@foldrun/core 0.3.0 → 0.4.0

package/src/json-schema.ts

@@ -0,0 +1,184 @@
+// A JSON Schema validator small enough to read, with no dependency.
+//
+// `schema:` beside `output: json` says what shape the reply's value must
+// have, and a value that does not have it fails the step with a sentence
+// naming the field. The subset here is the part of JSON Schema people write
+// by hand for a handoff — types, required fields, enums, ranges, patterns,
+// arrays, the combinators, and `$ref` to a definition in the same document.
+// Formats (`date-time`, `email`) are accepted and not checked; a check that
+// needs one belongs in a `verify:`. Anything the validator does not know is
+// ignored, the way JSON Schema itself says unknown keywords are.
+//
+// Not ajv: it sits in node_modules as a dependency of a dependency, which is
+// nothing to build on, and the whole of it is far more than a step needs.
+
+export interface SchemaError {
+  /** JSON pointer to the offending value: "" is the root, "/leads/0/url". */
+  path: string;
+  message: string;
+}
+
+type Schema = Record<string, unknown> | boolean;
+
+const MAX_ERRORS = 8;
+
+/** Is `value` what `schema` describes? Empty means yes. */
+export function validateSchema(value: unknown, schema: unknown): SchemaError[] {
+  const errors: SchemaError[] = [];
+  check(value, schema as Schema, "", schema as Schema, errors, 0);
+  return errors.slice(0, MAX_ERRORS);
+}
+
+/** The errors as one sentence for a trace line. */
+export function describeSchemaErrors(errors: SchemaError[]): string {
+  return errors.map((e) => `${e.path || "the value"}: ${e.message}`).join("; ");
+}
+
+/** Is this a schema at all? An object (or a boolean, which JSON Schema
+ *  allows) — not a string, not a list. */
+export function looksLikeSchema(schema: unknown): boolean {
+  return typeof schema === "boolean" || (typeof schema === "object" && schema !== null && !Array.isArray(schema));
+}
+
+const typeOf = (v: unknown): string =>
+  v === null ? "null" : Array.isArray(v) ? "array" : typeof v === "number" ? (Number.isInteger(v) ? "integer" : "number") : typeof v;
+
+const matchesType = (v: unknown, t: string): boolean => {
+  const actual = typeOf(v);
+  return t === actual || (t === "number" && actual === "integer");
+};
+
+function resolveRef(ref: string, root: Schema): Schema | null {
+  if (!ref.startsWith("#")) return null;
+  let node: unknown = root;
+  for (const raw of ref.slice(1).split("/").filter(Boolean)) {
+    const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (typeof node !== "object" || node === null) return null;
+    node = (node as Record<string, unknown>)[key];
+  }
+  return typeof node === "object" && node !== null ? (node as Schema) : typeof node === "boolean" ? node : null;
+}
+
+function check(value: unknown, schema: Schema, path: string, root: Schema, errors: SchemaError[], depth: number) {
+  if (errors.length >= MAX_ERRORS || depth > 64) return;
+  if (schema === true) return;
+  if (schema === false) return void errors.push({ path, message: "nothing is allowed here" });
+  if (typeof schema !== "object" || schema === null) return;
+  const s = schema as Record<string, unknown>;
+  const fail = (message: string) => errors.push({ path, message });
+
+  if (typeof s.$ref === "string") {
+    const target = resolveRef(s.$ref, root);
+    if (target === null) return fail(`schema: unresolvable $ref ${s.$ref}`);
+    check(value, target, path, root, errors, depth + 1);
+    return;
+  }
+
+  // type — one, or a list of alternatives; "nullable: true" (OpenAPI's
+  // spelling) lets null through.
+  if (s.type !== undefined) {
+    const types = Array.isArray(s.type) ? (s.type as string[]) : [String(s.type)];
+    const ok = types.some((t) => matchesType(value, t)) || (s.nullable === true && value === null);
+    if (!ok) return fail(`expected ${types.join(" or ")}, got ${typeOf(value)}`);
+  }
+  if (Array.isArray(s.enum) && !s.enum.some((e) => deepEqual(e, value))) {
+    return fail(`must be one of ${s.enum.map((e) => JSON.stringify(e)).join(", ")}`);
+  }
+  if ("const" in s && !deepEqual(s.const, value)) return fail(`must be ${JSON.stringify(s.const)}`);
+
+  if (typeof value === "string") {
+    if (typeof s.minLength === "number" && value.length < s.minLength) fail(`shorter than ${s.minLength} characters`);
+    if (typeof s.maxLength === "number" && value.length > s.maxLength) fail(`longer than ${s.maxLength} characters`);
+    if (typeof s.pattern === "string") {
+      try {
+        if (!new RegExp(s.pattern, "u").test(value)) fail(`does not match ${s.pattern}`);
+      } catch {
+        fail(`schema: invalid pattern ${s.pattern}`);
+      }
+    }
+  }
+  if (typeof value === "number") {
+    if (typeof s.minimum === "number" && value < s.minimum) fail(`below the minimum ${s.minimum}`);
+    if (typeof s.maximum === "number" && value > s.maximum) fail(`above the maximum ${s.maximum}`);
+    if (typeof s.exclusiveMinimum === "number" && value <= s.exclusiveMinimum) fail(`must be above ${s.exclusiveMinimum}`);
+    if (typeof s.exclusiveMaximum === "number" && value >= s.exclusiveMaximum) fail(`must be below ${s.exclusiveMaximum}`);
+    if (typeof s.multipleOf === "number" && s.multipleOf > 0 && Math.abs(value / s.multipleOf - Math.round(value / s.multipleOf)) > 1e-9) {
+      fail(`not a multiple of ${s.multipleOf}`);
+    }
+  }
+  if (Array.isArray(value)) {
+    if (typeof s.minItems === "number" && value.length < s.minItems) fail(`fewer than ${s.minItems} items`);
+    if (typeof s.maxItems === "number" && value.length > s.maxItems) fail(`more than ${s.maxItems} items`);
+    if (s.uniqueItems === true) {
+      const seen = new Set(value.map((v) => JSON.stringify(v)));
+      if (seen.size !== value.length) fail("items are not unique");
+    }
+    if (s.items !== undefined && !Array.isArray(s.items)) {
+      value.forEach((item, i) => check(item, s.items as Schema, `${path}/${i}`, root, errors, depth + 1));
+    } else if (Array.isArray(s.items) || Array.isArray(s.prefixItems)) {
+      const tuple = (Array.isArray(s.prefixItems) ? s.prefixItems : s.items) as Schema[];
+      tuple.forEach((sub, i) => i < value.length && check(value[i], sub, `${path}/${i}`, root, errors, depth + 1));
+    }
+  }
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    const props = (typeof s.properties === "object" && s.properties !== null ? s.properties : {}) as Record<string, Schema>;
+    if (Array.isArray(s.required)) {
+      for (const key of s.required as string[]) if (!(key in obj)) fail(`missing required field "${key}"`);
+    }
+    for (const [key, sub] of Object.entries(props)) {
+      if (key in obj) check(obj[key], sub, `${path}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`, root, errors, depth + 1);
+    }
+    const patterns = (typeof s.patternProperties === "object" && s.patternProperties !== null ? s.patternProperties : {}) as Record<string, Schema>;
+    for (const key of Object.keys(obj)) {
+      if (key in props) continue;
+      const pattern = Object.entries(patterns).find(([re]) => {
+        try {
+          return new RegExp(re, "u").test(key);
+        } catch {
+          return false;
+        }
+      });
+      if (pattern) {
+        check(obj[key], pattern[1], `${path}/${key}`, root, errors, depth + 1);
+      } else if (s.additionalProperties === false) {
+        fail(`unexpected field "${key}"`);
+      } else if (typeof s.additionalProperties === "object" && s.additionalProperties !== null) {
+        check(obj[key], s.additionalProperties as Schema, `${path}/${key}`, root, errors, depth + 1);
+      }
+    }
+    if (typeof s.minProperties === "number" && Object.keys(obj).length < s.minProperties) fail(`fewer than ${s.minProperties} fields`);
+    if (typeof s.maxProperties === "number" && Object.keys(obj).length > s.maxProperties) fail(`more than ${s.maxProperties} fields`);
+  }
+
+  if (Array.isArray(s.allOf)) {
+    for (const sub of s.allOf as Schema[]) check(value, sub, path, root, errors, depth + 1);
+  }
+  if (Array.isArray(s.anyOf)) {
+    const ok = (s.anyOf as Schema[]).some((sub) => validateSchema(value, withRoot(sub, root)).length === 0);
+    if (!ok) fail("matches none of the allowed shapes (anyOf)");
+  }
+  if (Array.isArray(s.oneOf)) {
+    const n = (s.oneOf as Schema[]).filter((sub) => validateSchema(value, withRoot(sub, root)).length === 0).length;
+    if (n !== 1) fail(n === 0 ? "matches none of the allowed shapes (oneOf)" : `matches ${n} of the shapes, must match exactly one (oneOf)`);
+  }
+  if (s.not !== undefined && validateSchema(value, withRoot(s.not as Schema, root)).length === 0) fail("matches a shape that is not allowed (not)");
+}
+
+/** A sub-schema checked on its own still resolves `$ref` against the
+ *  document it came from: carry the root's definitions along. */
+function withRoot(sub: Schema, root: Schema): Schema {
+  if (typeof sub !== "object" || sub === null || typeof root !== "object" || root === null) return sub;
+  const defs: Record<string, unknown> = {};
+  for (const key of ["$defs", "definitions"]) if (key in (root as Record<string, unknown>)) defs[key] = (root as Record<string, unknown>)[key];
+  return { ...defs, ...(sub as Record<string, unknown>) };
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a as object), kb = Object.keys(b as object);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));
+}

package/src/library.ts

@@ -11,6 +11,7 @@
 // own file beats its workspace's, which beats the account's. So a team can set
 // a house style once and one agent can still override it.
 
+import { platform } from "./platform.ts";
 import fs from "node:fs";
 import path from "node:path";
 import { dataRoot, singleWorkspace } from "./paths.ts";
@@ -255,7 +256,18 @@ export function deleteLibraryPath(
 
 /** Library tool definitions, keyed by name — http or script, both grantable by name in `tools:`. */
 export function libraryTools(tenant: string): Record<string, ToolDef> {
-  return readToolDir(libraryDir(tenant, "tools"), "account");
+  // The platform's gallery first, the account's own copies over it: a tool
+  // the platform ships is granted by name in every account without anyone
+  // installing it, and an account that installed (copied) one keeps its
+  // copy — that is what "install to customise" means. Both read at account
+  // scope, so a folder tool's `run:` resolves to /library/tools/<name>/…
+  // in the sandbox either way; the staging step lays the gallery down
+  // first and the account library over it for the same reason.
+  const gallery = platform.galleryDir();
+  return {
+    ...(gallery ? readToolDir(path.join(gallery, "tools"), "account") : {}),
+    ...readToolDir(libraryDir(tenant, "tools"), "account"),
+  };
 }
 
 /** Shared memory index — derived from the files, like every other scope. */

package/src/notify.ts

@@ -31,10 +31,13 @@
 // that works is the quiet kind of good news, and a channel that pings on
 // every success gets muted, which un-pings the failures too.
 
+import crypto from "node:crypto";
 import { readAgentsMd } from "./runner.ts";
-import { accountDir, workspaceDir, runCost, type RunRecord } from "./store.ts";
+import { accountDir, workspaceDir, runCost, readFlow, type RunRecord } from "./store.ts";
 import { getSecret } from "./secrets.ts";
-import { approveToken, publicUrl } from "./webhook.ts";
+import { publicUrl } from "./webhook.ts";
+import { approveLinkPath, approveLinkTtlMs } from "./approvals.ts";
+import { noteSecretUse, healthKey } from "./secret-health.ts";
 
 /**
  * The platform's own mail: an invite, a low balance.
@@ -74,10 +77,24 @@ export function notifyMail(tenant: string): { key: string; from: string } | null
   return accountMail(tenant) ?? platformMail(tenant);
 }
 
+/** Was the mail sent on the account's own key? Only then is a refusal from
+ *  Resend a fact about a secret the account holds. Recording a platform-key
+ *  failure against a RESEND_API_KEY the account does not have would send
+ *  them to rotate a key that does not exist. */
+function noteMailUse(tenant: string, status: number): void {
+  if (accountMail(tenant)) noteSecretUse(tenant, healthKey("RESEND_API_KEY", "account"), { host: "api.resend.com", status });
+}
+
 export interface NotifyConfig {
   url?: string;
   email?: string;
   events: string[];
+  /** `signing_secret:` — the NAME of a vault secret, never its value. With
+   *  one, every webhook carries an HMAC of the body it delivers, so the
+   *  receiver can tell a real notification from anyone who learned the URL.
+   *  Inbound hooks have verified a signature since they existed; a delivery
+   *  going the other way is the same problem in the same shape. */
+  signingSecret?: string;
 }
 
 const DEFAULT_EVENTS = ["failed", "awaiting-approval"];
@@ -94,7 +111,7 @@ export function notifyConfig(tenant: string, workspace: string): NotifyConfig |
       : { url: raw, events: DEFAULT_EVENTS };
   }
   if (typeof raw === "object" && raw !== null) {
-    const o = raw as { url?: unknown; email?: unknown; events?: unknown };
+    const o = raw as { url?: unknown; email?: unknown; events?: unknown; signing_secret?: unknown };
     const url = typeof o.url === "string" ? o.url : undefined;
     const email = typeof o.email === "string" ? o.email : undefined;
     if (!url && !email) return null;
@@ -102,6 +119,8 @@ export function notifyConfig(tenant: string, workspace: string): NotifyConfig |
       url,
       email,
       events: Array.isArray(o.events) && o.events.length ? o.events.map(String) : DEFAULT_EVENTS,
+      signingSecret:
+        typeof o.signing_secret === "string" ? o.signing_secret.trim().replace(/^\$\{|\}$/g, "") || undefined : undefined,
     };
   }
   return null;
@@ -111,20 +130,76 @@ export function notifyConfig(tenant: string, workspace: string): NotifyConfig |
 // line per parked run would bury the failures around it.
 let warnedNoPublicUrl = false;
 
+/**
+ * The headers that prove a delivery came from this install.
+ *
+ * `x-foldrun-signature` is a hex SHA-256 HMAC over "<timestamp>.<body>",
+ * keyed by the named vault secret — the timestamp is inside the signed
+ * string so a captured delivery cannot be replayed later with a fresh one.
+ * `x-signature` is the plain HMAC of the body beside it, the scheme the
+ * inbound `signature: hmac` verifies.
+ *
+ * No secret named, no headers: signing is opt-in, and a receiver that does
+ * not check one is no worse off than before.
+ */
+export function signatureHeaders(
+  tenant: string,
+  workspace: string,
+  config: NotifyConfig,
+  body: string,
+): Record<string, string> {
+  if (!config.signingSecret) return {};
+  const secret = getSecret(tenant, config.signingSecret, workspace);
+  if (!secret) {
+    console.error(
+      `[foldrun] notify: signing_secret names ${config.signingSecret}, which is not in the vault for ${tenant}/${workspace} — sending unsigned`,
+    );
+    return {};
+  }
+  const timestamp = Math.floor(Date.now() / 1000).toString();
+  const mac = crypto.createHmac("sha256", secret.value).update(`${timestamp}.${body}`).digest("hex");
+  // Two headers. `x-foldrun-signature` is the timestamped one, and what a
+  // receiver should check. `x-signature` is the plain HMAC of the body,
+  // which is what the inbound `signature: hmac` verifies — so a foldrun
+  // notification pointed at another foldrun webhook flow is accepted, and
+  // any receiver written against the plain scheme keeps working.
+  const plain = crypto.createHmac("sha256", secret.value).update(body).digest("hex");
+  return { "x-foldrun-timestamp": timestamp, "x-foldrun-signature": `sha256=${mac}`, "x-signature": plain };
+}
+
+/** One waiting step's pair of links. */
+export interface StepLinks {
+  /** Index into run.steps. */
+  step: number;
+  agent: string;
+  approveUrl: string;
+  rejectUrl: string;
+}
+
 /**
  * The approve/reject links for a run waiting on a person, or null when the
  * install cannot say where it lives. A notification that only says "waiting
  * for you" sends the reader to find a laptop; one that carries the decision
  * lets them make it where they read it.
  *
+ * One pair per waiting step, each bound to that step and to a moment (the
+ * flow's `approve_within:`, else a week) — see approvals.ts. A link bound
+ * to the run alone approved every later gate of the run for as long as it
+ * ran. When the notification goes to a named approver — an address in the
+ * flow's `approvers:` — the links are bound to that person too, so a
+ * forwarded mail decides as nobody. `approveUrl`/`rejectUrl` on the result
+ * are the first waiting step's pair, for receivers written against that.
+ *
  * The reject link goes to the same page with the choice pre-selected — a
  * GET must not decide anything, because inbox link-checkers follow links.
  */
 export function approvalLinks(
   tenant: string,
   workspace: string,
-  runId: string,
-): { approveUrl: string; rejectUrl: string } | null {
+  run: RunRecord,
+  /** Who the notification is going to, when it is going to one address. */
+  recipient: string | null = null,
+): { approveUrl: string; rejectUrl: string; links: StepLinks[] } | null {
   const base = publicUrl();
   if (!base) {
     if (!warnedNoPublicUrl) {
@@ -135,8 +210,18 @@ export function approvalLinks(
     }
     return null;
   }
-  const approveUrl = `${base}/api/approve/${tenant}/${workspace}/${runId}?token=${approveToken(tenant, workspace, runId)}`;
-  return { approveUrl, rejectUrl: `${approveUrl}&decision=reject` };
+  const flow = readFlow(tenant, workspace, run.flow);
+  const to = (recipient ?? "").trim().toLowerCase();
+  const approver = to && flow?.approvers?.includes(to) ? to : null;
+  const expiresAt = Date.now() + approveLinkTtlMs(flow);
+  const links: StepLinks[] = [];
+  run.steps.forEach((s, i) => {
+    if (s.status !== "awaiting-approval" || s.waitFor === "event") return;
+    const approveUrl = `${base}${approveLinkPath(tenant, workspace, run.id, { step: i, expiresAt, approver })}`;
+    links.push({ step: i, agent: s.agent, approveUrl, rejectUrl: `${approveUrl}&decision=reject` });
+  });
+  if (links.length === 0) return null;
+  return { approveUrl: links[0].approveUrl, rejectUrl: links[0].rejectUrl, links };
 }
 
 /**
@@ -149,6 +234,169 @@ export function isQuietFlow(flow: string): boolean {
   return /^(eval|adhoc):/.test(flow);
 }
 
+/**
+ * A notification that is not about one run finishing.
+ *
+ * Three things need to say something to the same destination a run
+ * notification goes to, and none of them has a RunRecord to hand: a flow
+ * that has been quarantined, a run that has outlived its `sla:`, and a
+ * budget that is nearly spent. They are the messages a person most needs
+ * and least expects, because each one is about something NOT happening —
+ * the failure mode that never sends mail is the one that costs a week.
+ *
+ * The event name is matched against `events:` exactly like a run status,
+ * so a workspace that wants none of this writes its own list and gets none
+ * of it. They are on by default: an alert nobody opted into is the point.
+ */
+export async function sendPlainNotification(
+  tenant: string,
+  workspace: string,
+  msg: { event: string; headline: string; detail: string; flow?: string; runId?: string },
+): Promise<boolean> {
+  const config = notifyConfig(tenant, workspace);
+  if (!config) return false;
+  // These follow `failed`. Each one IS a failure — a flow that stopped
+  // running, a run that has stalled, a budget about to refuse work — that
+  // happens to produce no failed run for the normal path to report. A
+  // destination hearing about failures hears about these; naming one
+  // explicitly also turns it on; leaving `failed` out silences them.
+  if (!config.events.includes(msg.event) && !config.events.includes("failed")) return false;
+
+  const body = {
+    text: `${msg.headline} — ${msg.detail} · ${workspace}`,
+    workspace,
+    status: msg.event,
+    summary: msg.detail,
+    ...(msg.flow ? { flow: msg.flow } : {}),
+    ...(msg.runId ? { runId: msg.runId } : {}),
+  };
+  try {
+    if (config.email) {
+      const mail = notifyMail(tenant);
+      if (!mail) return false;
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: { authorization: `Bearer ${mail.key}`, "content-type": "application/json" },
+        body: JSON.stringify({
+          from: mail.from,
+          to: config.email,
+          subject: `${msg.headline}`.slice(0, 160),
+          text: `${msg.headline}\n\n${msg.detail}\n\nworkspace: ${workspace}\n${msg.flow ? `flow: ${msg.flow}\n` : ""}${msg.runId ? `run: ${msg.runId}\n` : ""}`,
+        }),
+        signal: AbortSignal.timeout(8000),
+      });
+      return res.ok;
+    }
+    const url = (config.url ?? "").replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
+      const hit = getSecret(tenant, name, workspace);
+      return hit ? hit.value : whole;
+    });
+    if (!url || url.includes("${")) return false;
+    const payload = JSON.stringify(body);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...signatureHeaders(tenant, workspace, config, payload) },
+      body: payload,
+      signal: AbortSignal.timeout(5000),
+    });
+    return res.ok;
+  } catch (err) {
+    console.error(`[foldrun] notify (${msg.event}): ${tenant}/${workspace} →`, err instanceof Error ? err.message : err);
+    return false;
+  }
+}
+
+/**
+ * Prove the notification path works, now, while someone is looking.
+ *
+ * Every run notification is sent when nobody is watching, to a destination
+ * nobody has tested, through a mail domain nobody has verified. On
+ * 2026-09-06 every one of them had been going to a bin for weeks and the
+ * only symptom was silence — which is indistinguishable from nothing having
+ * gone wrong. An alert that has never been proven to arrive is not an alert.
+ *
+ * Unlike every other send here, this one reports its failure in full: the
+ * provider's own words, which are what actually name the problem ("domain
+ * not verified", "you can only send to your own address"). Swallowing them
+ * is right for a run notification and useless for a test.
+ */
+export async function sendTestNotification(
+  tenant: string,
+  workspace: string,
+): Promise<{ ok: boolean; destination: string; detail: string }> {
+  const config = notifyConfig(tenant, workspace);
+  if (!config) {
+    return {
+      ok: false,
+      destination: "none",
+      detail:
+        "no notify: in this workspace's AGENTS.md or the account's — nothing would be sent for a failure or a gate either",
+    };
+  }
+  const sent = new Date().toISOString();
+  const headline = "\u2713 foldrun test notification";
+  const detail = `Sent from ${workspace} at ${sent}. If you are reading this, failures and approval gates will reach you here too.`;
+
+  if (config.email) {
+    const mail = notifyMail(tenant);
+    if (!mail) {
+      return {
+        ok: false,
+        destination: config.email,
+        detail:
+          "email is configured but there is no mail credential — set RESEND_API_KEY (and EMAIL_FROM) on the account, or FOLDRUN_RESEND_API_KEY on the platform",
+      };
+    }
+    try {
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: { authorization: `Bearer ${mail.key}`, "content-type": "application/json" },
+        body: JSON.stringify({ from: mail.from, to: config.email, subject: headline, text: `${headline}\n\n${detail}\n` }),
+        signal: AbortSignal.timeout(8000),
+      });
+      noteMailUse(tenant, res.status);
+      const body = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 400);
+      return res.ok
+        ? { ok: true, destination: `${config.email} (from ${mail.from})`, detail: "accepted by Resend for delivery" }
+        : { ok: false, destination: config.email, detail: `HTTP ${res.status} from Resend — ${body}` };
+    } catch (err) {
+      return { ok: false, destination: config.email, detail: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  const raw = config.url ?? "";
+  const url = raw.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
+    const hit = getSecret(tenant, name, workspace);
+    return hit ? hit.value : whole;
+  });
+  // The destination is echoed back with the secret still unresolved: a
+  // Slack webhook URL is itself a credential, and a page that prints it is
+  // a page that leaks it into a screenshot.
+  const shown = raw.includes("${") ? raw : `${url.slice(0, 40)}…`;
+  if (!url || url.includes("${")) {
+    return { ok: false, destination: shown, detail: `the secret named in notify.url is not in this account's vault` };
+  }
+  try {
+    const payload = JSON.stringify({ text: `${headline} — ${detail}`, workspace, status: "test", summary: detail });
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...signatureHeaders(tenant, workspace, config, payload) },
+      body: payload,
+      signal: AbortSignal.timeout(8000),
+    });
+    const body = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 400);
+    return res.ok
+      ? {
+          ok: true,
+          destination: shown,
+          detail: config.signingSecret ? "accepted, signed with " + config.signingSecret : "accepted",
+        }
+      : { ok: false, destination: shown, detail: `HTTP ${res.status} — ${body}` };
+  } catch (err) {
+    return { ok: false, destination: shown, detail: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 export async function sendRunNotification(
   tenant: string,
   workspace: string,
@@ -162,6 +410,11 @@ export async function sendRunNotification(
   // on 2026-09-06 the reader's inbox rule had sent the lot to the bin, the
   // real reports with them. Failures and gates still send: a person asked.
   if (run.status === "completed" && isQuietFlow(run.flow)) return false;
+  // A test run sent nothing outward and this must not be the exception: it
+  // reports only a failure, which is the one thing the person testing it
+  // needs told about without watching. Its gate mail would ask a real
+  // decision about a pretend send.
+  if (run.test && run.status !== "failed") return false;
 
   const failed = run.steps.filter((s) => s.status === "failed").map((s) => s.agent);
   const waitingSteps = run.steps.filter((s) => s.status === "awaiting-approval");
@@ -185,7 +438,9 @@ export async function sendRunNotification(
   // reporting only its own existence is a desk nobody reads by week three.
   const summary = run.summary?.trim() || null;
 
-  const links = run.status === "awaiting-approval" ? approvalLinks(tenant, workspace, run.id) : null;
+  // An emailed link is minted for its reader: a named approver's mail
+  // carries links that decide as them. A webhook has no reader.
+  const links = run.status === "awaiting-approval" ? approvalLinks(tenant, workspace, run, config.email ?? null) : null;
   // At a gate the reader is being asked something; the question goes in the
   // mail, and so does what the run has concluded so far — the last finished
   // step's first line, which is the proposal's own summary ("… ·
@@ -238,10 +493,15 @@ export async function sendRunNotification(
             (asks.length ? `\n${asks.map((a) => `Question: ${a}`).join("\n")}\n` : "") +
             `\nworkspace: ${workspace}\nrun: ${run.id}\nflow: ${run.flow}\n` +
             `cost: $${runCost(run).toFixed(4)}\nstarted: ${run.startedAt}\nfinished: ${run.finishedAt ?? "-"}\n` +
-            (links ? `\nApprove: ${links.approveUrl}\nReject: ${links.rejectUrl}\n` : ""),
+            (links
+              ? links.links.length === 1
+                ? `\nApprove: ${links.approveUrl}\nReject: ${links.rejectUrl}\n`
+                : links.links.map((l) => `\nStep ${l.step + 1} (${l.agent})\nApprove: ${l.approveUrl}\nReject: ${l.rejectUrl}\n`).join("")
+              : ""),
         }),
         signal: AbortSignal.timeout(8000),
       });
+      noteMailUse(tenant, res.status);
       if (!res.ok) {
         // Resend's body says WHY — "domain not verified", "can only send to
         // your own address" — and a status alone sent someone to the wrong
@@ -263,10 +523,11 @@ export async function sendRunNotification(
       console.error(`[foldrun] notify: secret in URL not set for ${tenant}/${workspace}`);
       return false;
     }
+    const payload = JSON.stringify(body);
     const res = await fetch(url, {
       method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
+      headers: { "content-type": "application/json", ...signatureHeaders(tenant, workspace, config, payload) },
+      body: payload,
       signal: AbortSignal.timeout(5000),
     });
     if (!res.ok) {

package/src/paths.ts

@@ -77,3 +77,32 @@ export function dataRoot(): string {
 export function singleWorkspace(): string | null {
   return process.env.FOLDRUN_WORKSPACE ?? null;
 }
+
+// ------------------------------------------------------- linear trimming
+//
+// `s.replace(/\/+$/, "")` is the obvious way to drop trailing slashes and
+// it is quadratic: the engine tries `\/+` from every position and fails at
+// `$` each time, so a string of ten thousand slashes is fifty million
+// steps. Several of these strings come from a customer's own files — a
+// base_url, a tool's base, a storage prefix — which is exactly the input
+// that must not be able to stall a worker. A loop is linear and reads the
+// same.
+
+/** Without leading and/or trailing slashes. */
+export function trimSlashes(s: string, where: "start" | "end" | "both" = "end"): string {
+  let a = 0;
+  let b = s.length;
+  if (where !== "end") while (a < b && s[a] === "/") a++;
+  if (where !== "start") while (b > a && s[b - 1] === "/") b--;
+  return s.slice(a, b);
+}
+
+/** Without any of `chars` at the ends — the linear form of
+ *  `.replace(/^[chars]+/, "").replace(/[chars]+$/, "")`. */
+export function trimChars(s: string, chars: string): string {
+  let a = 0;
+  let b = s.length;
+  while (a < b && chars.includes(s[a])) a++;
+  while (b > a && chars.includes(s[b - 1])) b--;
+  return s.slice(a, b);
+}