@foldrun/core 8.0.1 → 9.1.0

package/dist/src/approvals.d.ts

@@ -127,19 +127,27 @@ export declare function decideApproval(tenant: string, workspace: string, runId:
  */
 export declare function expireStaleGate(tenant: string, workspace: string, run: RunRecord, now?: number): Promise<boolean>;
 /**
- * Release a run parked on `wait: event` with what arrived. The payload is
- * stored on the step — not as an approval note, which is a person's
- * guidance and capped as such — and the release itself is an approval
- * "by an external event", so the record reads the same way whichever door
- * a park was opened through.
+ * What a presented event token opens on a run (30 Oct 2026): `known` when
+ * it is a real token of this run — one of its parks, or the old per-run
+ * form — and `steps`, the waiting steps it releases now (none: a 409, the
+ * gate it was for is no longer waiting).
  *
- * Only steps waiting on an event are released: a run that is also asking a
- * person a question keeps asking.
+ * With `step` (the `&step=` every URL printed since carries), the token is
+ * that step's, bound to the moment it parked: the `t` of its "waiting for an
+ * external event" line. It releases that step only while that park is the
+ * step's current one — a released step is no longer waiting, and a step
+ * parked again (a loop) has a new `t` — so a URL handed out for one gate
+ * opens neither a later gate nor a later park.
  *
- * `by` names who delivered it when that is known — a signed-in person or a
- * key through the dashboard's approve route — and `step` releases one
- * waiting step rather than all of them.
+ * Without `step`, the per-run token URLs carried before then. It releases
+ * only a step still waiting under such a URL — its park line has no
+ * `step=` — so a run parked when this shipped can still be released, and
+ * nothing parked since can be released by the old form.
  */
+export declare function eventGatesFor(tenant: string, workspace: string, run: RunRecord, presented: string, step: number | null): {
+    known: boolean;
+    steps: number[];
+};
 export declare function deliverEvent(tenant: string, workspace: string, runId: string, payload: string, opts?: {
     by?: string;
     step?: number;

package/dist/src/approvals.js

@@ -12,7 +12,7 @@
 import crypto from "node:crypto";
 import { readRun, writeRun, readFlow, mayApprove } from "./store.js";
 import { platform } from "./platform.js";
-import { approveToken, installKey } from "./webhook.js";
+import { approveToken, eventToken, installKey } from "./webhook.js";
 // ----------------------------------------------------------------- links
 /** How long an emailed link decides for when the flow does not say. */
 export const APPROVE_LINK_DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
@@ -276,6 +276,56 @@ export async function expireStaleGate(tenant, workspace, run, now = Date.now())
  * key through the dashboard's approve route — and `step` releases one
  * waiting step rather than all of them.
  */
+const EVENT_WAIT_LINE = "waiting for an external event — release it with POST ";
+/**
+ * What a presented event token opens on a run (30 Oct 2026): `known` when
+ * it is a real token of this run — one of its parks, or the old per-run
+ * form — and `steps`, the waiting steps it releases now (none: a 409, the
+ * gate it was for is no longer waiting).
+ *
+ * With `step` (the `&step=` every URL printed since carries), the token is
+ * that step's, bound to the moment it parked: the `t` of its "waiting for an
+ * external event" line. It releases that step only while that park is the
+ * step's current one — a released step is no longer waiting, and a step
+ * parked again (a loop) has a new `t` — so a URL handed out for one gate
+ * opens neither a later gate nor a later park.
+ *
+ * Without `step`, the per-run token URLs carried before then. It releases
+ * only a step still waiting under such a URL — its park line has no
+ * `step=` — so a run parked when this shipped can still be released, and
+ * nothing parked since can be released by the old form.
+ */
+export function eventGatesFor(tenant, workspace, run, presented, step) {
+    const none = { known: false, steps: [] };
+    if (!presented)
+        return none;
+    const same = (want) => {
+        const a = Buffer.from(presented), b = Buffer.from(want);
+        return a.length === b.length && crypto.timingSafeEqual(a, b);
+    };
+    const parks = (i) => (run.steps[i]?.events ?? []).filter((e) => e?.text?.startsWith(EVENT_WAIT_LINE));
+    const waiting = (i) => {
+        const s = run.steps[i];
+        return !!s && s.status === "awaiting-approval" && s.waitFor === "event";
+    };
+    if (step !== null) {
+        const lines = parks(step);
+        const hit = lines.findIndex((e) => same(eventToken(tenant, workspace, run.id, { step, at: e.t })));
+        if (hit < 0)
+            return none;
+        // Only the step's latest park is open, and only while it waits.
+        return { known: true, steps: hit === lines.length - 1 && waiting(step) ? [step] : [] };
+    }
+    if (!same(eventToken(tenant, workspace, run.id)))
+        return none;
+    const legacy = [];
+    for (let i = 0; i < run.steps.length; i++) {
+        const last = parks(i).at(-1);
+        if (last && waiting(i) && !/[?&]step=\d/.test(last.text))
+            legacy.push(i);
+    }
+    return { known: true, steps: legacy };
+}
 export async function deliverEvent(tenant, workspace, runId, payload, opts = {}) {
     const run = readRun(tenant, workspace, runId);
     if (!run)

package/dist/src/catalog.d.ts

@@ -45,6 +45,20 @@ export declare const CATALOG_MAX_BYTES: number;
  * there is nothing at all to fall back on.
  */
 export declare function loadCatalog(baseUrl: string): Promise<Catalog | null>;
+/** How long after an attempt a background refresh of the same gateway is
+ *  not tried again, whether it worked or not. */
+export declare const CATALOG_RETRY_MS: number;
+/**
+ * Refresh a gateway's catalogue behind the caller, at most once per
+ * CATALOG_RETRY_MS per gateway (30 Oct 2026). For the editor's completions and
+ * the flows page, which ask on every request: a stale or missing catalogue
+ * used to start a fresh outbound fetch each time — a 10 s one per keystroke
+ * against an unreachable gateway, nothing remembering that it had just
+ * failed. The attempt is noted before it starts, so callers arriving while
+ * one is in flight do not start another. True when one was started. A run's
+ * own read (loadCatalog) is untouched.
+ */
+export declare function refreshCatalogSoon(baseUrl: string, load?: (baseUrl: string) => Promise<unknown>, now?: number): boolean;
 /** A preset reference — settings live in the gateway's dashboard, opaque to
  *  us on purpose. The catalogue offers no opinion on one. */
 export declare const isPresetRef: (model: string) => boolean;

package/dist/src/catalog.js

@@ -118,6 +118,34 @@ export async function loadCatalog(baseUrl) {
         return cached; // stale beats nothing; null when there is no nothing
     }
 }
+/** How long after an attempt a background refresh of the same gateway is
+ *  not tried again, whether it worked or not. */
+export const CATALOG_RETRY_MS = 5 * 60_000;
+const lastTried = new Map();
+/**
+ * Refresh a gateway's catalogue behind the caller, at most once per
+ * CATALOG_RETRY_MS per gateway (30 Oct 2026). For the editor's completions and
+ * the flows page, which ask on every request: a stale or missing catalogue
+ * used to start a fresh outbound fetch each time — a 10 s one per keystroke
+ * against an unreachable gateway, nothing remembering that it had just
+ * failed. The attempt is noted before it starts, so callers arriving while
+ * one is in flight do not start another. True when one was started. A run's
+ * own read (loadCatalog) is untouched.
+ */
+export function refreshCatalogSoon(baseUrl, load = loadCatalog, now = Date.now()) {
+    const cached = readCatalog(baseUrl);
+    if (cached && now - Date.parse(cached.fetchedAt) < TTL_MS)
+        return false; // fresh: nothing to fetch
+    const last = lastTried.get(baseUrl);
+    if (last !== undefined && now - last < CATALOG_RETRY_MS)
+        return false;
+    lastTried.delete(baseUrl);
+    lastTried.set(baseUrl, now);
+    if (lastTried.size > 1000)
+        lastTried.delete(lastTried.keys().next().value);
+    void load(baseUrl).catch(() => null);
+    return true;
+}
 /** A preset reference — settings live in the gateway's dashboard, opaque to
  *  us on purpose. The catalogue offers no opinion on one. */
 export const isPresetRef = (model) => model.startsWith("@preset/");

package/dist/src/cron.d.ts

@@ -15,3 +15,12 @@ export interface Cron {
 export declare function parseCron(expr: string): Cron | null;
 /** Why `schedule:` is not a cron the scheduler can run, or null when it is. */
 export declare function cronProblem(expr: unknown): string | null;
+/**
+ * Whether the calendar has any day this cron names (30 Oct 2026). `0 0 30 2 *`
+ * parses — every field is in range — yet no February has a 30th, so a search
+ * for its next fire walked the whole window every time it was asked (the
+ * schedule page did, 57,600 minutes per flow per request). Answered from the
+ * fields alone: only a day of the month with no weekday beside it can miss,
+ * since with a weekday either may match and every month has every weekday.
+ */
+export declare function cronCanFire(cron: Cron): boolean;

package/dist/src/cron.js

@@ -105,3 +105,23 @@ export function cronProblem(expr) {
         ? `schedule: "${expr}" has ${fields} field${fields === 1 ? "" : "s"}; cron has five — minute hour day-of-month month day-of-week ("0 9 * * MON"), or @hourly, @daily, @weekly, @monthly. As written the flow never fires`
         : `schedule: "${expr}" is not a cron the scheduler can read — a field is out of range or not a number (minute 0-59, hour 0-23, day 1-31, month 1-12, weekday 0-7 or sun-sat). As written the flow never fires`;
 }
+/** Days in each month, February at its leap-year 29: a cron naming the 29th
+ *  of February does fire, every fourth year. */
+const MONTH_DAYS = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/**
+ * Whether the calendar has any day this cron names (30 Oct 2026). `0 0 30 2 *`
+ * parses — every field is in range — yet no February has a 30th, so a search
+ * for its next fire walked the whole window every time it was asked (the
+ * schedule page did, 57,600 minutes per flow per request). Answered from the
+ * fields alone: only a day of the month with no weekday beside it can miss,
+ * since with a weekday either may match and every month has every weekday.
+ */
+export function cronCanFire(cron) {
+    if (!cron.domRestricted || cron.dowRestricted)
+        return true;
+    const firstDay = Math.min(...cron.dom);
+    for (const m of cron.month)
+        if (firstDay <= MONTH_DAYS[m - 1])
+            return true;
+    return false;
+}

package/dist/src/frontmatter-fields.js

@@ -109,7 +109,7 @@ const FLOW = [
     { key: "catchup", type: "string", validated: true, help: "last | none" },
     { key: "on", type: "string", validated: true, help: "trigger: flow — completed | failed | blocked | any" },
     { key: "signature", type: "string", validated: true, help: "github | stripe | slack | hmac" },
-    { key: "signing_secret", type: "string", help: "the secret a webhook's signature is checked with" },
+    { key: "signing_secret", type: "string", help: "the NAME of the vault secret a webhook's signature is checked with — never the value" },
     { key: "after", type: ["string", "list"], help: "trigger: flow — the flow this one follows" },
     { key: "at", type: "string", help: "trigger: once — when" },
     { key: "url", type: "string", help: "trigger: watch — the page watched" },

package/dist/src/frontmatter-schema.d.ts

@@ -2,7 +2,7 @@ import { type SchemaKind } from "./frontmatter-fields.ts";
 export { FRONTMATTER, schemaKindOf, type FieldSpec, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
 export interface FieldProblem {
     key: string;
-    rule: "config/unknown-field" | "config/wrong-type" | "config/invalid-value" | "config/missing-field" | "config/conflict" | "config/misplaced";
+    rule: "config/unknown-field" | "config/wrong-type" | "config/invalid-value" | "config/missing-field" | "config/conflict" | "config/misplaced" | "config/cron-never-fires" | "secret/signing-secret-value";
     level: "error" | "warn" | "info";
     message: string;
 }
@@ -13,3 +13,7 @@ export interface FieldProblem {
  * `near` is the typo matcher; scan.ts passes its own.
  */
 export declare function frontmatterProblems(kind: SchemaKind, data: Record<string, unknown>, near: (key: string, known: readonly string[]) => string | null): FieldProblem[];
+/** Why a `signing_secret:` value is not a vault secret's name, or null. The
+ *  runtime reads `NAME` and `${NAME}` alike (notify.ts, store.ts). Never
+ *  says what the value is: it may be the secret itself. */
+export declare function signingSecretProblem(v: unknown): string | null;

package/dist/src/frontmatter-schema.js

@@ -5,7 +5,8 @@ import { FRONTMATTER, JOBS } from "./frontmatter-fields.js";
 import { jobFold } from "./matter.js";
 import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS } from "./store.js";
 import { budgetProblem } from "./budget.js";
-import { cronProblem } from "./cron.js";
+import { cronProblem, parseCron, cronCanFire } from "./cron.js";
+import { SECRET_NAME } from "./secrets.js";
 import { modelSecretCollision } from "./model-credential.js";
 import { resourcesProblem, computeProblem } from "./resources.js";
 export { FRONTMATTER, schemaKindOf } from "./frontmatter-fields.js";
@@ -163,11 +164,49 @@ export function frontmatterProblems(kind, data, near) {
         if (why)
             out.push({ key, rule: "config/invalid-value", level: "warn", message: `\`${key}:\` ${why.replace(/^\w+: /, "")}` });
     }
+    // A cron every field of which is in range, on a day no month has —
+    // `0 0 30 2 *`. The scheduler's own cronCanFire decides (30 Oct 2026), so
+    // check and the scheduler say the same about it: it never fires.
+    if (kind === "flow" && typeof data.schedule === "string") {
+        const cron = parseCron(data.schedule);
+        if (cron && !cronCanFire(cron)) {
+            out.push({ key: "schedule", rule: "config/cron-never-fires", level: "warn", message: `\`schedule: "${data.schedule}"\` names a day no month it allows has — the flow never fires. Pick a day every named month has, or add a weekday` });
+        }
+    }
+    // A signing secret is the NAME of a vault entry (30 Oct 2026): a flow's
+    // `signing_secret:` and notify's `signing_secret:` are looked up with
+    // getSecret, so a literal value there is a secret written into a
+    // versioned, deployed file — and never matches anything in the vault.
+    // The message never repeats the value.
+    if (kind === "flow" && data.signing_secret !== undefined) {
+        const why = signingSecretProblem(data.signing_secret);
+        if (why)
+            out.push({ key: "signing_secret", rule: "secret/signing-secret-value", level: "warn", message: `\`signing_secret:\` ${why}` });
+    }
+    if (kind === "agents-md" && data.notify && typeof data.notify === "object" && !Array.isArray(data.notify)) {
+        const raw = data.notify.signing_secret;
+        const why = raw === undefined ? null : signingSecretProblem(raw);
+        if (why)
+            out.push({ key: "notify", rule: "secret/signing-secret-value", level: "warn", message: `\`notify: signing_secret:\` ${why}` });
+    }
     if (kind === "skill" && !(typeof data.description === "string" && data.description.trim())) {
         out.push({ key: "description", rule: "config/missing-field", level: "warn", message: "no `description:` — a skill without one is never loaded; the model chooses a skill by it" });
     }
     return out;
 }
+/** Why a `signing_secret:` value is not a vault secret's name, or null. The
+ *  runtime reads `NAME` and `${NAME}` alike (notify.ts, store.ts). Never
+ *  says what the value is: it may be the secret itself. */
+export function signingSecretProblem(v) {
+    if (typeof v !== "string")
+        return null; // config/wrong-type says so
+    const name = v.trim().replace(/^\$\{|\}$/g, "");
+    if (!name)
+        return null;
+    return SECRET_NAME.test(name)
+        ? null
+        : "holds something that is not a secret's name (UPPER_SNAKE_CASE, like WEBHOOK_SIGNING_KEY) — it is looked up in the vault by name, so a value written here is never found, and is deployed and versioned in plain text. Put the value in the vault (`foldrun secrets set NAME`), write the name here, and rotate it";
+}
 function askProblem(v) {
     const t = v?.timeout;
     return t === undefined ? null : DURATION(30, 86400, "30s to 24h")(t);

package/dist/src/history.d.ts

@@ -35,6 +35,11 @@ export interface RevisionSummary {
     commit: string | null;
     paths: string[];
 }
+/** Refuse (400) a deploy's `commit` that cannot be a revision id. A writer
+ *  calls this BEFORE it writes: checked only in recordRevision, after the
+ *  files were replaced, a bad commit left the new source live with no
+ *  revision, no snapshot and no audit entry (30 Oct 2026). */
+export declare function assertCommitId(commit: string): void;
 /** A local revision id: sortable by time, unique enough, visibly not a sha. */
 export declare function newRevisionId(now?: Date): string;
 /**

package/dist/src/history.js

@@ -55,6 +55,15 @@ const historyDir = (tenant, scope) => {
         assertSafeName(scope, "workspace");
     return path.join(dataRoot(), tenant, ".history", scope);
 };
+/** Refuse (400) a deploy's `commit` that cannot be a revision id. A writer
+ *  calls this BEFORE it writes: checked only in recordRevision, after the
+ *  files were replaced, a bad commit left the new source live with no
+ *  revision, no snapshot and no audit entry (30 Oct 2026). */
+export function assertCommitId(commit) {
+    if (typeof commit !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._@-]{0,120}$/.test(commit)) {
+        throw Object.assign(new Error(`commit "${String(commit).slice(0, 130)}" is not a commit id — letters, digits and . _ @ -, at most 121 characters`), { status: 400 });
+    }
+}
 /** A local revision id: sortable by time, unique enough, visibly not a sha. */
 export function newRevisionId(now = new Date()) {
     return `r-${now.getTime().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
@@ -72,8 +81,17 @@ export function recordRevision(tenant, scope, files, meta = {}) {
         return null;
     const dir = historyDir(tenant, scope);
     fs.mkdirSync(dir, { recursive: true });
+    // A commit is the revision's id only the first time it is recorded. A
+    // second deploy of one commit (a CI re-run after a dashboard edit), or a
+    // `commit` that names a revision already here, overwrote that revision's
+    // record and its snapshot (30 Oct 2026) — History could no longer restore
+    // to it. It gets its own id now; `commit` still says which one it was,
+    // and a restore by commit (resolveRevision) still finds it.
+    if (meta.commit)
+        assertCommitId(meta.commit);
+    const commitId = meta.commit && !fs.existsSync(path.join(dir, `${meta.commit}.json`)) ? meta.commit : null;
     const rev = {
-        id: meta.id ?? meta.commit ?? newRevisionId(),
+        id: meta.id ?? commitId ?? newRevisionId(),
         at: new Date().toISOString(),
         by: meta.by ?? "system",
         message: meta.message ?? describe(changed),
@@ -252,7 +270,11 @@ export function resolveRevision(tenant, scope, to, now = Date.now()) {
     else {
         if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/.test(t))
             throw Object.assign(new Error(`not a revision or a time: ${to}`), { status: 400 });
-        hit = all.find((r) => r.id === t || r.commit === t || (t.length >= 7 && r.commit?.startsWith(t)));
+        // An exact id first, then a commit: a commit deployed twice is recorded
+        // once under its own id and again under a fresh one naming it (30 Oct
+        // 2026, recordRevision), and newest-first with one predicate answered
+        // the first revision's id with the second's snapshot.
+        hit = all.find((r) => r.id === t) ?? all.find((r) => r.commit === t || (t.length >= 7 && r.commit?.startsWith(t)));
     }
     return hit ? { id: hit.id, at: hit.at, by: hit.by, message: hit.message } : null;
 }
@@ -353,8 +375,13 @@ export function changedPathsBetween(tenant, scope, from, to) {
     if (from === to)
         return [];
     const revs = listRevisions(tenant, scope, { limit: 500 }); // newest first
-    const ti = revs.findIndex((r) => r.id === to || r.commit === to);
-    const fi = revs.findIndex((r) => r.id === from || r.commit === from);
+    // An exact id before a commit, as resolveRevision.
+    const at = (x) => {
+        const byId = revs.findIndex((r) => r.id === x);
+        return byId >= 0 ? byId : revs.findIndex((r) => r.commit === x);
+    };
+    const ti = at(to);
+    const fi = at(from);
     if (ti < 0 || fi < 0 || ti > fi)
         return null;
     return [...new Set(revs.slice(ti, fi).flatMap((r) => r.paths))].sort();

package/dist/src/hooks.d.ts

@@ -6,6 +6,8 @@ export declare const HOOK_TIMEOUT_DEFAULT: {
 };
 export declare const HOOK_TIMEOUT_MAX = 120;
 export declare const HOOK_CODE_MAX: number;
+/** A hook's name: its folder's name, never a path. */
+export declare function isHookName(name: unknown): name is string;
 export interface HookDef {
     name: string;
     /** The folder holding hook.md and run.mjs. */

package/dist/src/hooks.js

@@ -38,6 +38,10 @@ export const HOOK_TIMEOUT_DEFAULT = { gate: 30, watch: 60 };
 export const HOOK_TIMEOUT_MAX = 120;
 export const HOOK_CODE_MAX = 100 * 1024;
 const NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** A hook's name: its folder's name, never a path. */
+export function isHookName(name) {
+    return typeof name === "string" && NAME.test(name);
+}
 /** Read hook.md, or say in one sentence why it is not a hook. */
 export function readHookDef(dir, scope) {
     const name = path.basename(dir);
@@ -117,6 +121,15 @@ export function resolveHooks(args) {
         if (seen.has(name))
             continue;
         seen.add(name);
+        // Checked before the name is joined to anything (30 Oct 2026): readHookDef
+        // tested only basename(dir), so `../../<tenant>/workspaces/<ws>/hooks/<h>`
+        // passed, and the hook test route answered which folders exist anywhere
+        // on the server — on a laptop it would have run that run.mjs. An error,
+        // not missing: a step refuses either way, and the name is the problem.
+        if (!isHookName(name)) {
+            errors.push(`"${name}" is not a hook name — lowercase letters, digits and dashes (the hook's folder name)`);
+            continue;
+        }
         const own = path.join(args.workspaceRoot, "hooks", name);
         const shared = path.join(args.libraryRoot, "hooks", name);
         const dir = fs.existsSync(own) ? own : fs.existsSync(shared) ? shared : null;

package/dist/src/library.js

@@ -234,6 +234,10 @@ export function deleteLibraryPath(tenant, kind, rel, meta = {}) {
     const norm = path.normalize(rel);
     if (norm.startsWith("..") || path.isAbsolute(norm))
         throw new Error(`illegal path: ${rel}`);
+    // "." (or "./", "a/..") is the shelf itself: one call took every shared
+    // tool or skill from every workspace (30 Oct 2026). Name what goes.
+    if (norm === "." || norm === "./")
+        throw new Error(`illegal path: ${rel} — name the file or folder to delete, not the whole ${kind} shelf`);
     const target = path.join(libraryDir(tenant, kind), norm);
     const gone = [];
     if (fs.existsSync(target)) {

package/dist/src/notify.d.ts

@@ -15,8 +15,11 @@ export declare function platformMail(tenant: string): {
     key: string;
     from: string;
 } | null;
-/** The account's own Resend key and sender, or null when it has none. */
-export declare function accountMail(tenant: string): {
+/** The account's own Resend key and sender, or null when it has none.
+ *  With a workspace — mail a workspace's run causes — an account key or
+ *  sender limited to other workspaces is not used (30 Oct 2026); the
+ *  account's own mail (resets, invites) names none and is not limited. */
+export declare function accountMail(tenant: string, workspace?: string): {
     key: string;
     from: string;
 } | null;
@@ -30,7 +33,7 @@ export declare function accountMail(tenant: string): {
  * owner's bin. The platform's key is the fallback for an account that set
  * none, so `notify:` works before anyone has configured mail at all.
  */
-export declare function notifyMail(tenant: string): {
+export declare function notifyMail(tenant: string, workspace?: string): {
     key: string;
     from: string;
 } | null;
@@ -78,10 +81,24 @@ export declare function nextAttemptAt(n: number, at: number): number | null;
  *  delivery, redeliveries included, so a receiver dedupes on it. */
 export declare function newDeliveryId(): string;
 /** The URL with ${SECRET}s resolved, and how it may be shown: a Slack hook
- *  URL is itself a credential, so it is never echoed resolved. */
+ *  URL is itself a credential, so it is never echoed resolved.
+ *
+ *  A secret bound to sites (`foldrun secrets sites`) is filled only when the
+ *  resolved URL's host is one of them — the rule the egress proxy and the
+ *  tool tester keep (30 Oct 2026). Before, notify.url filled any secret into
+ *  any host, so an editor could write `https://their.server/?k=${STRIPE_KEY}`
+ *  and press Test. The host is read AFTER filling, because the usual shape is
+ *  the whole URL as one secret (`${SLACK_WEBHOOK_URL}`, bound to
+ *  hooks.slack.com). An unbound secret fills as it does for an agent's
+ *  `secrets:` and a tool test — workspace first, then the account — since
+ *  binding is how an account says where a value may go. `refused` says why
+ *  `url` is null when a binding stopped it; `filled` maps each value put
+ *  into the URL to its name, so an error that echoes the URL can be scrubbed. */
 export declare function webhookTarget(tenant: string, workspace: string, config?: NotifyConfig | null): {
     url: string | null;
     shown: string;
+    refused?: string;
+    filled: Record<string, string>;
 };
 export interface WebhookAttempt {
     /** 1-based. */