mailery 0.14.0 → 0.16.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { ObjectId } from 'mongodb';
-import crypto2 from 'crypto';
+import crypto2, { randomBytes, createHash, timingSafeEqual } from 'crypto';
 import sgMail from '@sendgrid/mail';
 import IORedis from 'ioredis';
 import Handlebars from 'handlebars';
@@ -9,22 +9,22 @@ import mjml2html from 'mjml';
 import dns from 'dns/promises';
 import net from 'net';
 import psl from 'psl';
+import { XMLParser } from 'fast-xml-parser';
+import fs from 'fs';
+import path from 'path';
 import express, { Router } from 'express';
 import multer from 'multer';
-import path from 'path';
 import { fileURLToPath } from 'url';
-import fs from 'fs';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -240,6 +240,31 @@ var init_mongo = __esm({
   }
 });
 
+// src/server/providers/webhook-tolerance.ts
+function resolveWebhookToleranceSeconds(option) {
+  if (option === false || option === 0) return 0;
+  if (option === void 0 || option === null) return DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+  if (typeof option !== "number" || !Number.isFinite(option) || option < 0) {
+    return DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+  }
+  return option;
+}
+function isWebhookTimestampFresh(rawTimestamp, toleranceSeconds, now = /* @__PURE__ */ new Date()) {
+  if (toleranceSeconds === 0) return true;
+  if (!rawTimestamp) return false;
+  if (!/^\d{1,15}$/.test(rawTimestamp)) return false;
+  const timestampMs = Number(rawTimestamp) * 1e3;
+  if (!Number.isFinite(timestampMs)) return false;
+  const deltaMs = Math.abs(now.getTime() - timestampMs);
+  return deltaMs <= toleranceSeconds * 1e3;
+}
+var DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+var init_webhook_tolerance = __esm({
+  "src/server/providers/webhook-tolerance.ts"() {
+    DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+  }
+});
+
 // src/server/providers/sendgrid.ts
 var sendgrid_exports = {};
 __export(sendgrid_exports, {
@@ -286,6 +311,7 @@ function mapEventType(sgEvent) {
 var SG_SIG_HEADER, SG_TS_HEADER, SendGridProvider;
 var init_sendgrid = __esm({
   "src/server/providers/sendgrid.ts"() {
+    init_webhook_tolerance();
     SG_SIG_HEADER = "x-twilio-email-event-webhook-signature";
     SG_TS_HEADER = "x-twilio-email-event-webhook-timestamp";
     SendGridProvider = class {
@@ -293,10 +319,13 @@ var init_sendgrid = __esm({
         this.opts = opts;
         sgMail.setApiKey(opts.apiKey);
         this.sendRatePerSecond = opts.sendRatePerSecond ?? 10;
+        this.webhookToleranceSeconds = resolveWebhookToleranceSeconds(opts.webhookToleranceSeconds);
       }
       opts;
       name = "sendgrid";
       sendRatePerSecond;
+      /** Resolved replay window in seconds; `0` means the check is disabled. */
+      webhookToleranceSeconds;
       async send(args) {
         const msg = {
           to: args.to,
@@ -336,10 +365,11 @@ var init_sendgrid = __esm({
         try {
           const verifier = crypto2.createVerify("sha256");
           verifier.update(payload);
-          return verifier.verify(this.opts.webhookVerificationKey, sig, "base64");
+          if (!verifier.verify(this.opts.webhookVerificationKey, sig, "base64")) return false;
         } catch {
           return false;
         }
+        return isWebhookTimestampFresh(ts, this.webhookToleranceSeconds);
       }
       parseWebhookEvents(payload) {
         if (!Array.isArray(payload)) return [];
@@ -469,6 +499,10 @@ var flowStepSchema = z.lazy(
     }),
     z.object({
       type: z.literal("webhook"),
+      // `url` is validated for shape only and is deliberately never templated —
+      // see the comment on handleWebhookStep in src/server/runner/step.ts, and
+      // INVARIANT 16. Rendering contact/event data into this field would turn an
+      // admin-authored flow into a server-side request forgery primitive.
       url: z.string().url(),
       method: z.enum(["POST", "PUT"]).optional(),
       payload: z.record(z.string(), z.unknown()).optional(),
@@ -562,6 +596,7 @@ var DEFAULTS = {
   requireDoubleOptIn: false,
   unsubscribeTokenLifetimeDays: 90,
   transactionalRespectUnsubscribe: false,
+  unsubscribeWriteTimeoutMs: 5e3,
   doiTemplateSlug: "doi-confirmation",
   doiTokenLifetimeDays: 7,
   broadcastConfirmationThreshold: 1e3,
@@ -578,7 +613,9 @@ var DEFAULTS = {
   trackOpens: true,
   trackClicks: true,
   storeTrackingIp: false,
-  storeRenderedBody: false
+  storeRenderedBody: false,
+  requireSignedTrackingUrls: false,
+  trackingUrlLifetimeDays: 0
 };
 var CIRCUIT_BREAKER_DEFAULTS = {
   hardBounceRatePctTrip: 2,
@@ -595,6 +632,7 @@ function resolveConfig(c) {
     requireDoubleOptIn: c.requireDoubleOptIn ?? DEFAULTS.requireDoubleOptIn,
     unsubscribeTokenLifetimeDays: c.unsubscribeTokenLifetimeDays ?? DEFAULTS.unsubscribeTokenLifetimeDays,
     transactionalRespectUnsubscribe: c.transactionalRespectUnsubscribe ?? DEFAULTS.transactionalRespectUnsubscribe,
+    unsubscribeWriteTimeoutMs: c.unsubscribeWriteTimeoutMs ?? DEFAULTS.unsubscribeWriteTimeoutMs,
     doiTemplateSlug: c.doiTemplateSlug ?? DEFAULTS.doiTemplateSlug,
     doiTokenLifetimeDays: c.doiTokenLifetimeDays ?? DEFAULTS.doiTokenLifetimeDays,
     broadcastConfirmationThreshold: c.broadcastConfirmationThreshold ?? DEFAULTS.broadcastConfirmationThreshold,
@@ -612,6 +650,8 @@ function resolveConfig(c) {
     trackClicks: c.trackClicks ?? DEFAULTS.trackClicks,
     storeTrackingIp: c.storeTrackingIp ?? DEFAULTS.storeTrackingIp,
     storeRenderedBody: c.storeRenderedBody ?? DEFAULTS.storeRenderedBody,
+    requireSignedTrackingUrls: c.requireSignedTrackingUrls ?? DEFAULTS.requireSignedTrackingUrls,
+    trackingUrlLifetimeDays: c.trackingUrlLifetimeDays ?? DEFAULTS.trackingUrlLifetimeDays,
     circuitBreaker: { ...CIRCUIT_BREAKER_DEFAULTS, ...c.circuitBreaker ?? {} }
   };
 }
@@ -814,6 +854,22 @@ function isoDay(d) {
 function randomId() {
   return crypto2.randomBytes(8).toString("hex");
 }
+
+// src/server/provider-lookup.ts
+var PROVIDER_METHODS = ["send", "verifyWebhook", "parseWebhookEvents"];
+function isMailProvider(candidate) {
+  if (!candidate || typeof candidate !== "object") return false;
+  const p = candidate;
+  return PROVIDER_METHODS.every((m) => typeof p[m] === "function");
+}
+function resolveProvider(providers, name) {
+  if (typeof name !== "string" || !Object.hasOwn(providers, name)) return null;
+  const candidate = providers[name];
+  return isMailProvider(candidate) ? candidate : null;
+}
+function registeredProviderNames(providers) {
+  return Object.keys(providers).filter((name) => resolveProvider(providers, name) !== null).sort();
+}
 function signUnsubscribeToken(payload, secret) {
   const body = JSON.stringify({
     e: payload.email.toLowerCase(),
@@ -852,6 +908,28 @@ function verifyUnsubscribeToken(token, secret, now = /* @__PURE__ */ new Date())
     expiresAt: new Date(body.x)
   };
 }
+var TRACKING_SCOPES = ["open", "click"];
+var TRACKING_SIG_LENGTH = 12;
+function trackingMessage(scope, params) {
+  const tail = params.linkId === void 0 ? "" : `:${params.linkId}`;
+  return `mailery.track.v1:${scope}:${params.sendId}${tail}`;
+}
+function signTrackingToken(scope, params, secret) {
+  if (!TRACKING_SCOPES.includes(scope)) {
+    throw new Error(`signTrackingToken: unknown scope ${String(scope)}`);
+  }
+  const mac = crypto2.createHmac("sha256", secret).update(trackingMessage(scope, params)).digest();
+  return b64url(mac).slice(0, TRACKING_SIG_LENGTH);
+}
+function verifyTrackingToken(token, scope, params, secret) {
+  if (typeof token !== "string") return false;
+  if (!TRACKING_SCOPES.includes(scope)) return false;
+  if (token.length !== TRACKING_SIG_LENGTH) return false;
+  const expected = Buffer.from(signTrackingToken(scope, params, secret), "utf8");
+  const actual = Buffer.from(token, "utf8");
+  if (expected.length !== actual.length) return false;
+  return crypto2.timingSafeEqual(expected, actual);
+}
 function b64url(buf) {
   return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
@@ -895,6 +973,39 @@ function verifyDoiToken(token, secret, now = /* @__PURE__ */ new Date()) {
   if (body.x < now.getTime()) return null;
   return { externalId: body.i, expiresAt: new Date(body.x) };
 }
+
+// src/server/unsubscribe.ts
+async function applyUnsubscribe(collections, input, now = /* @__PURE__ */ new Date()) {
+  const normalized = input.email;
+  await collections.suppressions.updateOne(
+    { email: normalized, scope: input.scope },
+    {
+      $setOnInsert: {
+        email: normalized,
+        emailHash: sha256Hex(normalized),
+        scope: input.scope,
+        // mailer_suppressions canonical reason — see plans/02-data-model.md.
+        reason: "unsubscribed",
+        source: input.source,
+        notes: input.notes ?? null,
+        addedAt: now,
+        expiresAt: null
+      }
+    },
+    { upsert: true }
+  );
+  await collections.subscriptions.updateOne(
+    { emailAtSubscribe: normalized },
+    {
+      $set: {
+        status: "unsubscribed",
+        unsubscribedAt: now,
+        unsubscribeReason: input.reason,
+        updatedAt: now
+      }
+    }
+  );
+}
 var QUEUE_NAMES = {
   tick: "mailer-tick",
   advance: "mailer-advance",
@@ -1727,7 +1838,7 @@ async function suppressOnce(ctx, email, reason, scope) {
 }
 
 // src/server/runner/predicate.ts
-var BOT_UA_RE = /Mimecast|SafeLinks|proofpoint|HeadlessChrome|Googlebot|bingbot/i;
+var DEFAULT_BOT_UA_RE = /Mimecast|SafeLinks|proofpoint|HeadlessChrome|Googlebot|bingbot/i;
 async function evaluatePredicate(predicate, ctx) {
   const p = predicate;
   if ("hasTag" in p) return ctx.contact.tags.includes(p.hasTag);
@@ -1795,17 +1906,35 @@ async function openOrClickCount(ctx, kind, opts, excludeBots) {
     return await ctx.collections.sends.countDocuments(filter);
   }
   const docs = await ctx.collections.sends.find(filter).limit(1e3).toArray();
+  const botRe = ctx.botFilter?.userAgentPattern ?? DEFAULT_BOT_UA_RE;
+  const minOpenDelayMs = ctx.botFilter?.minOpenDelayMs ?? 0;
   let n = 0;
   for (const s of docs) {
-    if (kind === "opened") {
-      n++;
-      continue;
-    }
-    const hasHumanClick = s.clickedLinks?.some((c) => !c.userAgent || !BOT_UA_RE.test(c.userAgent));
-    if (hasHumanClick) n++;
+    const doc = s;
+    const human = kind === "opened" ? hasHumanOpen(doc, botRe, minOpenDelayMs) : (doc.clickedLinks ?? []).some((c) => !isBotUserAgent(c.userAgent, botRe));
+    if (human) n++;
   }
   return n;
 }
+function isBotUserAgent(ua, botRe) {
+  if (typeof ua !== "string" || ua.trim() === "") return false;
+  return botRe.test(ua);
+}
+function hasHumanOpen(send, botRe, minOpenDelayMs) {
+  const opens = send.opens && send.opens.length > 0 ? send.opens : send.openedAt ? [{ openedAt: send.openedAt, userAgent: null }] : [];
+  return opens.some((o) => {
+    if (isBotUserAgent(o.userAgent, botRe)) return false;
+    if (isPrefetchOpen(o.openedAt, send.queuedAt, minOpenDelayMs)) return false;
+    return true;
+  });
+}
+function isPrefetchOpen(openedAt, queuedAt, minOpenDelayMs) {
+  if (!minOpenDelayMs || minOpenDelayMs <= 0) return false;
+  if (!(openedAt instanceof Date) || !(queuedAt instanceof Date)) return false;
+  const delta = openedAt.getTime() - queuedAt.getTime();
+  if (!Number.isFinite(delta) || delta < 0) return false;
+  return delta < minOpenDelayMs;
+}
 function effectiveLowerBound(ctx, opts) {
   const now = ctx.now ?? /* @__PURE__ */ new Date();
   if (opts.sinceFlowStart) return ctx.run.enteredAt;
@@ -1971,12 +2100,14 @@ function applyTracking(html, opts) {
         seen.set(url, linkId);
         links.push({ linkId, url });
       }
-      const newHref = `${opts.publicUrl}/m/click/${opts.sendId}/${linkId}`;
+      const sig = opts.signingSecret ? `/${signTrackingToken("click", { sendId: opts.sendId, linkId }, opts.signingSecret)}` : "";
+      const newHref = `${opts.publicUrl}/m/click/${opts.sendId}/${linkId}${sig}`;
       return `<a${pre}href="${newHref}"${post}>`;
     });
   }
   if (opts.trackOpens) {
-    const pixel = `<img src="${opts.publicUrl}/m/open/${opts.sendId}.png" width="1" height="1" alt="" style="display:block;border:0" />`;
+    const sig = opts.signingSecret ? `.${signTrackingToken("open", { sendId: opts.sendId }, opts.signingSecret)}` : "";
+    const pixel = `<img src="${opts.publicUrl}/m/open/${opts.sendId}${sig}.png" width="1" height="1" alt="" style="display:block;border:0" />`;
     if (/<\/body>/i.test(out)) {
       out = out.replace(/<\/body>/i, `${pixel}</body>`);
     } else {
@@ -1987,14 +2118,22 @@ function applyTracking(html, opts) {
 }
 function shouldSkipClickRewrite(url, preserve, fullTag) {
   if (!url) return true;
-  if (url.startsWith("mailto:")) return true;
-  if (url.startsWith("tel:")) return true;
   if (url.startsWith("#")) return true;
   if (url.startsWith("{{") || url.startsWith("{")) return true;
   if (preserve.has(url.trim())) return true;
   if (/data-mailer-notrack=["']true["']/.test(fullTag)) return true;
+  if (!isHttpUrl(url)) return true;
   return false;
 }
+function isHttpUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url.trim());
+  } catch {
+    return false;
+  }
+  return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
 var NAMED_ENTITIES = {
   amp: "&",
   lt: "<",
@@ -2215,7 +2354,8 @@ async function dispatchSend(sendId, ctx) {
     publicUrl: ctx.config.publicUrl,
     trackOpens: template.trackOpens ?? ctx.config.trackOpens,
     trackClicks: template.trackClicks ?? ctx.config.trackClicks,
-    preserveUrls: [renderCtx.unsubscribeUrl]
+    preserveUrls: [renderCtx.unsubscribeUrl],
+    signingSecret: ctx.config.unsubscribeSecret
   });
   await ctx.collections.sends.updateOne(
     { _id: send._id },
@@ -2233,9 +2373,14 @@ async function dispatchSend(sendId, ctx) {
       }
     }
   );
-  const provider = ctx.providers[send.provider] ?? ctx.providers[ctx.config.defaultProvider];
+  const provider = resolveProvider(ctx.providers, send.provider);
   if (!provider) {
-    await markFailed(send._id, `provider_unknown: ${send.provider}`, ctx);
+    const known = registeredProviderNames(ctx.providers);
+    await markFailed(
+      send._id,
+      `provider_unknown: no provider is registered as "${send.provider}". Registered providers: ${known.length ? known.join(", ") : "(none)"}.`,
+      ctx
+    );
     return;
   }
   const headers = send.kind === "marketing" ? {
@@ -2434,7 +2579,7 @@ async function handleWait(run, step, ctx) {
 }
 async function handleCondition(run, step, contact, ctx) {
   if (!contact) return;
-  const result = await evaluatePredicate(step.test, { contact, run, collections: ctx.collections });
+  const result = await evaluatePredicate(step.test, { contact, run, collections: ctx.collections, botFilter: ctx.config.botFilter });
   if (result) {
     await advanceStep(run, ctx, { action: "condition_evaluated", details: { result: true } });
     return;
@@ -2447,7 +2592,7 @@ async function handleCondition(run, step, contact, ctx) {
 }
 async function handleBranch(run, step, contact, ctx) {
   if (!contact) return;
-  const result = await evaluatePredicate(step.test, { contact, run, collections: ctx.collections });
+  const result = await evaluatePredicate(step.test, { contact, run, collections: ctx.collections, botFilter: ctx.config.botFilter });
   const newPath = [...run.currentBranchPath, run.currentStepIndex, result ? "true" : "false", 0];
   const updated = await ctx.collections.flowRuns.findOneAndUpdate(
     { _id: run._id, currentStepIndex: run.currentStepIndex },
@@ -3591,8 +3736,6 @@ function nthSundayOfMonth(year, month0, n) {
   const firstSunday = 1 + (7 - dayOfWeek) % 7;
   return firstSunday + (n - 1) * 7;
 }
-
-// src/server/runner/dmarc.ts
 var MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
 function assertSafeZipEntryName(rawName) {
   if (typeof rawName !== "string" || rawName.length === 0) {
@@ -3666,7 +3809,6 @@ async function extractDmarcXmls(buffer, filename) {
   return [buffer.toString("utf8")];
 }
 function parseDmarcReport(xml) {
-  const { XMLParser } = __require("fast-xml-parser");
   const parser = new XMLParser({
     ignoreAttributes: false,
     parseAttributeValue: false,
@@ -3757,7 +3899,7 @@ function toArray(v) {
   if (v === void 0 || v === null) return [];
   return Array.isArray(v) ? v : [v];
 }
-async function ingestDmarcAttachment(ctx, buffer, filename) {
+async function ingestDmarcAttachment(ctx, buffer, filename, opts = {}) {
   const xmls = await extractDmarcXmls(buffer, filename);
   if (xmls.length === 0) throw new Error("attachment contained no XML payload");
   const results = [];
@@ -3765,6 +3907,9 @@ async function ingestDmarcAttachment(ctx, buffer, filename) {
   for (const xml of xmls) {
     try {
       const parsed = parseDmarcReport(xml);
+      if (opts.allowDomain && !opts.allowDomain(parsed.report.domain)) {
+        throw new Error(`DMARC report is for domain "${parsed.report.domain}", which this deployment does not send from`);
+      }
       results.push(await ingestParsedDmarcReport(ctx, parsed));
     } catch (err) {
       if (!firstError) firstError = err;
@@ -3875,6 +4020,260 @@ function suggestPolicyProgression(input) {
   }
   return null;
 }
+var DRAINING_INFIX = ".draining.";
+var ADOPT_AFTER_MS = 5 * 60 * 1e3;
+var JOURNAL_WARN_BYTES = 8 * 1024 * 1024;
+var O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+var APPEND_FLAGS = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | O_NOFOLLOW;
+function appendPendingUnsub(journalPath, entry) {
+  fs.mkdirSync(path.dirname(journalPath), { recursive: true, mode: 448 });
+  const fd = fs.openSync(journalPath, APPEND_FLAGS, 384);
+  try {
+    assertPrivateRegularFile(fd, journalPath);
+    fs.writeSync(fd, serializeEntry(entry));
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function assertPrivateRegularFile(fd, journalPath) {
+  const st = fs.fstatSync(fd);
+  if (!st.isFile()) {
+    throw new Error(`pending-unsubscribe journal is not a regular file: ${journalPath}`);
+  }
+  if (st.nlink > 1) {
+    throw new Error(`pending-unsubscribe journal has ${st.nlink} hard links: ${journalPath}`);
+  }
+  if ((st.mode & 63) !== 0) fs.fchmodSync(fd, 384);
+}
+function serializeEntry(entry) {
+  return JSON.stringify(entry) + "\n";
+}
+function claimToken() {
+  return `${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+}
+function claimJournal(journalPath) {
+  const claimed = `${journalPath}${DRAINING_INFIX}${claimToken()}`;
+  try {
+    fs.renameSync(journalPath, claimed);
+  } catch (err) {
+    if (isMissing(err)) return null;
+    throw err;
+  }
+  markClaimActive(claimed);
+  return claimed;
+}
+function markClaimActive(claimPath) {
+  const now = /* @__PURE__ */ new Date();
+  try {
+    fs.utimesSync(claimPath, now, now);
+  } catch (err) {
+    if (!isMissing(err)) throw err;
+  }
+}
+function adoptAbandonedClaims(journalPath, opts = {}) {
+  const olderThanMs = opts.olderThanMs ?? ADOPT_AFTER_MS;
+  const now = opts.now ?? Date.now();
+  const dir = path.dirname(journalPath);
+  const prefix = path.basename(journalPath) + DRAINING_INFIX;
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (err) {
+    if (isMissing(err)) return [];
+    throw err;
+  }
+  const adopted = [];
+  for (const name of names) {
+    if (!name.startsWith(prefix)) continue;
+    const full = path.join(dir, name);
+    let st;
+    try {
+      st = fs.statSync(full);
+    } catch (err) {
+      if (isMissing(err)) continue;
+      throw err;
+    }
+    if (!st.isFile()) continue;
+    if (now - st.mtimeMs < olderThanMs) continue;
+    const mine = `${journalPath}${DRAINING_INFIX}${claimToken()}`;
+    try {
+      fs.renameSync(full, mine);
+      markClaimActive(mine);
+      adopted.push(mine);
+    } catch (err) {
+      if (!isMissing(err)) throw err;
+    }
+  }
+  return adopted;
+}
+function readClaim(claimPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(claimPath, "utf8");
+  } catch (err) {
+    if (isMissing(err)) return { entries: [], malformed: [], bytes: 0 };
+    throw err;
+  }
+  const entries = [];
+  const malformed = [];
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;
+    const parsed = parseEntry(line);
+    if (parsed) entries.push(parsed);
+    else malformed.push({ lineNumber: i + 1, preview: line.slice(0, 120) });
+  }
+  return { entries, malformed, bytes: Buffer.byteLength(raw) };
+}
+function parseEntry(line) {
+  let obj;
+  try {
+    obj = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return null;
+  const o = obj;
+  const check = unsubscribeInputSchema.safeParse({
+    email: o.email,
+    scope: o.scope,
+    reason: "user_request",
+    source: "one-click"
+  });
+  if (!check.success) return null;
+  const at = typeof o.at === "number" && Number.isFinite(o.at) ? o.at : Date.now();
+  const attempts = typeof o.attempts === "number" && Number.isFinite(o.attempts) && o.attempts > 0 ? Math.floor(o.attempts) : void 0;
+  return {
+    email: check.data.email,
+    scope: check.data.scope,
+    at,
+    ...attempts === void 0 ? {} : { attempts }
+  };
+}
+function entryToInput(entry) {
+  return unsubscribeInputSchema.parse({
+    email: entry.email,
+    scope: entry.scope,
+    reason: "user_request",
+    // Distinguishable in `mailer_suppressions.source` from a live one-click,
+    // but only on rows the drain actually created (the upsert is
+    // `$setOnInsert`, so a row the live path already wrote keeps its own).
+    source: "one-click-drain"
+  });
+}
+function releaseClaim(journalPath, claimPath, remaining) {
+  if (remaining.length > 0) {
+    fs.mkdirSync(path.dirname(journalPath), { recursive: true, mode: 448 });
+    const fd = fs.openSync(journalPath, APPEND_FLAGS, 384);
+    try {
+      assertPrivateRegularFile(fd, journalPath);
+      fs.writeSync(
+        fd,
+        remaining.map((e) => serializeEntry({ ...e, attempts: (e.attempts ?? 0) + 1 })).join("")
+      );
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  try {
+    fs.unlinkSync(claimPath);
+  } catch (err) {
+    if (!isMissing(err)) throw err;
+  }
+}
+function journalExists(journalPath) {
+  try {
+    return fs.statSync(journalPath).isFile();
+  } catch (err) {
+    if (isMissing(err)) return false;
+    throw err;
+  }
+}
+function isMissing(err) {
+  const code = err?.code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+// src/server/runner/pending-unsubs.ts
+var MAX_ENTRIES_PER_PASS = 1e3;
+var NOISY_AFTER_ATTEMPTS = 10;
+var consoleLog = {
+  warn: (fields, msg) => console.warn(msg ?? "mailery", fields),
+  error: (fields, msg) => console.error(msg ?? "mailery", fields)
+};
+async function drainPendingUnsubscribes(ctx, opts = {}) {
+  const journalPath = opts.path ?? ctx.config.pendingUnsubsPath;
+  const result = {
+    enabled: Boolean(journalPath),
+    applied: 0,
+    deferred: 0,
+    malformed: 0,
+    batches: 0
+  };
+  if (!journalPath) return result;
+  const log = opts.log ?? consoleLog;
+  const budget = opts.maxEntries ?? MAX_ENTRIES_PER_PASS;
+  const claims = [];
+  try {
+    claims.push(...adoptAbandonedClaims(journalPath));
+  } catch (err) {
+    log.error?.({ err, path: journalPath }, "mailery: pending-unsub claim adoption failed");
+  }
+  if (journalExists(journalPath)) {
+    const claimed = claimJournal(journalPath);
+    if (claimed) claims.push(claimed);
+  }
+  if (claims.length === 0) return result;
+  let remainingBudget = budget;
+  for (const claimPath of claims) {
+    result.batches++;
+    const batch = readClaim(claimPath);
+    if (batch.bytes > JOURNAL_WARN_BYTES) {
+      log.warn?.(
+        { path: claimPath, bytes: batch.bytes, entries: batch.entries.length },
+        "mailery: pending-unsubscribe journal is large \u2014 Mongo has been unreachable for a while"
+      );
+    }
+    for (const bad of batch.malformed) {
+      result.malformed++;
+      log.warn?.(
+        { path: claimPath, lineNumber: bad.lineNumber, preview: bad.preview },
+        "mailery: pending-unsubscribe journal line unusable \u2014 skipped"
+      );
+    }
+    const deferred = [];
+    let stop = false;
+    for (let i = 0; i < batch.entries.length; i++) {
+      const entry = batch.entries[i];
+      if (stop || remainingBudget <= 0) {
+        deferred.push(entry);
+        continue;
+      }
+      try {
+        await applyUnsubscribe(ctx.collections, entryToInput(entry));
+        result.applied++;
+        remainingBudget--;
+      } catch (err) {
+        stop = true;
+        deferred.push(entry);
+        const attempts = (entry.attempts ?? 0) + 1;
+        const fields = { err, path: claimPath, attempts, pending: batch.entries.length - i };
+        if (attempts >= NOISY_AFTER_ATTEMPTS) {
+          log.error?.(
+            fields,
+            "mailery: pending unsubscribe still not applied after repeated attempts \u2014 investigate"
+          );
+        } else {
+          log.warn?.(fields, "mailery: pending-unsubscribe replay failed \u2014 deferred to next tick");
+        }
+      }
+    }
+    result.deferred += deferred.length;
+    releaseClaim(journalPath, claimPath, deferred);
+  }
+  return result;
+}
 
 // src/server/runner/tick.ts
 var STRANDED_SEND_THRESHOLD_MS = 5 * 60 * 1e3;
@@ -3916,6 +4315,9 @@ async function runTick(ctx) {
   await drainOutbox(ctx).catch((err) => {
     console.error("mailery: outbox drain failed", err);
   });
+  await drainPendingUnsubscribes(ctx).catch((err) => {
+    console.error("mailery: pending-unsubscribe drain failed", err);
+  });
   await processScheduledBroadcasts2(ctx).catch((err) => {
     console.error("mailery: broadcast dispatch failed", err);
   });
@@ -4048,6 +4450,10 @@ var Mailer = class _Mailer {
    *   MAILER_FROM_NAME / MAILER_FROM_EMAIL
    *   MAILER_DEFAULT_PROVIDER           — defaults to 'sendgrid' if SENDGRID_API_KEY is set
    *   MAILER_SENDGRID_API_KEY / MAILER_SENDGRID_WEBHOOK_KEY
+   *   MAILER_SENDGRID_WEBHOOK_TOLERANCE — signed-webhook replay window, seconds
+   *                                       (default 300; '0' disables the check).
+   *                                       Unparseable values fall back to the
+   *                                       default rather than disabling it.
    *   MAILER_HOST_USERS_COLLECTION (default 'users')
    *   MAILER_HOST_USERS_EMAIL_FIELD (default 'email')
    *   MAILER_HOST_USERS_ID_FIELD (default '_id')
@@ -4082,6 +4488,10 @@ var Mailer = class _Mailer {
       providers.sendgrid = new SendGridProvider2({
         apiKey: env.MAILER_SENDGRID_API_KEY,
         webhookVerificationKey: env.MAILER_SENDGRID_WEBHOOK_KEY,
+        // Left undefined when unset/blank so the provider default (300s) applies.
+        // resolveWebhookToleranceSeconds() rejects NaN back to the default, so a
+        // typo here can never silently switch the replay check off.
+        webhookToleranceSeconds: env.MAILER_SENDGRID_WEBHOOK_TOLERANCE ? Number(env.MAILER_SENDGRID_WEBHOOK_TOLERANCE) : void 0,
         sandbox: env.NODE_ENV !== "production"
       });
     }
@@ -4109,8 +4519,15 @@ var Mailer = class _Mailer {
   }
   static async init(input) {
     const config = resolveConfig(input);
-    if (!config.providers[config.defaultProvider]) {
-      throw new Error(`defaultProvider "${config.defaultProvider}" not in providers map`);
+    if (!resolveProvider(config.providers, config.defaultProvider)) {
+      throw new Error(
+        `defaultProvider "${config.defaultProvider}" is not a registered provider. Registered: ${registeredProviderNames(config.providers).join(", ") || "(none)"}`
+      );
+    }
+    if (config.defaultTransactionalProvider != null && !resolveProvider(config.providers, config.defaultTransactionalProvider)) {
+      throw new Error(
+        `defaultTransactionalProvider "${config.defaultTransactionalProvider}" is not a registered provider. Registered: ${registeredProviderNames(config.providers).join(", ") || "(none)"}`
+      );
     }
     if (config.varsAdapter) {
       const { assertNoReservedVarKeys: assertNoReservedVarKeys2 } = await Promise.resolve().then(() => (init_vars(), vars_exports));
@@ -4252,38 +4669,14 @@ var Mailer = class _Mailer {
       }
     }
   }
+  /**
+   * The writes live in `server/unsubscribe.ts` so the pending-unsubscribe
+   * drain (INVARIANT 8) replays a journaled opt-out through exactly this path
+   * without holding a `Mailer` instance.
+   */
   async unsubscribe(email, opts) {
     const parsed = unsubscribeInputSchema.parse({ email, ...opts });
-    const normalized = parsed.email;
-    const now = /* @__PURE__ */ new Date();
-    await this.collections.suppressions.updateOne(
-      { email: normalized, scope: parsed.scope },
-      {
-        $setOnInsert: {
-          email: normalized,
-          emailHash: sha256Hex(normalized),
-          scope: parsed.scope,
-          // mailer_suppressions canonical reason — see plans/02-data-model.md.
-          reason: "unsubscribed",
-          source: parsed.source,
-          notes: parsed.notes ?? null,
-          addedAt: now,
-          expiresAt: null
-        }
-      },
-      { upsert: true }
-    );
-    await this.collections.subscriptions.updateOne(
-      { emailAtSubscribe: normalized },
-      {
-        $set: {
-          status: "unsubscribed",
-          unsubscribedAt: now,
-          unsubscribeReason: parsed.reason,
-          updatedAt: now
-        }
-      }
-    );
+    await applyUnsubscribe(this.collections, parsed);
   }
   async suppress(email, opts) {
     const parsed = suppressInputSchema.parse({ email, ...opts });
@@ -4619,8 +5012,20 @@ var NullProvider = class {
       status: "accepted"
     };
   }
+  /**
+   * Fails closed. This provider has no signing key, so it can never establish
+   * that an inbound payload is authentic — and a method whose entire job is to
+   * reject unauthenticated input must not answer "yes" by default. Returning
+   * `true` here would mean any unsigned body posted to the webhook route is
+   * accepted as genuine whenever the null provider is registered, which is
+   * exactly the dev/staging configuration where that is easiest to miss.
+   *
+   * Nothing is lost: `parseWebhookEvents()` returns `[]`, so there was never
+   * any inbound behaviour to preserve. To exercise the inbound half locally,
+   * use a provider that actually signs (see `test/README.md`).
+   */
   async verifyWebhook() {
-    return true;
+    return false;
   }
   parseWebhookEvents() {
     return [];
@@ -5757,13 +6162,13 @@ function createAdminRouter(mailer, opts = {}) {
     req.actor = getActor(req);
     next();
   });
-  router.use("/api", apiRouter(mailer, opts));
+  router.use("/api", createAdminApiRouter(mailer, opts));
   router.get(/.*/, (_req, res) => {
     res.sendFile(path.join(spaDir, "index.html"));
   });
   return router;
 }
-function apiRouter(mailer, opts = {}) {
+function createAdminApiRouter(mailer, opts = {}) {
   const r = Router();
   const c = mailer.collections;
   const varsSchema = mailer.config.varsAdapter ? varsJsonSchema(mailer.config.varsAdapter) : null;
@@ -5960,7 +6365,11 @@ function apiRouter(mailer, opts = {}) {
     asyncHandler(async (req, res) => {
       const before = await c.flows.findOne({ slug: req.params.slug });
       if (!before) return res.status(404).json({ error: "not_found" });
-      await c.flows.updateOne({ _id: before._id }, { $set: { enabled: true, updatedAt: /* @__PURE__ */ new Date() } });
+      const now = /* @__PURE__ */ new Date();
+      await c.flows.updateOne(
+        { _id: before._id },
+        { $set: { enabled: true, updatedAt: now, ...before.lastTriggerScanAt ? {} : { lastTriggerScanAt: now } } }
+      );
       await mailer.audit({
         actor: req.actor,
         action: "flow.resume",
@@ -6541,6 +6950,7 @@ function apiRouter(mailer, opts = {}) {
       if (!Array.isArray(draftSteps) || draftSteps.length === 0) {
         return res.status(400).json({ error: "empty_flow", message: "flow has no steps to publish" });
       }
+      const enable = req.body?.enable !== false;
       const nextVersion = (flow.version ?? 0) + 1;
       const now = /* @__PURE__ */ new Date();
       await c.flowVersions.insertOne({
@@ -6557,11 +6967,14 @@ function apiRouter(mailer, opts = {}) {
           $set: {
             steps: draftSteps,
             version: nextVersion,
-            enabled: true,
+            enabled: enable ? true : flow.enabled,
             draft: null,
             publishedAt: now,
             publishedBy: req.actor,
-            updatedAt: now
+            updatedAt: now,
+            // First enable: stamp the trigger watermark so the scan does not
+            // replay every event since the flow document was created.
+            ...enable && !flow.lastTriggerScanAt ? { lastTriggerScanAt: now } : {}
           }
         }
       );
@@ -6569,9 +6982,9 @@ function apiRouter(mailer, opts = {}) {
         actor: req.actor,
         action: "flow.publish",
         resource: { collection: "mailer_flows", id: flow._id, slug: flow.slug },
-        diffSummary: `Published v${nextVersion}`
+        diffSummary: `Published v${nextVersion}${enable ? "" : " (left disabled)"}`
       });
-      return res.json({ ok: true, version: nextVersion });
+      return res.json({ ok: true, version: nextVersion, enabled: enable ? true : flow.enabled });
     })
   );
   r.delete(
@@ -6762,11 +7175,11 @@ function apiRouter(mailer, opts = {}) {
       if (cached) {
         return res.json({ cached: true, status: "ready", score: cached });
       }
-      const { checkId, emailAddress } = await client.provisionCheck();
-      const provider = mailer.providers[tpl.providerOverride ?? mailer.config.defaultProvider];
+      const provider = resolveProvider(mailer.providers, tpl.providerOverride ?? mailer.config.defaultProvider);
       if (!provider) {
-        return res.status(500).json({ error: "provider_unknown", message: `default provider ${mailer.config.defaultProvider} is not registered` });
+        return res.status(400).json(unknownProviderError(mailer, tpl));
       }
+      const { checkId, emailAddress } = await client.provisionCheck();
       try {
         await provider.send({
           to: emailAddress,
@@ -7115,7 +7528,10 @@ function apiRouter(mailer, opts = {}) {
         trackOpens: false,
         trackClicks: false
       });
-      const provider = mailer.providers[tpl.providerOverride ?? mailer.config.defaultProvider];
+      const provider = resolveProvider(mailer.providers, tpl.providerOverride ?? mailer.config.defaultProvider);
+      if (!provider) {
+        return res.status(400).json(unknownProviderError(mailer, tpl));
+      }
       const result = await provider.send({
         to,
         fromName: rendered.fromName,
@@ -7267,6 +7683,18 @@ function asyncHandler(fn) {
     fn(req, res, next).catch(next);
   };
 }
+function unknownProviderError(mailer, tpl) {
+  const override = tpl.providerOverride ?? null;
+  const name = override ?? mailer.config.defaultProvider;
+  const known = registeredProviderNames(mailer.providers);
+  const source = override ? `template "${tpl.slug ?? "?"}" overrides the provider to "${name}"` : `the configured defaultProvider is "${name}"`;
+  return {
+    error: "provider_unknown",
+    message: `${source}, but no such provider is registered. Registered providers: ${known.length ? known.join(", ") : "(none)"}.`,
+    provider: name,
+    registeredProviders: known
+  };
+}
 async function collectQueueCounts(mailer) {
   const qs = Object.values(mailer.queues);
   const sum = async (key) => {
@@ -7402,81 +7830,1690 @@ async function computeBroadcastStats(mailer, idFilter) {
   }
   return out;
 }
-var PIXEL = Buffer.from(
-  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
-  "base64"
-);
-function createPublicRouter(mailer, opts = {}) {
-  const router = Router();
-  const pendingUnsubsPath = opts.pendingUnsubsPath ?? "/tmp/mailery-pending-unsubs.jsonl";
-  router.use(
-    "/webhooks",
-    express.json({
-      limit: "5mb",
-      verify: (req, _res, buf) => {
-        req.rawBody = buf;
-      }
-    })
-  );
-  router.use("/unsub", express.urlencoded({ extended: false }));
-  router.get("/open/:sendId.png", async (req, res) => {
-    res.setHeader("Content-Type", "image/png");
-    res.setHeader("Content-Length", String(PIXEL.length));
-    res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate, max-age=0");
-    res.status(200).end(PIXEL);
-    const id = req.params.sendId;
-    if (!ObjectId.isValid(id)) return;
-    const sendId = new ObjectId(id);
+
+// src/server/api/wrap.ts
+var consoleRouteLogger = {
+  error(fields, msg) {
+    console.error(msg ?? "mailery: request failed", fields);
+  },
+  warn(fields, msg) {
+    console.warn(msg ?? "mailery: request warning", fields);
+  },
+  info(fields, msg) {
+    console.info(msg ?? "mailery: request", fields);
+  }
+};
+function wrap(logger, handler) {
+  return async (req, res, next) => {
     try {
-      const send = await mailer.collections.sends.findOne({ _id: sendId }, { projection: { openedAt: 1 } });
-      if (!send) return;
-      await mailer.collections.sends.updateOne(
-        { _id: sendId },
-        {
-          $set: {
-            openedAt: send.openedAt ?? /* @__PURE__ */ new Date(),
-            status: "delivered"
-          },
-          $inc: { openCount: 1 }
-        }
-      );
+      await handler(req, res, next);
     } catch (err) {
-      console.error("mailery: open pixel update failed", err);
+      logger.error?.({ err, path: req.originalUrl }, "mailery: request failed");
+      if (res.headersSent) return;
+      res.status(500).json({ error: "internal_error" });
     }
-  });
-  router.get("/click/:sendId/:linkId", async (req, res) => {
-    const { sendId: sendIdStr, linkId } = req.params;
-    if (!ObjectId.isValid(sendIdStr)) return res.status(400).end();
-    const sendId = new ObjectId(sendIdStr);
-    const send = await mailer.collections.sends.findOne(
-      { _id: sendId },
-      { projection: { links: 1, firstClickAt: 1 } }
+  };
+}
+
+// src/server/api/agent.ts
+init_vars();
+
+// src/server/runner/arm.ts
+var FlowOperationError = class extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "FlowOperationError";
+  }
+  code;
+  status;
+};
+async function stampWatermarkIfNull(collections, flow, now = /* @__PURE__ */ new Date()) {
+  if (flow.lastTriggerScanAt) return flow.lastTriggerScanAt;
+  await collections.flows.updateOne(
+    { _id: flow._id, lastTriggerScanAt: null },
+    { $set: { lastTriggerScanAt: now, updatedAt: now } }
+  );
+  return now;
+}
+async function armFlow(mailer, slug, opts) {
+  const c = mailer.collections;
+  const flow = await c.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  if (!Array.isArray(flow.steps) || flow.steps.length === 0) {
+    throw new FlowOperationError(
+      "no_live_steps",
+      `flow "${slug}" (v${flow.version}) has no published steps \u2014 publish it first; an empty flow completes every run instantly`,
+      409
     );
-    if (!send) return res.status(404).end();
-    const link = (send.links ?? []).find((l) => l.linkId === linkId);
-    if (!link) return res.status(404).end();
-    res.redirect(302, link.url);
-    try {
-      await mailer.collections.sends.updateOne(
-        { _id: sendId },
-        {
-          $set: { firstClickAt: send.firstClickAt ?? /* @__PURE__ */ new Date() },
-          $inc: { clickCount: 1 },
-          $push: {
-            clickedLinks: {
-              url: link.url,
-              linkId,
-              clickedAt: /* @__PURE__ */ new Date()
-            }
-          }
-        }
-      );
-    } catch (err) {
-      console.error("mailery: click recording failed", err);
-    }
+  }
+  const eventName = flow.trigger?.eventName ?? null;
+  const now = /* @__PURE__ */ new Date();
+  const watermark = opts.since ?? now;
+  if (flow.enabled) {
+    return {
+      slug,
+      version: flow.version,
+      armed: false,
+      alreadyEnabled: true,
+      watermark: flow.lastTriggerScanAt ?? null,
+      eventName,
+      skippedEvents: 0,
+      pendingEvents: 0
+    };
+  }
+  const previous = flow.lastTriggerScanAt ?? flow.createdAt;
+  const overlapFrom = new Date(watermark.getTime() - SCAN_OVERLAP_MS);
+  const [skippedEvents, pendingEvents] = eventName ? await Promise.all([
+    c.events.countDocuments({ name: eventName, createdAt: { $gt: previous, $lte: overlapFrom } }),
+    c.events.countDocuments({ name: eventName, createdAt: { $gt: overlapFrom } })
+  ]) : [0, 0];
+  const res = await c.flows.updateOne(
+    { _id: flow._id, enabled: false },
+    { $set: { enabled: true, lastTriggerScanAt: watermark, updatedAt: now } }
+  );
+  if (res.modifiedCount === 0) {
+    const again = await c.flows.findOne({ _id: flow._id });
+    return {
+      slug,
+      version: flow.version,
+      armed: false,
+      alreadyEnabled: !!again?.enabled,
+      watermark: again?.lastTriggerScanAt ?? null,
+      eventName,
+      skippedEvents: 0,
+      pendingEvents: 0
+    };
+  }
+  await mailer.audit({
+    actor: opts.actor,
+    action: "flow.arm",
+    resource: { collection: "mailer_flows", id: flow._id, slug },
+    diffSummary: `Enabled v${flow.version} with lastTriggerScanAt=${watermark.toISOString()} (skipped ${skippedEvents} earlier ${eventName ?? "trigger"} event(s), ${pendingEvents} pending)`
   });
-  router.get("/unsub/:token", (req, res) => {
-    const decoded = verifyUnsubscribeToken(req.params.token, mailer.config.unsubscribeSecret);
+  return {
+    slug,
+    version: flow.version,
+    armed: true,
+    alreadyEnabled: false,
+    watermark,
+    eventName,
+    skippedEvents,
+    pendingEvents
+  };
+}
+async function disarmFlow(mailer, slug, actor) {
+  const c = mailer.collections;
+  const flow = await c.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  if (!flow.enabled) return { slug, disarmed: false };
+  await c.flows.updateOne({ _id: flow._id }, { $set: { enabled: false, updatedAt: /* @__PURE__ */ new Date() } });
+  await mailer.audit({
+    actor,
+    action: "flow.pause",
+    resource: { collection: "mailer_flows", id: flow._id, slug },
+    diffSummary: "Disarmed (enabled: false); in-flight runs continue"
+  });
+  return { slug, disarmed: true };
+}
+function isCanaryGate(step) {
+  const s = step;
+  return !!s && s.type === "condition" && s.canaryGate === true;
+}
+function gateStep(tag) {
+  return { type: "condition", test: { hasTag: tag }, ifFalse: "exit", canaryGate: true };
+}
+async function publishVersion(mailer, flow, steps, actor, summary) {
+  const c = mailer.collections;
+  const nextVersion = (flow.version ?? 0) + 1;
+  const now = /* @__PURE__ */ new Date();
+  await c.flowVersions.insertOne({
+    flowId: flow._id,
+    version: nextVersion,
+    steps,
+    trigger: flow.trigger,
+    publishedAt: now,
+    publishedBy: actor
+  });
+  await c.flows.updateOne(
+    { _id: flow._id },
+    { $set: { steps, version: nextVersion, draft: null, publishedAt: now, publishedBy: actor, updatedAt: now } }
+  );
+  await mailer.audit({
+    actor,
+    action: "flow.publish",
+    resource: { collection: "mailer_flows", id: flow._id, slug: flow.slug },
+    diffSummary: `Published v${nextVersion}: ${summary}`
+  });
+  return { version: nextVersion };
+}
+async function gateFlow(mailer, slug, opts) {
+  const tag = String(opts.tag ?? "").trim();
+  if (!tag) throw new FlowOperationError("tag_required", "a canary tag is required");
+  const flow = await mailer.collections.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  const live = Array.isArray(flow.steps) ? flow.steps : [];
+  if (live.length === 0) {
+    throw new FlowOperationError("no_live_steps", `flow "${slug}" has no published steps to gate`, 409);
+  }
+  if (isCanaryGate(live[0])) {
+    throw new FlowOperationError(
+      "already_gated",
+      `flow "${slug}" v${flow.version} is already gated on "${live[0].test.hasTag}" \u2014 ungate first`,
+      409
+    );
+  }
+  await mailer.collections.flowVersions.updateOne(
+    { flowId: flow._id, version: flow.version },
+    {
+      $setOnInsert: {
+        flowId: flow._id,
+        version: flow.version,
+        steps: live,
+        trigger: flow.trigger,
+        publishedAt: flow.publishedAt ?? flow.updatedAt ?? /* @__PURE__ */ new Date(),
+        publishedBy: flow.publishedBy ?? "unknown"
+      }
+    },
+    { upsert: true }
+  );
+  const { version } = await publishVersion(
+    mailer,
+    flow,
+    [gateStep(tag), ...live],
+    opts.actor,
+    `canary gate on tag "${tag}"`
+  );
+  return { slug, version, tag, enabled: flow.enabled };
+}
+async function ungateFlow(mailer, slug, opts) {
+  const c = mailer.collections;
+  const flow = await c.flows.findOne({ slug });
+  if (!flow) throw new FlowOperationError("not_found", `no flow with slug "${slug}"`, 404);
+  const live = Array.isArray(flow.steps) ? flow.steps : [];
+  if (!isCanaryGate(live[0])) {
+    throw new FlowOperationError("not_gated", `flow "${slug}" v${flow.version} is not gated`, 409);
+  }
+  const versions = await c.flowVersions.find({ flowId: flow._id }).sort({ version: -1 }).toArray();
+  const clean = versions.find((v) => Array.isArray(v.steps) && v.steps.length > 0 && !isCanaryGate(v.steps[0]));
+  if (!clean) {
+    throw new FlowOperationError(
+      "no_ungated_version",
+      `flow "${slug}" has no ungated version in mailer_flow_versions to restore`,
+      409
+    );
+  }
+  const { version } = await publishVersion(
+    mailer,
+    flow,
+    clean.steps,
+    opts.actor,
+    `restored steps of v${clean.version} (canary gate removed)`
+  );
+  return { slug, version, restoredFrom: clean.version, enabled: flow.enabled };
+}
+var MAX_STEPS = 1e3;
+async function simulateFlow(flow, contact, ctx, opts = {}) {
+  const enteredAt = opts.at ?? /* @__PURE__ */ new Date();
+  const steps = opts.steps ?? flow.steps ?? [];
+  const eventName = flow.trigger?.eventName ?? "simulated";
+  const eventProperties = opts.eventProperties ?? {};
+  const reasons = [];
+  if (!flow.enabled) reasons.push("flow is disabled (enabled: false)");
+  const sub = await ctx.collections.subscriptions.findOne({ externalId: contact.externalId });
+  if (!sub) reasons.push("contact has no subscription row \u2014 the trigger scan requires one");
+  else if (sub.status !== "subscribed") reasons.push(`subscription status is "${sub.status}", not "subscribed"`);
+  if (flow.trigger?.once) {
+    const existing = await ctx.collections.flowRuns.findOne(
+      { externalId: contact.externalId, flowId: flow._id },
+      { projection: { _id: 1, status: 1 } }
+    );
+    if (existing) reasons.push(`trigger.once is true and the contact already has a run (${existing.status})`);
+  }
+  if (steps.length === 0) reasons.push("flow has no live steps \u2014 a run would complete immediately");
+  const run = {
+    _id: new ObjectId(),
+    externalId: contact.externalId,
+    flowId: flow._id,
+    flowSlug: flow.slug,
+    flowVersion: flow.version,
+    emailAtEntry: contact.email,
+    triggerEvent: { name: eventName, properties: eventProperties, occurredAt: enteredAt },
+    triggerDedupeKey: null,
+    enteredAt,
+    status: "active",
+    currentStepIndex: 0,
+    currentBranchPath: [],
+    nextActionAt: enteredAt,
+    attemptsForCurrentStep: 0,
+    history: [],
+    exitedAt: null,
+    exitReason: null,
+    createdAt: enteredAt,
+    updatedAt: enteredAt
+  };
+  const path3 = [];
+  const sends = [];
+  let list = steps;
+  let index = 0;
+  let branchPath = [];
+  let t = enteredAt;
+  let terminal = null;
+  const record = (type, outcome, detail) => {
+    path3.push({ at: t, stepIndex: index, branchPath: [...branchPath], type, outcome, ...detail ? { detail } : {} });
+  };
+  const predicateCtx = () => ({
+    contact,
+    run: { ...run, currentStepIndex: index, currentBranchPath: branchPath, nextActionAt: t },
+    collections: ctx.collections,
+    now: t,
+    botFilter: ctx.config.botFilter
+  });
+  for (let guard = 0; guard < MAX_STEPS && !terminal; guard += 1) {
+    const step = list[index];
+    if (!step) {
+      terminal = { kind: "completed", reason: "sequence_complete", at: t };
+      break;
+    }
+    switch (step.type) {
+      case "wait": {
+        const ms = unitToMs2(step.value, step.unit);
+        record("wait", "waited", { value: step.value, unit: step.unit, until: new Date(t.getTime() + ms) });
+        t = new Date(t.getTime() + ms);
+        index += 1;
+        break;
+      }
+      case "condition": {
+        const result = await evaluatePredicate(step.test, predicateCtx());
+        if (result) {
+          record("condition", "passed", { test: step.test, result });
+          index += 1;
+        } else if (step.ifFalse === "continue") {
+          record("condition", "skipped_next", { test: step.test, result });
+          index += 2;
+        } else {
+          record("condition", "exited", { test: step.test, result });
+          terminal = { kind: "exited", reason: "condition_false", at: t };
+        }
+        break;
+      }
+      case "branch": {
+        const result = await evaluatePredicate(step.test, predicateCtx());
+        record("branch", result ? "branch_true" : "branch_false", { test: step.test, result });
+        branchPath = [...branchPath, index, result ? "true" : "false", 0];
+        list = result ? step.ifTrueSteps : step.ifFalseSteps;
+        index = 0;
+        break;
+      }
+      case "send": {
+        let at = t;
+        if (step.delivery) {
+          at = computeDeliveryTime(t, step.delivery, contact.timezone);
+        }
+        if (at.getTime() > t.getTime() + 3e4) {
+          record("send", "send_deferred", { templateSlug: step.templateSlug, delivery: step.delivery, until: at });
+          t = at;
+        }
+        record("send", "send", { templateSlug: step.templateSlug });
+        sends.push({ templateSlug: step.templateSlug, at: t, stepIndex: index, branchPath: [...branchPath] });
+        index += 1;
+        break;
+      }
+      case "tag":
+        record("tag", "tagged", { addTags: step.addTags ?? [], removeTags: step.removeTags ?? [] });
+        index += 1;
+        break;
+      case "fire_event":
+        record("fire_event", "event_fired", { eventName: step.eventName });
+        index += 1;
+        break;
+      case "webhook":
+        record("webhook", "webhook", { url: step.url, method: step.method ?? "POST", note: "not called in simulation" });
+        index += 1;
+        break;
+      case "exit":
+        record("exit", "exited", { reason: step.reason ?? "exit_step" });
+        terminal = { kind: "exited", reason: step.reason ?? "exit_step", at: t };
+        break;
+    }
+  }
+  if (!terminal) terminal = { kind: "truncated", reason: `stopped after ${MAX_STEPS} steps`, at: t };
+  return {
+    flow: { slug: flow.slug, version: flow.version, enabled: flow.enabled },
+    contact: { externalId: contact.externalId, email: contact.email },
+    enteredAt,
+    wouldEnter: { ok: reasons.length === 0, reasons },
+    path: path3,
+    sends,
+    terminal,
+    durationMs: terminal.at.getTime() - enteredAt.getTime()
+  };
+}
+function unitToMs2(value, unit) {
+  const m = 6e4;
+  switch (unit) {
+    case "minutes":
+      return value * m;
+    case "hours":
+      return value * 60 * m;
+    case "days":
+      return value * 24 * 60 * m;
+    case "weeks":
+      return value * 7 * 24 * 60 * m;
+  }
+}
+
+// src/server/api/agent.ts
+var VERSION = "0.16.0" ;
+var MIN_AGENT_TOKEN_LENGTH = 24;
+function createAgentRouter(mailer, opts) {
+  if (!opts || !Array.isArray(opts.tokens) || opts.tokens.length === 0) {
+    throw new Error("createAgentRouter: at least one bearer token is required \u2014 the agent API is never open");
+  }
+  for (const t of opts.tokens) {
+    if (typeof t?.token !== "string" || t.token.length < MIN_AGENT_TOKEN_LENGTH) {
+      throw new Error(
+        `createAgentRouter: every token must be at least ${MIN_AGENT_TOKEN_LENGTH} characters (got ${t?.token?.length ?? 0})`
+      );
+    }
+    if (typeof t.actor !== "string" || !t.actor.trim()) {
+      throw new Error('createAgentRouter: every token needs an actor label, e.g. "agent:claude"');
+    }
+  }
+  const logger = opts.logger ?? consoleRouteLogger;
+  const isTestContact = testContactMatcher(opts.testContacts);
+  const c = mailer.collections;
+  const varsSchema = mailer.config.varsAdapter ? varsJsonSchema(mailer.config.varsAdapter) : null;
+  const router = Router();
+  router.use(express.json({ limit: "1mb" }));
+  router.use(bearerAuth(opts.tokens));
+  router.use("/api", createAdminApiRouter(mailer, { mailTesterClient: opts.mailTesterClient }));
+  const actorOf = (req) => String(req.actor);
+  function guardTestContact(res, contact) {
+    if (!isTestContact) {
+      res.status(403).json({
+        error: "test_contacts_not_configured",
+        message: "this route only acts on test contacts, and the router was constructed without a testContacts pattern"
+      });
+      return false;
+    }
+    if (!isTestContact(contact.email)) {
+      res.status(403).json({
+        error: "not_a_test_contact",
+        message: `${contact.email} does not match the testContacts pattern`,
+        externalId: contact.externalId
+      });
+      return false;
+    }
+    return true;
+  }
+  async function loadContact(res, externalId) {
+    const contact = await mailer.adapter.getById(externalId);
+    if (!contact) res.status(404).json({ error: "contact_not_found", externalId });
+    return contact;
+  }
+  async function loadTemplate(res, slug) {
+    const tpl = await c.templates.findOne({ slug });
+    if (!tpl) res.status(404).json({ error: "template_not_found", slug });
+    return tpl;
+  }
+  router.get("/", (req, res) => {
+    res.json({
+      service: "mailery-agent",
+      version: VERSION,
+      actor: actorOf(req),
+      testContactsConfigured: !!isTestContact,
+      docs: "https://jeffjassky.github.io/mailery/reference/agent-api",
+      endpoints: ENDPOINTS
+    });
+  });
+  router.post(
+    "/templates/:slug/verify",
+    wrap2(async (req, res) => {
+      const tpl = await loadTemplate(res, String(req.params.slug));
+      if (!tpl) return;
+      const contact = await contactForRender(req, res);
+      if (!contact) return;
+      const report = await verifyTemplate(mailer, tpl, contact, {
+        eventProperties: objectOrUndefined(req.body?.eventProperties),
+        vars: objectOrUndefined(req.body?.vars),
+        includeRendered: req.body?.includeRendered === true,
+        varsSchema
+      });
+      res.status(200).json(report);
+    })
+  );
+  router.post(
+    "/templates/verify-all",
+    wrap2(async (req, res) => {
+      const slugs = Array.isArray(req.body?.slugs) ? req.body.slugs.map(String) : null;
+      const contactIds = Array.isArray(req.body?.contactIds) ? req.body.contactIds.map(String) : [];
+      if (contactIds.length === 0) {
+        return res.status(400).json({ error: "validation_failed", message: "contactIds (non-empty array) is required" });
+      }
+      const templates = await c.templates.find(slugs ? { slug: { $in: slugs } } : {}).sort({ slug: 1 }).toArray();
+      const contacts = [];
+      for (const id of contactIds) {
+        const found = await mailer.adapter.getById(id);
+        if (!found) return res.status(404).json({ error: "contact_not_found", externalId: id });
+        contacts.push(found);
+      }
+      const results = [];
+      for (const tpl of templates) {
+        for (const contact of contacts) {
+          const report = await verifyTemplate(mailer, tpl, contact, {
+            eventProperties: objectOrUndefined(req.body?.eventProperties),
+            includeRendered: false,
+            varsSchema
+          });
+          results.push({
+            slug: tpl.slug,
+            contactId: contact.externalId,
+            ok: report.ok,
+            failed: report.checks.filter((k) => k.status === "fail").map((k) => k.id),
+            warned: report.checks.filter((k) => k.status === "warn").map((k) => k.id)
+          });
+        }
+      }
+      const failing = results.filter((r) => !r.ok);
+      res.json({
+        ok: failing.length === 0,
+        templates: templates.length,
+        contacts: contacts.length,
+        verified: results.length,
+        failing: failing.length,
+        results
+      });
+    })
+  );
+  router.post(
+    "/templates/:slug/render",
+    wrap2(async (req, res) => {
+      const tpl = await loadTemplate(res, String(req.params.slug));
+      if (!tpl) return;
+      const contact = await contactForRender(req, res);
+      if (!contact) return;
+      const out = await renderForContact(mailer, tpl, contact, {
+        reason: "preview",
+        eventProperties: objectOrUndefined(req.body?.eventProperties),
+        vars: objectOrUndefined(req.body?.vars)
+      });
+      res.json({
+        template: { slug: tpl.slug, kind: tpl.kind },
+        contact: { externalId: contact.externalId, email: contact.email },
+        subject: out.rendered.subject,
+        preheader: out.rendered.preheader,
+        fromName: out.rendered.fromName,
+        fromEmail: out.rendered.fromEmail,
+        replyTo: out.rendered.replyTo,
+        html: out.rendered.html,
+        plainText: out.rendered.plainText,
+        resolvedVars: out.resolved,
+        unsubscribeUrl: out.unsubscribeUrl
+      });
+    })
+  );
+  router.post(
+    "/templates/:slug/send",
+    wrap2(async (req, res) => {
+      const tpl = await loadTemplate(res, String(req.params.slug));
+      if (!tpl) return;
+      const contactId = typeof req.body?.contactId === "string" ? req.body.contactId : "";
+      if (!contactId) return res.status(400).json({ error: "validation_failed", message: "contactId is required" });
+      const contact = await loadContact(res, contactId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      if (!tpl.body?.html && !tpl.body?.mjml) {
+        return res.status(409).json({ error: "not_published", message: "template has no published body" });
+      }
+      const dedupeKey = typeof req.body?.dedupeKey === "string" && req.body.dedupeKey ? String(req.body.dedupeKey) : `agent:${crypto2.randomUUID()}`;
+      const { sendId } = await mailer.sendOneOff({
+        templateSlug: tpl.slug,
+        externalId: contact.externalId,
+        dedupeKey,
+        vars: objectOrUndefined(req.body?.vars)
+      });
+      const dispatchNow = req.body?.dispatch !== "queue";
+      if (dispatchNow) {
+        await dispatchSend(new ObjectId(sendId), mailer.getRunnerContext());
+      }
+      const send = await c.sends.findOne({ _id: new ObjectId(sendId) });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.send",
+        resource: { collection: "mailer_sends", id: new ObjectId(sendId), slug: tpl.slug },
+        diffSummary: `to=${contact.email} dispatch=${dispatchNow ? "now" : "queue"} dedupeKey=${dedupeKey}`
+      });
+      res.status(201).json({ sendId, dedupeKey, dispatched: dispatchNow, send: send ? sendSummary(send) : null });
+    })
+  );
+  router.get(
+    "/sends/:id/wait",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const target = String(req.query.status ?? "delivered");
+      if (!WAIT_TARGETS.has(target)) {
+        return res.status(400).json({ error: "validation_failed", message: `status must be one of ${[...WAIT_TARGETS].join(", ")}` });
+      }
+      const timeoutMs = Math.max(0, Math.min(Number(req.query.timeoutMs ?? 3e4) || 0, 55e3));
+      const started = Date.now();
+      let send = null;
+      let reached = false;
+      for (; ; ) {
+        send = await c.sends.findOne({ _id: new ObjectId(id) });
+        if (!send) return res.status(404).json({ error: "not_found" });
+        reached = waitTargetReached(send, target);
+        if (reached || Date.now() - started >= timeoutMs) break;
+        await sleep2(1e3);
+      }
+      const webhookEvents = send.providerMessageId ? await c.webhookEvents.find({ providerMessageId: send.providerMessageId }).sort({ receivedAt: 1 }).limit(100).toArray() : [];
+      res.json({ reached, target, waitedMs: Date.now() - started, send: sendSummary(send), webhookEvents });
+    })
+  );
+  router.post(
+    "/sends/:id/dispatch",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const send = await c.sends.findOne({ _id: new ObjectId(id) });
+      if (!send) return res.status(404).json({ error: "not_found" });
+      const contact = await loadContact(res, send.externalId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      await dispatchSend(send._id, mailer.getRunnerContext());
+      const after = await c.sends.findOne({ _id: send._id });
+      res.json({ send: after ? sendSummary(after) : null });
+    })
+  );
+  router.post(
+    "/flows/:slug/simulate",
+    wrap2(async (req, res) => {
+      const flow = await c.flows.findOne({ slug: String(req.params.slug) });
+      if (!flow) return res.status(404).json({ error: "flow_not_found", slug: String(req.params.slug) });
+      const contactId = typeof req.body?.contactId === "string" ? req.body.contactId : "";
+      if (!contactId) return res.status(400).json({ error: "validation_failed", message: "contactId is required" });
+      const contact = await loadContact(res, contactId);
+      if (!contact) return;
+      let at;
+      if (req.body?.at) {
+        at = new Date(String(req.body.at));
+        if (Number.isNaN(at.getTime())) return res.status(400).json({ error: "validation_failed", message: "at must be an ISO date" });
+      }
+      let steps = void 0;
+      if (req.body?.version !== void 0) {
+        const v = Number(req.body.version);
+        if (v !== flow.version) {
+          const snap = await c.flowVersions.findOne({ flowId: flow._id, version: v });
+          if (!snap) return res.status(404).json({ error: "version_not_found", version: v });
+          steps = snap.steps;
+        }
+      }
+      const result = await simulateFlow(flow, contact, mailer.getRunnerContext(), {
+        at,
+        eventProperties: objectOrUndefined(req.body?.eventProperties),
+        steps
+      });
+      res.json(result);
+    })
+  );
+  router.post(
+    "/flows/:slug/arm",
+    wrap2(async (req, res) => {
+      if (req.body?.confirm !== true) {
+        return res.status(400).json({
+          error: "confirm_required",
+          message: 'arming enables a flow for every future matching event; pass {"confirm": true}'
+        });
+      }
+      let since;
+      if (req.body?.since) {
+        since = new Date(String(req.body.since));
+        if (Number.isNaN(since.getTime())) return res.status(400).json({ error: "validation_failed", message: "since must be an ISO date" });
+      }
+      const result = await armFlow(mailer, String(req.params.slug), { actor: actorOf(req), since });
+      res.json(result);
+    })
+  );
+  router.post(
+    "/flows/:slug/disarm",
+    wrap2(async (req, res) => {
+      res.json(await disarmFlow(mailer, String(req.params.slug), actorOf(req)));
+    })
+  );
+  router.post(
+    "/flows/:slug/gate",
+    wrap2(async (req, res) => {
+      const tag = typeof req.body?.tag === "string" ? req.body.tag : "";
+      res.json(await gateFlow(mailer, String(req.params.slug), { tag, actor: actorOf(req) }));
+    })
+  );
+  router.post(
+    "/flows/:slug/ungate",
+    wrap2(async (req, res) => {
+      res.json(await ungateFlow(mailer, String(req.params.slug), { actor: actorOf(req) }));
+    })
+  );
+  router.get(
+    "/runs",
+    wrap2(async (req, res) => {
+      const filter = {};
+      if (typeof req.query.externalId === "string") filter.externalId = req.query.externalId;
+      if (typeof req.query.flowSlug === "string") filter.flowSlug = req.query.flowSlug;
+      if (typeof req.query.status === "string") filter.status = req.query.status;
+      const limit = Math.min(Math.max(Number(req.query.limit ?? 50) || 50, 1), 200);
+      const runs = await c.flowRuns.find(filter).sort({ enteredAt: -1 }).limit(limit).toArray();
+      res.json(runs.map(runSummary));
+    })
+  );
+  router.get(
+    "/runs/:id",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new ObjectId(id) });
+      if (!run) return res.status(404).json({ error: "not_found" });
+      const sends = await c.sends.find({ flowRunId: run._id }).sort({ queuedAt: 1 }).toArray();
+      res.json({ run, sends: sends.map(sendSummary) });
+    })
+  );
+  router.post(
+    "/runs/:id/advance",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new ObjectId(id) });
+      if (!run) return res.status(404).json({ error: "not_found" });
+      const contact = await loadContact(res, run.externalId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      if (run.status !== "active") {
+        return res.status(409).json({ error: "run_not_active", status: run.status, exitReason: run.exitReason });
+      }
+      const steps = Math.min(Math.max(Number(req.body?.steps ?? 1) || 1, 1), 50);
+      const dispatch = req.body?.dispatch !== false;
+      const ctx = mailer.getRunnerContext();
+      const startedAt = /* @__PURE__ */ new Date();
+      const historyBefore = run.history.length;
+      const actor = actorOf(req);
+      for (let i = 0; i < steps; i += 1) {
+        const advanced = await advanceOnce(run._id, ctx, actor, c);
+        if (!advanced) break;
+      }
+      const after = await c.flowRuns.findOne({ _id: run._id });
+      const newSends = await c.sends.find({ flowRunId: run._id, queuedAt: { $gte: startedAt } }).toArray();
+      if (dispatch) {
+        for (const s of newSends) {
+          if (s.status === "queued") await dispatchSend(s._id, ctx);
+        }
+      }
+      const sends = await c.sends.find({ flowRunId: run._id, queuedAt: { $gte: startedAt } }).toArray();
+      await mailer.audit({
+        actor,
+        action: "agent.run.advance",
+        resource: { collection: "mailer_flow_runs", id: run._id, slug: run.flowSlug },
+        diffSummary: `advanced ${steps} step(s) for ${contact.email}; ${sends.length} send(s) created`
+      });
+      res.json({
+        run: after ? runSummary(after) : null,
+        historyAdded: after ? after.history.slice(historyBefore) : [],
+        sends: sends.map(sendSummary)
+      });
+    })
+  );
+  router.post(
+    "/runs/:id/cancel",
+    wrap2(async (req, res) => {
+      const id = String(req.params.id);
+      if (!ObjectId.isValid(id)) return res.status(400).json({ error: "bad_id" });
+      const run = await c.flowRuns.findOne({ _id: new ObjectId(id) });
+      if (!run) return res.status(404).json({ error: "not_found" });
+      if (run.status !== "active") return res.status(409).json({ error: "run_not_active", status: run.status });
+      const actor = actorOf(req);
+      await exitFlowRun(run, `aborted_by_host:${actor}`, mailer.getRunnerContext());
+      const cancelled = await c.sends.updateMany(
+        { flowRunId: run._id, status: "queued" },
+        { $set: { status: "cancelled", errorMessage: `cancelled: aborted_by_host:${actor}`, updatedAt: /* @__PURE__ */ new Date() } }
+      );
+      await mailer.audit({
+        actor,
+        action: "agent.run.cancel",
+        resource: { collection: "mailer_flow_runs", id: run._id, slug: run.flowSlug },
+        diffSummary: `cancelled run for ${run.externalId}; ${cancelled.modifiedCount} queued send(s) cancelled`
+      });
+      const after = await c.flowRuns.findOne({ _id: run._id });
+      res.json({ run: after ? runSummary(after) : null, cancelledSends: cancelled.modifiedCount });
+    })
+  );
+  router.post(
+    "/events",
+    wrap2(async (req, res) => {
+      const name = typeof req.body?.name === "string" ? req.body.name : "";
+      const externalId = typeof req.body?.externalId === "string" ? req.body.externalId : "";
+      if (!name || !externalId) {
+        return res.status(400).json({ error: "validation_failed", message: "name and externalId are required" });
+      }
+      const contact = await loadContact(res, externalId);
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      const dedupeKey = typeof req.body?.dedupeKey === "string" && req.body.dedupeKey ? req.body.dedupeKey : void 0;
+      try {
+        await mailer.fire(name, externalId, objectOrUndefined(req.body?.properties) ?? {}, dedupeKey);
+      } catch (err) {
+        return res.status(400).json({ error: "fire_failed", message: String(err?.message ?? err) });
+      }
+      const latest = await c.events.findOne({ externalId, name }, { sort: { createdAt: -1 } });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.event.fire",
+        resource: { collection: "mailer_events", id: latest?._id },
+        diffSummary: `${name} for ${contact.email}${dedupeKey ? ` key=${dedupeKey}` : ""}`
+      });
+      res.status(201).json({ ok: true, event: latest });
+    })
+  );
+  router.get(
+    "/contacts/by-email/:email",
+    wrap2(async (req, res) => {
+      const contact = await mailer.adapter.getByEmail(String(req.params.email).toLowerCase());
+      if (!contact) return res.status(404).json({ error: "contact_not_found", email: req.params.email });
+      res.json(await contactDetail(contact));
+    })
+  );
+  router.get(
+    "/contacts/:externalId",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      res.json(await contactDetail(contact));
+    })
+  );
+  router.get(
+    "/contacts/:externalId/unsubscribe-url",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      res.json({ contact: { externalId: contact.externalId, email: contact.email }, unsubscribeUrl: unsubscribeUrlFor(mailer, contact.email) });
+    })
+  );
+  router.post(
+    "/contacts/:externalId/subscribe",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      await mailer.upsertSubscription({ externalId: contact.externalId, source: "agent" });
+      const sub = await c.subscriptions.findOne({ externalId: contact.externalId });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.contact.subscribe",
+        resource: { collection: "mailer_subscriptions", id: sub?._id },
+        diffSummary: contact.email
+      });
+      res.json({ subscription: sub });
+    })
+  );
+  router.post(
+    "/contacts/:externalId/unsubscribe",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      await mailer.unsubscribe(contact.email, { scope: "marketing", reason: "user_request", source: "agent" });
+      const sub = await c.subscriptions.findOne({ externalId: contact.externalId });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.contact.unsubscribe",
+        resource: { collection: "mailer_subscriptions", id: sub?._id },
+        diffSummary: contact.email
+      });
+      res.json({ subscription: sub });
+    })
+  );
+  router.post(
+    "/contacts/:externalId/reset",
+    wrap2(async (req, res) => {
+      const contact = await loadContact(res, String(req.params.externalId));
+      if (!contact) return;
+      if (!guardTestContact(res, contact)) return;
+      const b = req.body ?? {};
+      const eventFilter = { externalId: contact.externalId };
+      if (Array.isArray(b.events)) eventFilter.name = { $in: b.events.map(String) };
+      const doRuns = b.runs !== false;
+      const doSends = b.sends !== false;
+      const doEvents = b.events !== false;
+      const doSuppressions = b.suppressions !== false;
+      const doSubscribe = b.subscribe !== false;
+      const removed = { runs: 0, sends: 0, events: 0, suppressions: 0 };
+      if (doRuns) removed.runs = (await c.flowRuns.deleteMany({ externalId: contact.externalId })).deletedCount;
+      if (doSends) removed.sends = (await c.sends.deleteMany({ externalId: contact.externalId })).deletedCount;
+      if (doEvents) removed.events = (await c.events.deleteMany(eventFilter)).deletedCount;
+      if (doSuppressions) removed.suppressions = (await c.suppressions.deleteMany({ email: contact.email })).deletedCount;
+      if (doSubscribe) await mailer.upsertSubscription({ externalId: contact.externalId, source: "agent-reset" });
+      const subscription = await c.subscriptions.findOne({ externalId: contact.externalId });
+      await mailer.audit({
+        actor: actorOf(req),
+        action: "agent.contact.reset",
+        resource: { collection: "mailer_subscriptions", id: subscription?._id },
+        diffSummary: `${contact.email}: removed ${removed.runs} run(s), ${removed.sends} send(s), ${removed.events} event(s), ${removed.suppressions} suppression(s)${doSubscribe ? "; resubscribed" : ""}`
+      });
+      res.json({ contact: { externalId: contact.externalId, email: contact.email }, removed, subscription });
+    })
+  );
+  router.post(
+    "/tick",
+    wrap2(async (_req, res) => {
+      const started = Date.now();
+      await runTick(mailer.getRunnerContext());
+      res.json({ ok: true, ms: Date.now() - started });
+    })
+  );
+  router.get(
+    "/webhooks/status",
+    wrap2(async (_req, res) => {
+      const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1e3);
+      const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1e3);
+      const [last, byType24h, total7d, unprocessed] = await Promise.all([
+        c.webhookEvents.findOne({}, { sort: { receivedAt: -1 }, projection: { receivedAt: 1, provider: 1, normalizedType: 1 } }),
+        c.webhookEvents.aggregate([{ $match: { receivedAt: { $gte: dayAgo } } }, { $group: { _id: "$normalizedType", n: { $sum: 1 } } }]).toArray(),
+        c.webhookEvents.countDocuments({ receivedAt: { $gte: weekAgo } }),
+        c.webhookEvents.countDocuments({ processed: false })
+      ]);
+      res.json({
+        providers: Object.keys(mailer.providers),
+        lastReceivedAt: last?.receivedAt ?? null,
+        lastProvider: last?.provider ?? null,
+        last24h: Object.fromEntries(byType24h.map((r) => [r._id, r.n])),
+        last7d: total7d,
+        unprocessed,
+        ingestPath: `${mailer.config.publicUrl}/m/webhooks/<provider>`
+      });
+    })
+  );
+  router.get(
+    "/status",
+    wrap2(async (_req, res) => {
+      const dayAgo = new Date(Date.now() - 24 * 60 * 60 * 1e3);
+      const [flows, templates, subscribed, suppressions, activeRuns, sends24h, webhooks24h, lastWebhook, healthDocs, setup] = await Promise.all([
+        c.flows.find({}, { projection: { slug: 1, enabled: 1, version: 1, lastTriggerScanAt: 1, steps: 1, trigger: 1 } }).sort({ slug: 1 }).toArray(),
+        c.templates.find({}, { projection: { slug: 1, kind: 1, publishedAt: 1, "body.html": 1, fromEmail: 1 } }).sort({ slug: 1 }).toArray(),
+        c.subscriptions.countDocuments({ status: "subscribed" }),
+        c.suppressions.estimatedDocumentCount(),
+        c.flowRuns.countDocuments({ status: "active" }),
+        c.sends.aggregate([{ $match: { queuedAt: { $gte: dayAgo } } }, { $group: { _id: "$status", n: { $sum: 1 } } }]).toArray(),
+        c.webhookEvents.countDocuments({ receivedAt: { $gte: dayAgo } }),
+        c.webhookEvents.findOne({}, { sort: { receivedAt: -1 }, projection: { receivedAt: 1 } }),
+        c.health.find({}).limit(500).toArray(),
+        runSetupChecks(mailer)
+      ]);
+      const activeByFlow = await c.flowRuns.aggregate([{ $match: { status: "active" } }, { $group: { _id: "$flowSlug", n: { $sum: 1 } } }]).toArray();
+      const activeMap = new Map(activeByFlow.map((r) => [r._id, r.n]));
+      res.json({
+        version: VERSION,
+        now: /* @__PURE__ */ new Date(),
+        testContactsConfigured: !!isTestContact,
+        setup,
+        health: { status: healthDocs.length ? effectiveOverallStatus(healthDocs) : null, aggregate: healthDocs.find((d) => d._id === HEALTH_AGG_ID) ?? null },
+        flows: flows.map((f) => ({
+          slug: f.slug,
+          enabled: f.enabled,
+          version: f.version,
+          lastTriggerScanAt: f.lastTriggerScanAt ?? null,
+          trigger: f.trigger,
+          liveSteps: Array.isArray(f.steps) ? f.steps.length : 0,
+          gated: Array.isArray(f.steps) && isCanaryGate(f.steps[0]) ? f.steps[0].test.hasTag : null,
+          activeRuns: activeMap.get(f.slug) ?? 0
+        })),
+        templates: templates.map((t) => ({
+          slug: t.slug,
+          kind: t.kind,
+          fromEmail: t.fromEmail,
+          published: !!(t.body && t.body.html),
+          publishedAt: t.publishedAt ?? null
+        })),
+        counts: {
+          subscribed,
+          suppressions,
+          activeRuns,
+          sendsLast24h: Object.fromEntries(sends24h.map((r) => [r._id, r.n])),
+          webhookEventsLast24h: webhooks24h,
+          lastWebhookAt: lastWebhook?.receivedAt ?? null
+        }
+      });
+    })
+  );
+  router.use((req, res) => {
+    res.status(404).json({ error: "not_found", message: `no agent route ${req.method} ${req.path}; GET / lists them` });
+  });
+  router.use((err, req, res, _next) => {
+    if (err instanceof FlowOperationError) {
+      return res.status(err.status).json({ error: err.code, message: err.message });
+    }
+    if (err?.name === "ZodError") {
+      return res.status(400).json({ error: "validation_failed", issues: err.issues });
+    }
+    logger.error?.({ err: String(err?.message ?? err), path: req.path, method: req.method }, "mailery agent: request failed");
+    if (res.headersSent) return;
+    res.status(500).json({ error: "internal", message: String(err?.message ?? err) });
+  });
+  return router;
+  async function contactForRender(req, res) {
+    const contactId = typeof req.body?.contactId === "string" ? req.body.contactId : "";
+    if (contactId) return loadContact(res, contactId);
+    const sample = req.body?.sampleContact;
+    if (sample && typeof sample === "object" && typeof sample.email === "string") {
+      return {
+        externalId: String(sample.externalId ?? "sample-contact"),
+        email: sample.email,
+        tags: Array.isArray(sample.tags) ? sample.tags.map(String) : [],
+        fields: sample.fields && typeof sample.fields === "object" ? sample.fields : {},
+        timezone: typeof sample.timezone === "string" ? sample.timezone : void 0
+      };
+    }
+    res.status(400).json({ error: "validation_failed", message: "contactId (or a sampleContact with an email) is required" });
+    return null;
+  }
+  async function contactDetail(contact) {
+    const [subscription, recentEvents, recentSends, runs, suppressions] = await Promise.all([
+      c.subscriptions.findOne({ externalId: contact.externalId }),
+      c.events.find({ externalId: contact.externalId }).sort({ occurredAt: -1 }).limit(50).toArray(),
+      c.sends.find({ externalId: contact.externalId }).sort({ queuedAt: -1 }).limit(50).toArray(),
+      c.flowRuns.find({ externalId: contact.externalId }).sort({ enteredAt: -1 }).limit(50).toArray(),
+      c.suppressions.find({ email: contact.email }).toArray()
+    ]);
+    return {
+      contact,
+      isTestContact: isTestContact ? isTestContact(contact.email) : null,
+      subscription,
+      suppressions,
+      recentEvents,
+      recentSends: recentSends.map(sendSummary),
+      runs: runs.map(runSummary)
+    };
+  }
+}
+var PLACEHOLDER_RE = /\{\{[^{}]*\}\}|\{\{\{[^{}]*\}\}\}/g;
+var HREF_RE = /href\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+var GMAIL_CLIP_BYTES = 102 * 1024;
+async function verifyTemplate(mailer, tpl, contact, opts = {}) {
+  const checks = [];
+  const push = (id, status, detail) => checks.push(detail === void 0 ? { id, status } : { id, status, detail });
+  const base = {
+    template: { slug: tpl.slug, kind: tpl.kind, name: tpl.name },
+    contact: { externalId: contact.externalId, email: contact.email }
+  };
+  const finish = (rendered2, links2) => ({
+    ok: checks.every((k) => k.status !== "fail"),
+    ...base,
+    checks,
+    links: { total: links2.length, sample: links2.slice(0, 50) },
+    rendered: rendered2 ? opts.includeRendered ? {
+      subject: rendered2.subject,
+      preheader: rendered2.preheader,
+      html: rendered2.html,
+      plainText: rendered2.plainText,
+      fromEmail: rendered2.fromEmail,
+      fromName: rendered2.fromName,
+      replyTo: rendered2.replyTo
+    } : {
+      subject: rendered2.subject,
+      preheader: rendered2.preheader,
+      htmlBytes: Buffer.byteLength(rendered2.html, "utf8"),
+      textLength: rendered2.plainText.trim().length,
+      fromEmail: rendered2.fromEmail
+    } : null
+  });
+  if (!tpl.body?.html && !tpl.body?.mjml) {
+    push("published", "fail", "template has no published body (body.html and body.mjml are empty)");
+    return finish(null, []);
+  }
+  push("published", "pass", { publishedAt: tpl.publishedAt ?? null });
+  let out;
+  try {
+    out = await renderForContact(mailer, tpl, contact, {
+      reason: "test",
+      eventProperties: opts.eventProperties,
+      vars: opts.vars
+    });
+    push("vars_resolved", "pass", { keys: Object.keys(out.resolved) });
+    push("render", "pass");
+  } catch (err) {
+    const message = String(err?.message ?? err);
+    push(message.startsWith("varsAdapter") ? "vars_resolved" : "render", "fail", message);
+    return finish(null, []);
+  }
+  const { rendered, unsubscribeUrl } = out;
+  const leftovers = /* @__PURE__ */ new Set();
+  for (const part of [rendered.subject, rendered.preheader, rendered.html, rendered.plainText]) {
+    for (const m of part.matchAll(PLACEHOLDER_RE)) leftovers.add(m[0]);
+  }
+  push("unresolved_placeholders", leftovers.size ? "fail" : "pass", leftovers.size ? { placeholders: [...leftovers] } : void 0);
+  const referenced = referencedPaths(
+    [tpl.subject, tpl.preheader, tpl.body.html, tpl.body.plainText, tpl.body.mjml ?? ""].join("\n"),
+    Object.keys(mailer.config.handlebarsHelpers ?? {})
+  );
+  const missing = [];
+  const empty = [];
+  for (const path3 of referenced) {
+    const value = lookupPath(out.context, path3);
+    if (value === void 0) {
+      const root = path3.split(".")[0];
+      if (RESERVED_VAR_KEYS.includes(root)) empty.push(path3);
+      else missing.push(path3);
+    } else if (value === null || value === "") {
+      empty.push(path3);
+    }
+  }
+  push("unknown_variables", missing.length ? "fail" : "pass", { referenced: referenced.length, missing });
+  push("empty_variables", empty.length ? "warn" : "pass", { empty });
+  const links = extractLinks(rendered.html);
+  const invalid = links.filter((l) => !/^(https?:\/\/|mailto:|tel:)/i.test(l));
+  push("links_absolute", invalid.length ? "fail" : "pass", { total: links.length, invalid });
+  if (tpl.kind === "marketing") {
+    push("unsubscribe_link", rendered.html.includes(unsubscribeUrl) ? "pass" : "fail", {
+      hint: "a marketing template must reference {{unsubscribeUrl}} in its body"
+    });
+    if (mailer.config.senderAddress) {
+      push("sender_address", rendered.html.includes(mailer.config.senderAddress) ? "pass" : "fail", {
+        hint: "CAN-SPAM: reference {{senderAddress}} in the footer"
+      });
+    }
+  }
+  const text = rendered.plainText.trim();
+  push("plain_text", text.length === 0 ? "fail" : text.length < 40 ? "warn" : "pass", { length: text.length });
+  const subject = rendered.subject.trim();
+  push("subject", subject.length === 0 ? "fail" : subject.length > 78 ? "warn" : "pass", { length: subject.length });
+  if (mailer.config.senderDomains && Object.keys(mailer.config.senderDomains).length > 0) {
+    const v = validateSenderDomain(rendered.fromEmail, tpl.kind, mailer.config.senderDomains);
+    push("from_domain", v.ok ? "pass" : "fail", v.ok ? { fromEmail: rendered.fromEmail } : { fromEmail: rendered.fromEmail, code: v.code, reason: v.reason });
+  }
+  const bytes = Buffer.byteLength(rendered.html, "utf8");
+  push("html_size", bytes > GMAIL_CLIP_BYTES ? "warn" : "pass", { bytes, clipAt: GMAIL_CLIP_BYTES });
+  const lint = lintTemplate(
+    {
+      subject: tpl.subject,
+      preheader: tpl.preheader,
+      mjml: tpl.body.mjml ?? "",
+      editorJson: tpl.body.editorJson ?? void 0,
+      html: tpl.body.html,
+      plainText: tpl.body.plainText,
+      kind: tpl.kind,
+      fromEmail: tpl.fromEmail
+    },
+    { senderDomains: mailer.config.senderDomains, varsJsonSchema: opts.varsSchema ?? null }
+  );
+  push("lint", lint.errors.length ? "fail" : lint.warnings.length ? "warn" : "pass", {
+    errors: lint.errors.map((i) => ({ rule: i.rule, message: i.message })),
+    warnings: lint.warnings.map((i) => i.rule)
+  });
+  return finish(rendered, links);
+}
+async function renderForContact(mailer, tpl, contact, opts) {
+  let resolved;
+  try {
+    resolved = await resolveVars(mailer.config.varsAdapter, contact, {
+      reason: opts.reason,
+      templateSlug: tpl.slug,
+      eventProperties: opts.eventProperties
+    });
+  } catch (err) {
+    throw new Error(`varsAdapter.resolve threw: ${String(err?.message ?? err)}`);
+  }
+  const unsubscribeUrl = unsubscribeUrlFor(mailer, contact.email);
+  const context = {
+    ...resolved,
+    contact,
+    vars: opts.vars ?? {},
+    event: opts.eventProperties ?? {},
+    unsubscribeUrl,
+    senderAddress: mailer.config.senderAddress
+  };
+  const rendered = await renderTemplate(tpl, context, { helpers: mailer.config.handlebarsHelpers });
+  return { rendered, resolved, unsubscribeUrl, context };
+}
+function unsubscribeUrlFor(mailer, email) {
+  const expiresAt = new Date(Date.now() + mailer.config.unsubscribeTokenLifetimeDays * 24 * 60 * 60 * 1e3);
+  const token = signUnsubscribeToken({ email, scope: "marketing", expiresAt }, mailer.config.unsubscribeSecret);
+  return `${mailer.config.publicUrl}/m/unsub/${token}`;
+}
+function extractLinks(html) {
+  const out = [];
+  for (const m of html.matchAll(HREF_RE)) {
+    const href = (m[1] ?? m[2] ?? "").trim();
+    if (!href || href.startsWith("#")) continue;
+    out.push(href);
+  }
+  return out;
+}
+var BUILTIN_HELPERS = /* @__PURE__ */ new Set([
+  "eq",
+  "ne",
+  "gt",
+  "lt",
+  "gte",
+  "lte",
+  "and",
+  "or",
+  "not",
+  "formatDate",
+  "formatNumber",
+  "formatCurrency",
+  "pluralize",
+  "if",
+  "unless",
+  "each",
+  "with",
+  "else",
+  "lookup",
+  "log",
+  "this",
+  "true",
+  "false",
+  "null",
+  "undefined"
+]);
+var MUSTACHE_RE = /\{\{\{?([^{}]*)\}\}\}?/g;
+var BLOCK_SCOPE_RE = /\{\{#(each|with)\b[\s\S]*?\{\{\/\1\}\}/g;
+var HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+var PATH_RE = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
+function referencedPaths(source, helperNames = []) {
+  const helpers = /* @__PURE__ */ new Set([...BUILTIN_HELPERS, ...helperNames]);
+  const out = /* @__PURE__ */ new Set();
+  const scanned = source.replace(HTML_COMMENT_RE, "").replace(BLOCK_SCOPE_RE, "");
+  for (const m of scanned.matchAll(MUSTACHE_RE)) {
+    let expr = (m[1] ?? "").trim();
+    if (!expr || expr.startsWith("!")) continue;
+    expr = expr.replace(/^[#/^]\s*/, "").replace(/^else\b\s*/, "");
+    for (let tok of expr.split(/[\s()]+/)) {
+      if (!tok) continue;
+      const eq = tok.indexOf("=");
+      if (eq > 0) tok = tok.slice(eq + 1);
+      if (/^['"]/.test(tok) || /^-?\d/.test(tok)) continue;
+      if (tok.startsWith("@") || tok.startsWith("../") || tok.startsWith("this.")) continue;
+      if (helpers.has(tok) || !PATH_RE.test(tok)) continue;
+      out.add(tok);
+    }
+  }
+  return [...out];
+}
+function lookupPath(ctx, path3) {
+  let cur = ctx;
+  for (const part of path3.split(".")) {
+    if (cur === null || typeof cur !== "object") return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function testContactMatcher(spec) {
+  if (!spec) return null;
+  if (spec instanceof RegExp) return (email) => spec.test(email);
+  if (typeof spec === "function") return (email) => !!spec(email);
+  return null;
+}
+function bearerAuth(tokens) {
+  const hashed = tokens.map((t) => ({ hash: crypto2.createHash("sha256").update(t.token).digest(), actor: t.actor }));
+  return (req, res, next) => {
+    const header = String(req.headers.authorization ?? "");
+    const m = /^Bearer\s+(\S+)\s*$/i.exec(header);
+    if (!m) {
+      return res.status(401).json({ error: "unauthorized", message: "send Authorization: Bearer <token>" });
+    }
+    const presented = crypto2.createHash("sha256").update(m[1] ?? "").digest();
+    const match = hashed.find((h) => crypto2.timingSafeEqual(h.hash, presented));
+    if (!match) return res.status(401).json({ error: "unauthorized", message: "unknown token" });
+    req.actor = match.actor;
+    next();
+  };
+}
+async function advanceOnce(runId, ctx, actor, c) {
+  for (let hop = 0; hop < 10; hop += 1) {
+    const run = await c.flowRuns.findOne({ _id: runId });
+    if (!run || run.status !== "active") return false;
+    if (run.nextActionAt && run.nextActionAt.getTime() > Date.now()) {
+      await c.flowRuns.updateOne(
+        { _id: runId, status: "active" },
+        {
+          $set: { nextActionAt: /* @__PURE__ */ new Date(), updatedAt: /* @__PURE__ */ new Date() },
+          $push: {
+            history: {
+              stepIndex: Math.max(0, run.currentStepIndex - 1),
+              action: "wait_completed",
+              at: /* @__PURE__ */ new Date(),
+              details: { forcedBy: actor, scheduledFor: run.nextActionAt }
+            }
+          }
+        }
+      );
+    }
+    const before = (await c.flowRuns.findOne({ _id: runId }))?.history.length ?? 0;
+    await processOneRunStep(runId, ctx);
+    const after = await c.flowRuns.findOne({ _id: runId });
+    if (!after) return false;
+    const last = after.history[after.history.length - 1];
+    const progressed = after.history.length > before;
+    if (progressed && last?.action === "wait_started" && after.status === "active") continue;
+    return after.status === "active" && progressed;
+  }
+  return false;
+}
+var WAIT_TARGETS = /* @__PURE__ */ new Set(["sent", "delivered", "opened", "clicked", "terminal"]);
+function waitTargetReached(send, target) {
+  switch (target) {
+    case "sent":
+      return send.status === "sent" || send.status === "delivered" || !!send.sentAt;
+    case "delivered":
+      return send.status === "delivered" || !!send.deliveredAt;
+    case "opened":
+      return !!send.openedAt;
+    case "clicked":
+      return !!send.firstClickAt;
+    case "terminal":
+      return ["delivered", "bounced", "failed", "suppressed", "cancelled", "complained"].includes(send.status);
+    default:
+      return false;
+  }
+}
+function sendSummary(s) {
+  return {
+    id: String(s._id),
+    templateSlug: s.templateSlug,
+    externalId: s.externalId,
+    email: s.emailAtSend,
+    kind: s.kind,
+    status: s.status,
+    provider: s.provider,
+    providerMessageId: s.providerMessageId,
+    subject: s.subject,
+    errorMessage: s.errorMessage,
+    flowRunId: s.flowRunId ? String(s.flowRunId) : null,
+    queuedAt: s.queuedAt,
+    sentAt: s.sentAt,
+    deliveredAt: s.deliveredAt,
+    openedAt: s.openedAt,
+    firstClickAt: s.firstClickAt,
+    bounceType: s.bounceType
+  };
+}
+function runSummary(r) {
+  return {
+    id: String(r._id),
+    flowSlug: r.flowSlug,
+    flowVersion: r.flowVersion,
+    externalId: r.externalId,
+    email: r.emailAtEntry,
+    status: r.status,
+    currentStepIndex: r.currentStepIndex,
+    currentBranchPath: r.currentBranchPath,
+    nextActionAt: r.nextActionAt,
+    enteredAt: r.enteredAt,
+    exitedAt: r.exitedAt,
+    exitReason: r.exitReason,
+    triggerEvent: r.triggerEvent ?? null,
+    history: r.history
+  };
+}
+function objectOrUndefined(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : void 0;
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function wrap2(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res)).catch(next);
+  };
+}
+var ENDPOINTS = [
+  { method: "GET", path: "/", summary: "This listing, the package version and the actor behind the token." },
+  { method: "*", path: "/api/*", summary: "The full admin JSON API (flows, templates, contacts, sends, health, setup-status, \u2026) with this token as the actor." },
+  { method: "POST", path: "/templates/:slug/verify", summary: "Render the published template as a contact ({contactId} or {sampleContact}) and run named checks: placeholders, links, unsubscribe, sender address, plain text, subject, from domain, size, lint. {includeRendered: true} returns the HTML." },
+  { method: "POST", path: "/templates/verify-all", summary: "Verify every template (or {slugs}) for each of {contactIds}; a matrix of pass/fail." },
+  { method: "POST", path: "/templates/:slug/render", summary: "Render for a contact and return subject, preheader, HTML, plain text, resolved vars and the signed unsubscribe URL." },
+  { method: "POST", path: "/templates/:slug/send", summary: 'A real send through the pipeline to a test contact ({contactId}); dispatched inline unless {dispatch: "queue"}. Returns the sendId.', testContactsOnly: true },
+  { method: "GET", path: "/sends/:id/wait?status=delivered&timeoutMs=30000", summary: "Long-poll a send until it reaches sent | delivered | opened | clicked | terminal, with its webhook events." },
+  { method: "POST", path: "/sends/:id/dispatch", summary: "Dispatch a queued send now (test contacts only).", testContactsOnly: true },
+  { method: "POST", path: "/flows/:slug/simulate", summary: "Dry-run the flow for {contactId} from {at} with {eventProperties}: the path taken, every gate verdict, projected send times, where it ends. Writes nothing." },
+  { method: "POST", path: "/flows/:slug/arm", summary: "Enable the flow for FUTURE events: stamps the trigger watermark ({since} or now) in the same write. Requires {confirm: true}." },
+  { method: "POST", path: "/flows/:slug/disarm", summary: "Disable the flow (pause). In-flight runs continue." },
+  { method: "POST", path: "/flows/:slug/gate", summary: "Publish a canary version whose first step exits anyone without {tag}." },
+  { method: "POST", path: "/flows/:slug/ungate", summary: "Restore the newest ungated version." },
+  { method: "GET", path: "/runs?externalId=&flowSlug=&status=&limit=", summary: "List flow runs." },
+  { method: "GET", path: "/runs/:id", summary: "One run with its history and sends." },
+  { method: "POST", path: "/runs/:id/advance", summary: "Walk a test contact's run forward now, skipping the wait in front of each of {steps} transitions; sends are dispatched inline.", testContactsOnly: true },
+  { method: "POST", path: "/runs/:id/cancel", summary: "Exit an active run and cancel its queued sends." },
+  { method: "POST", path: "/events", summary: "Fire {name} for a test contact {externalId} with {properties} and optional {dedupeKey}.", testContactsOnly: true },
+  { method: "GET", path: "/contacts/:externalId", summary: "Contact with subscription, suppressions, recent events, sends and runs." },
+  { method: "GET", path: "/contacts/by-email/:email", summary: "Same, looked up by email." },
+  { method: "GET", path: "/contacts/:externalId/unsubscribe-url", summary: "A signed one-click unsubscribe URL for a test contact, to exercise POST /m/unsub/:token.", testContactsOnly: true },
+  { method: "POST", path: "/contacts/:externalId/subscribe", summary: "Subscribe a test contact.", testContactsOnly: true },
+  { method: "POST", path: "/contacts/:externalId/unsubscribe", summary: "Unsubscribe a test contact (marketing scope).", testContactsOnly: true },
+  { method: "POST", path: "/contacts/:externalId/reset", summary: "Delete a test contact's runs, sends, events ({events: [names]} to narrow) and suppressions, then resubscribe. Each part can be turned off with false.", testContactsOnly: true },
+  { method: "POST", path: "/tick", summary: "Run the runner tick now (trigger scan, sweeps, outbox, webhook backlog)." },
+  { method: "GET", path: "/webhooks/status", summary: "Provider webhook ingest: last event received, counts by type (24h), unprocessed backlog." },
+  { method: "GET", path: "/status", summary: "One document with setup checks, health, every flow (enabled, version, watermark, gate, active runs), every template, and 24h counts." }
+];
+var ALLOWED_EXTENSIONS = [".zip", ".gz", ".xml"];
+var DEFAULT_PATH = "/inbound/dmarc";
+var DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_FILES = 10;
+function mountDmarcInbound(router, mailer, opts, logger) {
+  const secret = opts?.secret;
+  if (!opts || typeof secret !== "string" || secret.length === 0) return null;
+  const routePath = opts.path ?? DEFAULT_PATH;
+  const parseInbound = opts.parseInbound ?? sendgridInboundParser;
+  const allowedDomains = normalizeDomains(opts.allowedDomains ?? deriveSenderDomains(mailer));
+  if (allowedDomains.size === 0) {
+    logger.warn?.(
+      { path: routePath },
+      "mailery: DMARC inbound route mounted without a domain allowlist \u2014 set senderDomains (or dmarcInbound.allowedDomains) so a leaked secret cannot inject reports for arbitrary domains"
+    );
+  }
+  const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: {
+      fileSize: opts.maxFileSizeBytes ?? DEFAULT_MAX_FILE_BYTES,
+      files: opts.maxFiles ?? DEFAULT_MAX_FILES,
+      // Inbound Parse sends the whole email as form fields (headers, text,
+      // html, ...). We read none of them, but they still have to be bounded.
+      fields: 40,
+      fieldSize: 1024 * 1024
+    }
+  });
+  router.post(
+    routePath,
+    wrap(logger, (req, res, next) => {
+      if (!isAuthorized(req, secret)) {
+        logger.warn?.(
+          { path: routePath, ip: req.ip },
+          "mailery: DMARC inbound request rejected \u2014 bad or missing shared secret"
+        );
+        res.status(401).json({ error: "unauthorized" });
+        return;
+      }
+      next();
+    }),
+    (req, res, next) => {
+      upload.any()(req, res, (err) => {
+        if (!err) return next();
+        const code = err?.code;
+        const status = code === "LIMIT_FILE_SIZE" || code === "LIMIT_FILE_COUNT" ? 413 : 400;
+        logger.warn?.({ err, path: routePath }, "mailery: DMARC inbound upload rejected");
+        res.status(status).json({ error: "upload_rejected", message: String(code ?? "malformed_multipart") });
+      });
+    },
+    wrap(logger, async (req, res) => {
+      let attachments;
+      try {
+        attachments = parseInbound(req);
+      } catch (err) {
+        logger.warn?.({ err, path: routePath }, "mailery: DMARC inbound payload unreadable");
+        return res.status(400).json({ error: "bad_payload" });
+      }
+      const candidates = attachments.filter((a) => hasAllowedExtension(a.filename));
+      if (candidates.length === 0) {
+        logger.info?.(
+          { path: routePath, attachments: attachments.length },
+          "mailery: DMARC inbound message carried no report attachment \u2014 ignored"
+        );
+        return res.status(200).json({ ok: true, ingested: 0, ignored: attachments.length });
+      }
+      const ctx = mailer.getRunnerContext();
+      const allowDomain = allowedDomains.size === 0 ? void 0 : (d) => allowedDomains.has(d.toLowerCase());
+      const ingested = [];
+      const rejected = [];
+      for (const file of candidates) {
+        try {
+          const result = await ingestDmarcAttachment(ctx, file.buffer, file.filename, { allowDomain });
+          ingested.push({ reportId: result.reportId, domain: result.domain, duplicate: result.duplicate });
+        } catch (err) {
+          const message = String(err?.message ?? err);
+          rejected.push({ filename: file.filename, message });
+          logger.warn?.(
+            { path: routePath, filename: file.filename, err },
+            "mailery: DMARC inbound attachment rejected"
+          );
+        }
+      }
+      if (ingested.length === 0) {
+        return res.status(400).json({ error: "ingest_failed", rejected });
+      }
+      return res.status(200).json({ ok: true, ingested, rejected });
+    })
+  );
+  return routePath;
+}
+function isAuthorized(req, secret) {
+  const presented = extractPresentedSecret(req);
+  if (presented === null) return false;
+  return constantTimeEquals(presented, secret);
+}
+function extractPresentedSecret(req) {
+  const header = req.headers.authorization;
+  if (typeof header !== "string") return null;
+  const [scheme, ...rest] = header.split(" ");
+  const value = rest.join(" ").trim();
+  if (!scheme || value === "") return null;
+  switch (scheme.toLowerCase()) {
+    case "basic": {
+      let decoded;
+      try {
+        decoded = Buffer.from(value, "base64").toString("utf8");
+      } catch {
+        return null;
+      }
+      const sep = decoded.indexOf(":");
+      return sep === -1 ? null : decoded.slice(sep + 1);
+    }
+    case "bearer":
+      return value;
+    default:
+      return null;
+  }
+}
+function constantTimeEquals(a, b) {
+  const ha = createHash("sha256").update(a, "utf8").digest();
+  const hb = createHash("sha256").update(b, "utf8").digest();
+  return timingSafeEqual(ha, hb);
+}
+var sendgridInboundParser = (req) => {
+  const files = req.files;
+  if (!Array.isArray(files)) return [];
+  return files.filter((f) => Boolean(f) && Buffer.isBuffer(f.buffer)).map((f) => ({ filename: safeFilename(f.originalname), buffer: f.buffer }));
+};
+function safeFilename(raw) {
+  if (typeof raw !== "string") return "";
+  return raw.replace(/[\u0000-\u001f\u007f]/g, "").replace(/[\\/]/g, "_").slice(0, 255);
+}
+function hasAllowedExtension(filename) {
+  const lower = filename.toLowerCase();
+  return ALLOWED_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+function normalizeDomains(domains) {
+  const out = /* @__PURE__ */ new Set();
+  for (const d of domains) {
+    if (typeof d !== "string") continue;
+    const trimmed = d.trim().toLowerCase().replace(/^\.+/, "");
+    if (trimmed) out.add(trimmed);
+  }
+  return out;
+}
+function deriveSenderDomains(mailer) {
+  const out = [];
+  const push = (domain) => {
+    if (!domain) return;
+    out.push(domain);
+    const labels = domain.split(".");
+    if (labels.length > 2) out.push(labels.slice(-2).join("."));
+  };
+  for (const domain of Object.keys(mailer.config.senderDomains ?? {})) push(domain.toLowerCase());
+  push(emailDomain(mailer.config.fromDefaults?.email));
+  push(emailDomain(mailer.config.transactionalFromDefaults?.email));
+  push(emailDomain(mailer.config.senderAddress));
+  return out;
+}
+function emailDomain(email) {
+  if (typeof email !== "string") return void 0;
+  const at = email.lastIndexOf("@");
+  if (at === -1) return void 0;
+  const domain = email.slice(at + 1).trim().toLowerCase();
+  return domain || void 0;
+}
+
+// src/server/api/public.ts
+var PIXEL = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
+  "base64"
+);
+function createPublicRouter(mailer, opts = {}) {
+  const router = Router();
+  const logger = opts.logger ?? consoleRouteLogger;
+  const pendingUnsubsPath = opts.pendingUnsubsPath ?? mailer.config.pendingUnsubsPath ?? null;
+  if (opts.pendingUnsubsPath && !mailer.config.pendingUnsubsPath) {
+    logger.warn?.(
+      { path: opts.pendingUnsubsPath },
+      "mailery: pendingUnsubsPath set on the public router but not in MailerConfig \u2014 the tick drain will not replay this journal"
+    );
+  }
+  if (!pendingUnsubsPath) {
+    logger.warn?.(
+      {},
+      "mailery: no pendingUnsubsPath configured \u2014 POST /unsub answers 503 when Mongo is unreachable instead of journaling the opt-out"
+    );
+  }
+  const dmarcInboundPath = mountDmarcInbound(router, mailer, opts.dmarcInbound, logger);
+  if (dmarcInboundPath) {
+    logger.info?.(
+      { path: dmarcInboundPath },
+      "mailery: DMARC inbound route mounted (shared-secret auth; SendGrid Inbound Parse does not sign payloads)"
+    );
+  }
+  router.use(
+    "/webhooks",
+    express.json({
+      limit: "5mb",
+      verify: (req, _res, buf) => {
+        req.rawBody = buf;
+      }
+    })
+  );
+  router.use("/unsub", express.urlencoded({ extended: false }));
+  router.get("/open/:sendId.png", wrap(logger, async (req, res) => {
+    res.setHeader("Content-Type", "image/png");
+    res.setHeader("Content-Length", String(PIXEL.length));
+    res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate, max-age=0");
+    res.status(200).end(PIXEL);
+    const parsed = splitOpenParam(req.params.sendId);
+    if (!parsed) return;
+    const { id, sig } = parsed;
+    if (!ObjectId.isValid(id)) return;
+    const sendId = new ObjectId(id);
+    const verdict = checkTrackingSignature({
+      scope: "open",
+      params: { sendId: id },
+      sig,
+      secret: mailer.config.unsubscribeSecret,
+      requireSigned: mailer.config.requireSignedTrackingUrls,
+      logger,
+      fields: { sendId: id }
+    });
+    if (verdict === "rejected") return;
+    try {
+      const send = await mailer.collections.sends.findOne(
+        { _id: sendId },
+        { projection: { openedAt: 1, queuedAt: 1 } }
+      );
+      if (!send) return;
+      if (isTrackingExpired(send, mailer.config.trackingUrlLifetimeDays)) {
+        logger.warn?.({ sendId: id }, "mailery: open ignored \u2014 tracking URL past trackingUrlLifetimeDays");
+        return;
+      }
+      const now = /* @__PURE__ */ new Date();
+      await mailer.collections.sends.updateOne(
+        { _id: sendId },
+        {
+          $set: {
+            openedAt: send.openedAt ?? now,
+            status: "delivered"
+          },
+          $inc: { openCount: 1 },
+          // Per-open user agent, so `hasOpenedExcludingBots` has a signal to
+          // filter on. Capped: an open pixel can be re-fetched indefinitely
+          // (every time the recipient re-opens the mail) and an unbounded
+          // array would eventually run the send document into the 16MB limit.
+          $push: {
+            opens: {
+              $each: [{ openedAt: now, userAgent: requestUserAgent(req) }],
+              $slice: -MAX_TRACKED_OPENS
+            }
+          }
+        }
+      );
+    } catch (err) {
+      logger.error?.({ err, sendId: id }, "mailery: open pixel update failed");
+    }
+  }));
+  router.get("/click/:sendId/:linkId{/:sig}", wrap(logger, async (req, res) => {
+    const { sendId: sendIdStr, linkId, sig } = req.params;
+    if (!ObjectId.isValid(sendIdStr)) return res.status(400).end();
+    const sendId = new ObjectId(sendIdStr);
+    const verdict = checkTrackingSignature({
+      scope: "click",
+      params: { sendId: sendIdStr, linkId },
+      sig,
+      secret: mailer.config.unsubscribeSecret,
+      requireSigned: mailer.config.requireSignedTrackingUrls,
+      logger,
+      fields: { sendId: sendIdStr, linkId }
+    });
+    if (verdict === "rejected") return res.status(404).end();
+    const send = await mailer.collections.sends.findOne(
+      { _id: sendId },
+      { projection: { links: 1, firstClickAt: 1, queuedAt: 1 } }
+    );
+    if (!send) return res.status(404).end();
+    if (isTrackingExpired(send, mailer.config.trackingUrlLifetimeDays)) {
+      logger.warn?.(
+        { sendId: sendIdStr, linkId },
+        "mailery: click rejected \u2014 tracking URL past trackingUrlLifetimeDays"
+      );
+      return res.status(404).end();
+    }
+    const link = (send.links ?? []).find((l) => l.linkId === linkId);
+    if (!link) return res.status(404).end();
+    if (!isSafeRedirectTarget(link.url)) {
+      logger.warn?.(
+        { sendId: sendIdStr, linkId, url: link.url },
+        "mailery: click redirect blocked \u2014 disallowed URL scheme"
+      );
+      return res.status(400).type("html").send("<!doctype html><html><body><p>This link cannot be opened.</p></body></html>");
+    }
+    res.redirect(302, link.url);
+    try {
+      await mailer.collections.sends.updateOne(
+        { _id: sendId },
+        {
+          $set: { firstClickAt: send.firstClickAt ?? /* @__PURE__ */ new Date() },
+          $inc: { clickCount: 1 },
+          $push: {
+            clickedLinks: {
+              url: link.url,
+              linkId,
+              clickedAt: /* @__PURE__ */ new Date(),
+              // The bot filter has always read `clickedLinks[].userAgent`; until
+              // now nothing ever wrote it, so every click scored as human.
+              userAgent: requestUserAgent(req)
+            }
+          }
+        }
+      );
+    } catch (err) {
+      logger.error?.({ err, sendId: sendIdStr, linkId }, "mailery: click recording failed");
+    }
+  }));
+  router.get("/unsub/:token", wrap(logger, (req, res) => {
+    const decoded = verifyUnsubscribeToken(req.params.token, mailer.config.unsubscribeSecret);
     if (!decoded) return sendUnsubError(res, "Invalid or expired link.");
     res.status(200).type("html").send(`<!doctype html>
 <html><head>
@@ -7490,32 +9527,55 @@ function createPublicRouter(mailer, opts = {}) {
     <button type="submit">Unsubscribe</button>
   </form>
 </body></html>`);
-  });
-  router.post("/unsub/:token", async (req, res) => {
+  }));
+  router.post("/unsub/:token", wrap(logger, async (req, res) => {
     const decoded = verifyUnsubscribeToken(req.params.token, mailer.config.unsubscribeSecret);
     if (!decoded) {
       res.status(200).end();
       return;
     }
-    res.status(200).type("html").send("<!doctype html><html><body><p>You are unsubscribed.</p></body></html>");
+    const write = mailer.unsubscribe(decoded.email, {
+      scope: decoded.scope,
+      reason: "user_request",
+      source: "one-click"
+    });
+    let dbError = null;
     try {
-      await mailer.unsubscribe(decoded.email, {
-        scope: decoded.scope,
-        reason: "user_request",
-        source: "one-click"
-      });
+      await withTimeout(write, mailer.config.unsubscribeWriteTimeoutMs);
     } catch (err) {
+      dbError = err ?? new Error("unsubscribe write failed");
+      void write.catch(() => {
+      });
+    }
+    if (dbError) {
+      if (!pendingUnsubsPath) {
+        logger.error?.(
+          { err: dbError },
+          "mailery: unsubscribe write failed and no pendingUnsubsPath is configured \u2014 answering 503"
+        );
+        return sendUnsubUnavailable(res);
+      }
       try {
-        fs.appendFileSync(
-          pendingUnsubsPath,
-          JSON.stringify({ email: decoded.email, scope: decoded.scope, at: Date.now() }) + "\n"
+        appendPendingUnsub(pendingUnsubsPath, {
+          email: decoded.email,
+          scope: decoded.scope,
+          at: Date.now()
+        });
+        logger.warn?.(
+          { err: dbError, path: pendingUnsubsPath },
+          "mailery: unsubscribe journaled to disk \u2014 will be replayed by the tick drain"
         );
       } catch (diskErr) {
-        console.error("mailery: unsub disk fallback failed", { err, diskErr });
+        logger.error?.(
+          { err: dbError, diskErr, path: pendingUnsubsPath },
+          "mailery: unsub disk fallback failed \u2014 answering 503"
+        );
+        return sendUnsubUnavailable(res);
       }
     }
-  });
-  router.get("/confirm-doi/:token", async (req, res) => {
+    res.status(200).type("html").send("<!doctype html><html><body><p>You are unsubscribed.</p></body></html>");
+  }));
+  router.get("/confirm-doi/:token", wrap(logger, async (req, res) => {
     const token = req.params.token;
     const decoded = verifyDoiToken(token, mailer.config.unsubscribeSecret);
     if (!decoded) {
@@ -7543,10 +9603,10 @@ function createPublicRouter(mailer, opts = {}) {
     } catch {
     }
     return res.status(200).type("html").send("<!doctype html><html><body><p>Thanks \u2014 you're subscribed.</p></body></html>");
-  });
-  router.post("/webhooks/:provider", async (req, res) => {
+  }));
+  router.post("/webhooks/:provider", wrap(logger, async (req, res) => {
     const providerName = req.params.provider;
-    const provider = mailer.providers[providerName];
+    const provider = resolveProvider(mailer.providers, providerName);
     if (!provider) return res.status(404).end();
     const rawBody = req.rawBody;
     if (!rawBody) return res.status(400).end();
@@ -7577,7 +9637,10 @@ function createPublicRouter(mailer, opts = {}) {
           { upsert: true }
         );
       } catch (err) {
-        console.error("mailery: webhook dedupe insert failed", err);
+        logger.error?.(
+          { err, provider: providerName, providerEventId: evt.providerEventId },
+          "mailery: webhook dedupe insert failed"
+        );
       }
     }
     if (events.length > 0) {
@@ -7586,15 +9649,94 @@ function createPublicRouter(mailer, opts = {}) {
       } catch {
       }
     }
-  });
+  }));
   return router;
 }
+var MAX_TRACKED_OPENS = 50;
+var MAX_UA_LENGTH = 256;
+function requestUserAgent(req) {
+  const ua = req.headers["user-agent"];
+  if (typeof ua !== "string" || ua.trim() === "") return null;
+  return ua.slice(0, MAX_UA_LENGTH);
+}
+function splitOpenParam(raw) {
+  if (typeof raw !== "string") return null;
+  const parts = raw.split(".");
+  if (parts.length === 1) return { id: parts[0] };
+  if (parts.length === 2) return { id: parts[0], sig: parts[1] };
+  return null;
+}
+function checkTrackingSignature(args) {
+  const { sig, logger, fields, scope } = args;
+  if (sig === void 0 || sig === "") {
+    if (args.requireSigned) {
+      logger.warn?.(
+        { ...fields, scope },
+        "mailery: unsigned tracking URL rejected (requireSignedTrackingUrls)"
+      );
+      return "rejected";
+    }
+    logger.info?.(
+      { ...fields, scope },
+      "mailery: unsigned tracking URL accepted \u2014 legacy grace mode"
+    );
+    return "legacy";
+  }
+  if (!verifyTrackingToken(sig, scope, args.params, args.secret)) {
+    logger.warn?.({ ...fields, scope }, "mailery: tracking URL signature invalid");
+    return "rejected";
+  }
+  return "signed";
+}
+function isTrackingExpired(send, lifetimeDays, now = /* @__PURE__ */ new Date()) {
+  if (!lifetimeDays || lifetimeDays <= 0) return false;
+  const queuedAt = send.queuedAt;
+  if (!(queuedAt instanceof Date) || Number.isNaN(queuedAt.getTime())) return false;
+  return now.getTime() - queuedAt.getTime() > lifetimeDays * 24 * 60 * 60 * 1e3;
+}
 function sendUnsubError(res, msg) {
   return res.status(400).type("html").send(`<!doctype html><html><body><p>${escapeHtml(msg)}</p></body></html>`);
 }
+function sendUnsubUnavailable(res) {
+  return res.status(503).set("Retry-After", "60").type("html").send(
+    "<!doctype html><html><body><p>We could not record your unsubscribe right now, so you are <strong>not</strong> unsubscribed yet. Please try again in a minute.</p></body></html>"
+  );
+}
+function withTimeout(p, ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return p;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`timed out after ${ms}ms`));
+    }, ms);
+    if (typeof timer.unref === "function") timer.unref();
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+var ALLOWED_REDIRECT_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+function isSafeRedirectTarget(raw) {
+  if (typeof raw !== "string") return false;
+  const trimmed = raw.trim();
+  if (trimmed === "") return false;
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return false;
+  }
+  return ALLOWED_REDIRECT_PROTOCOLS.has(parsed.protocol);
+}
 function lowercaseHeaders(h) {
   const out = {};
   for (const k of Object.keys(h)) {
@@ -7763,8 +9905,8 @@ var DEDUPE_POLICIES = [
 ];
 
 // src/server/index.ts
-var VERSION = "0.14.0" ;
+var VERSION2 = "0.16.0" ;
 
-export { DEDUPE_POLICIES, FLOW_STEP_KINDS, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, RESERVED_VAR_KEYS, SEGMENT_FILTER_KINDS, SendGridProvider, VERSION, applyTracking, applyWebhookEvent, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, defineVars, derivePlaintext, dispatchSend, ensureIndexes, getCollections, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, renderTemplate, runTick, sha256Hex, signUnsubscribeToken, sweepStrandedFlowRuns, validateSenderDomain, varsJsonSchema, verifyUnsubscribeToken };
+export { DEDUPE_POLICIES, DEFAULT_BOT_UA_RE, FLOW_STEP_KINDS, FlowOperationError, MIN_AGENT_TOKEN_LENGTH, Mailer, MongoContactAdapter, NullProvider, PREDICATE_KINDS, RESERVED_VAR_KEYS, SEGMENT_FILTER_KINDS, SendGridProvider, TRACKING_SIG_LENGTH, VERSION2 as VERSION, applyTracking, applyWebhookEvent, armFlow, compileMailyTemplate, compileTemplate, computeDeliveryTime, createAdminApiRouter, createAdminRouter, createAgentRouter, createPublicRouter, defaultFlowStep, defaultPredicate, defaultSegmentFilter, defineVars, derivePlaintext, disarmFlow, dispatchSend, drainPendingUnsubscribes, ensureIndexes, gateFlow, getCollections, isCanaryGate, predicateKind, processNewlyFiredEventTriggers, processOneRunStep, referencedPaths, renderForContact, renderTemplate, runTick, sendgridInboundParser, sha256Hex, signTrackingToken, signUnsubscribeToken, simulateFlow, stampWatermarkIfNull, sweepStrandedFlowRuns, ungateFlow, validateSenderDomain, varsJsonSchema, verifyTemplate, verifyTrackingToken, verifyUnsubscribeToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map