@foldrun/core 0.3.0 → 0.4.0

package/dist/src/trigger-log.js

@@ -0,0 +1,122 @@
+// Why nothing happened.
+//
+// A run that exists can be read. A run that does not exist leaves no record
+// anywhere, and "the hook fired but nothing ran" is the hardest question the
+// platform gets asked — because every honest answer to it is a thing that
+// deliberately did NOT happen:
+//
+//   the delivery was a duplicate          idempotency:
+//   the burst is still being waited out   debounce:
+//   it arrived inside the window          throttle:
+//   the flow is switched off              disable_after:
+//   yesterday's run is still going        overlap: skip
+//   the platform was down at 05:00        catchup: none
+//
+// Six different reasons, all of them correct behaviour, none of them visible.
+// Before this they were console lines on a box nobody reads.
+//
+// This is deliberately NOT the hook delivery log next door. That one answers
+// "did the request reach us and was it authentic" — a bad token, a failed
+// signature. This one answers "did an event become a run". A delivery can be
+// perfectly authentic and still not start anything, which is exactly the
+// case that needed writing down.
+//
+// One bounded JSONL per workspace, the same shape and the same compaction as
+// the delivery log: this is diagnostics, not an audit trail, and it must
+// never become a disk-full incident with a delay.
+import fs from "node:fs";
+import path from "node:path";
+import { workspaceDir } from "./store.js";
+function logFile(tenant, workspace) {
+    return path.join(workspaceDir(tenant, workspace), "trigger-log.jsonl");
+}
+const KEEP = 500;
+/** Never throws. A diagnostic that can break a trigger is worse than no
+ *  diagnostic: the whole point is to be reading it on the bad morning. */
+export function recordTriggerEvent(tenant, workspace, event) {
+    try {
+        const file = logFile(tenant, workspace);
+        if (!fs.existsSync(path.dirname(file)))
+            return;
+        fs.appendFileSync(file, JSON.stringify(event) + "\n");
+        const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+        if (lines.length > KEEP * 2) {
+            const tmp = `${file}.tmp`;
+            fs.writeFileSync(tmp, lines.slice(-KEEP).join("\n") + "\n");
+            fs.renameSync(tmp, file);
+        }
+    }
+    catch {
+        // best effort, always
+    }
+}
+export function readTriggerEvents(tenant, workspace, limit = 200) {
+    let lines;
+    try {
+        lines = fs.readFileSync(logFile(tenant, workspace), "utf8").split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    // One line at a time: a torn line — an append racing a compaction from
+    // another pod — must lose that line, not the whole log, on exactly the
+    // morning the log exists for.
+    const out = [];
+    for (const line of lines.slice(-limit).reverse()) {
+        try {
+            const e = JSON.parse(line);
+            if (e && typeof e.t === "string")
+                out.push(e);
+        }
+        catch {
+            // skip the torn line
+        }
+    }
+    return out;
+}
+/**
+ * One row per flow: how often it fired, how often that became a run, and
+ * what happened to the difference.
+ *
+ * The gap between `fired` and `started` is the number someone is looking
+ * for. A flow with forty fires and two runs is either working exactly as
+ * configured or badly misconfigured, and the reasons column is what tells
+ * those apart without opening the flow file.
+ */
+export function summariseTriggers(tenant, workspace, sinceMs = null) {
+    const rows = new Map();
+    const reasons = new Map();
+    for (const e of readTriggerEvents(tenant, workspace, 500)) {
+        if (sinceMs !== null && new Date(e.t).getTime() < sinceMs)
+            continue;
+        let row = rows.get(e.flow);
+        if (!row) {
+            row = { flow: e.flow, trigger: e.trigger, fired: 0, started: 0, dropped: [], lastFiredAt: null, lastStartedAt: null };
+            rows.set(e.flow, row);
+            reasons.set(e.flow, new Map());
+        }
+        row.fired++;
+        // Events come back newest first, so the first of each is the latest.
+        row.lastFiredAt ??= e.t;
+        if (e.outcome === "started") {
+            row.started++;
+            row.lastStartedAt ??= e.t;
+        }
+        else {
+            const byReason = reasons.get(e.flow);
+            const seen = byReason.get(e.outcome);
+            // Keep the newest detail: "the last run started 4 minutes ago" is more
+            // use than the same sentence from Tuesday.
+            if (seen)
+                seen.count++;
+            else
+                byReason.set(e.outcome, { count: 1, detail: e.detail ?? "" });
+        }
+    }
+    for (const [flow, byReason] of reasons) {
+        rows.get(flow).dropped = [...byReason.entries()]
+            .map(([outcome, v]) => ({ outcome, ...v }))
+            .sort((a, b) => b.count - a.count);
+    }
+    return [...rows.values()].sort((a, b) => b.fired - a.fired || a.flow.localeCompare(b.flow));
+}

package/dist/src/triggers.d.ts

@@ -22,6 +22,26 @@ export declare function underPrefix(rel: string, prefix: string | null): boolean
  * a loop — every other writer counts.
  */
 export declare function fireStorageTriggers(tenant: string, workspace: string, paths: string[], by: string): Promise<string[]>;
+/**
+ * The value that identifies this delivery, as the flow's `idempotency:`
+ * names it.
+ *
+ * Two shapes, and only two:
+ *
+ *   idempotency: x-github-delivery   a request header
+ *   idempotency: body:id             a top-level field of a JSON body
+ *
+ * A NAME, never an expression — the grammar has no expressions, and this is
+ * not the place to grow one. Nothing is computed, combined or nested: if the
+ * sender does not put an identifier somewhere a name can reach, the flow
+ * cannot dedupe on it, and saying so is better than inventing a syntax.
+ *
+ * Returns null when the flow asks for no key, or when the delivery does not
+ * carry the one it asked for. A missing key admits the delivery: refusing
+ * one because a sender omitted a header would turn "dedupe when you can"
+ * into an outage.
+ */
+export declare function deliveryKey(idempotency: string | null, header: (name: string) => string | null, body: string): string | null;
 export interface SignatureVerdict {
     ok: boolean;
     reason: string;

package/dist/src/triggers.js

@@ -65,11 +65,24 @@ export async function fireChainedFlows(tenant, workspace, finished) {
         (result ? `\n${result}` : "");
     for (const flow of flows) {
         try {
-            const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "previous_run", body), flow.name, flow.model, [
-                `after:${finished.flow}`,
-            ]);
-            started.push(run.id);
-            console.log(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name} started after ${finished.flow} ${finished.status}`);
+            const gate = await platform.admitTrigger(tenant, workspace, flow, { body, tag: "previous_run" });
+            if (!gate.admit) {
+                console.log(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name} not started: ${gate.detail}`);
+                continue;
+            }
+            try {
+                // A test run's chain stays a test: the flow after it reads a result
+                // nothing real produced, and must not act on it for real either.
+                const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "previous_run", body), flow.name, flow.model, [
+                    `after:${finished.flow}`,
+                ], null, finished.test ? { test: true } : {});
+                started.push(run.id);
+                console.log(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name} started after ${finished.flow} ${finished.status}`);
+            }
+            catch (err) {
+                await platform.rollbackTrigger(tenant, workspace, flow, { reason: err instanceof Error ? err.message : String(err) });
+                throw err;
+            }
         }
         catch (err) {
             console.error(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name}:`, err instanceof Error ? err.message : err);
@@ -115,10 +128,23 @@ export async function fireStorageTriggers(tenant, workspace, paths, by) {
             continue;
         try {
             const body = `by: ${by}\n${hits.map((h) => `- storage/${h}`).join("\n")}`;
-            const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "storage_event", body), flow.name, flow.model, [
-                "storage",
-            ]);
-            started.push(run.id);
+            // A deploy that writes forty files under one prefix is one event, not
+            // forty runs — which is exactly what `debounce:` is for.
+            const gate = await platform.admitTrigger(tenant, workspace, flow, { body, tag: "storage_event" });
+            if (!gate.admit) {
+                console.log(`[foldrun] trigger: storage — ${tenant}/${workspace}/${flow.name} not started: ${gate.detail}`);
+                continue;
+            }
+            try {
+                const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "storage_event", body), flow.name, flow.model, [
+                    "storage",
+                ]);
+                started.push(run.id);
+            }
+            catch (err) {
+                await platform.rollbackTrigger(tenant, workspace, flow, { reason: err instanceof Error ? err.message : String(err) });
+                throw err;
+            }
         }
         catch (err) {
             console.error(`[foldrun] trigger: storage — ${tenant}/${workspace}/${flow.name}:`, err instanceof Error ? err.message : err);
@@ -126,6 +152,61 @@ export async function fireStorageTriggers(tenant, workspace, paths, by) {
     }
     return started;
 }
+/** HTML to the text a prompt reads. Style and script blocks are removed
+ *  until none remain — one pass leaves `<sty<style>le>` behind, which is
+ *  the shape a sanitiser checker (rightly) flags. Nothing here is rendered
+ *  as HTML afterwards; it becomes a task for an agent. */
+function stripTags(html) {
+    let out = html;
+    for (let prev = ""; prev !== out;) {
+        prev = out;
+        out = out.replace(/<(style|script)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "");
+    }
+    return out.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+}
+// ------------------------------------------------------- idempotency keys
+/**
+ * The value that identifies this delivery, as the flow's `idempotency:`
+ * names it.
+ *
+ * Two shapes, and only two:
+ *
+ *   idempotency: x-github-delivery   a request header
+ *   idempotency: body:id             a top-level field of a JSON body
+ *
+ * A NAME, never an expression — the grammar has no expressions, and this is
+ * not the place to grow one. Nothing is computed, combined or nested: if the
+ * sender does not put an identifier somewhere a name can reach, the flow
+ * cannot dedupe on it, and saying so is better than inventing a syntax.
+ *
+ * Returns null when the flow asks for no key, or when the delivery does not
+ * carry the one it asked for. A missing key admits the delivery: refusing
+ * one because a sender omitted a header would turn "dedupe when you can"
+ * into an outage.
+ */
+export function deliveryKey(idempotency, header, body) {
+    if (!idempotency)
+        return null;
+    if (idempotency.startsWith("body:")) {
+        const field = idempotency.slice(5).trim();
+        if (!field)
+            return null;
+        try {
+            const parsed = JSON.parse(body);
+            const value = parsed?.[field];
+            // A scalar only. An object stringifies to "[object Object]" for every
+            // delivery, which would make the second one and every one after it a
+            // "duplicate" of the first.
+            if (value === undefined || value === null || typeof value === "object")
+                return null;
+            return String(value).slice(0, 200);
+        }
+        catch {
+            return null; // not JSON, so no field to read
+        }
+    }
+    return header(idempotency)?.slice(0, 200) || null;
+}
 function safeEqual(a, b) {
     const x = Buffer.from(a);
     const y = Buffer.from(b);
@@ -259,7 +340,7 @@ export function normaliseInboundEmail(contentType, raw) {
     const subject = pick("subject", "Subject");
     const html = pick("html", "HtmlBody", "body-html");
     const text = pick("text", "TextBody", "body-plain", "stripped-text", "plain") ||
-        html.replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+        stripTags(html);
     if (!from && !subject && !text)
         return null;
     return { from, to: pick("to", "To", "recipient", "ToFull"), subject, text };

package/dist/src/webhook.d.ts

@@ -1,6 +1,13 @@
 /**
- * The install's secret key. Every derived token — flow hooks, git secrets —
- * hangs off this one value, so rotating it invalidates all of them together.
+ * The install's secret key. Every derived token — flow hooks, git secrets,
+ * approval links — hangs off this one value, so rotating it invalidates all
+ * of them together.
+ *
+ * The same material the vault encrypts with, created on first use. This used
+ * to fall back to the constant "foldrun-dev-install" until the vault lazily
+ * wrote `.secret-key`, which meant two things nobody wanted: every hook and
+ * approval token on a fresh install was computable from the source, and all
+ * of them silently changed the first time a secret was stored.
  */
 export declare function installKey(): string;
 export declare function hookGeneration(tenant: string, workspace: string, flow: string): number;
@@ -38,7 +45,12 @@ export declare function publicUrl(): string | null;
 export interface HookDelivery {
     t: string;
     flow: string;
-    outcome: "accepted" | "invalid-token" | "invalid-signature" | "not-webhook" | "no-flow" | "error";
+    /** `dropped` is a delivery that arrived, was authentic, and did not
+     *  become a run because the flow's own gates said one was enough —
+     *  a duplicate, a throttled burst, a quarantined flow. Distinct from
+     *  `accepted` so "why did nothing run" has an answer in the log, and
+     *  distinct from the refusals so nobody hunts for a bad token. */
+    outcome: "accepted" | "invalid-token" | "invalid-signature" | "not-webhook" | "no-flow" | "error" | "dropped";
     runId?: string;
     bytes?: number;
     detail?: string;

package/dist/src/webhook.js

@@ -3,22 +3,22 @@
 // per flow, and rotating FOLDRUN_SECRET_KEY invalidates every hook at once.
 import fs from "node:fs";
 import path from "node:path";
-import { dataRoot } from "./paths.js";
 import { workspaceDir } from "./store.js";
+import { installKeyMaterial } from "./secrets.js";
 import crypto from "node:crypto";
-const keyFile = () => path.join(dataRoot(), ".secret-key");
 /**
- * The install's secret key. Every derived token — flow hooks, git secrets —
- * hangs off this one value, so rotating it invalidates all of them together.
+ * The install's secret key. Every derived token — flow hooks, git secrets,
+ * approval links — hangs off this one value, so rotating it invalidates all
+ * of them together.
+ *
+ * The same material the vault encrypts with, created on first use. This used
+ * to fall back to the constant "foldrun-dev-install" until the vault lazily
+ * wrote `.secret-key`, which meant two things nobody wanted: every hook and
+ * approval token on a fresh install was computable from the source, and all
+ * of them silently changed the first time a secret was stored.
  */
 export function installKey() {
-    if (process.env.FOLDRUN_SECRET_KEY)
-        return process.env.FOLDRUN_SECRET_KEY;
-    if (fs.existsSync(keyFile()))
-        return fs.readFileSync(keyFile(), "utf8");
-    // secrets.ts creates this on first use; fall back to a fixed dev value so
-    // hook URLs stay stable before any secret has been set.
-    return "foldrun-dev-install";
+    return installKeyMaterial();
 }
 function hooksFile(tenant, workspace) {
     return path.join(workspaceDir(tenant, workspace), "hooks.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,13 +36,13 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.220",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.261",
     "gray-matter": "^4.0.3",
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22",
-    "typescript": "^5"
+    "@types/node": "^26",
+    "typescript": "^7"
   },
   "repository": {
     "type": "git",

package/src/approvals.ts

@@ -10,8 +10,10 @@
 // at a desk. So the decision lives in core and the routes only say who made
 // it.
 
-import { readRun, writeRun, type RunRecord } from "./store.ts";
+import crypto from "node:crypto";
+import { readRun, writeRun, readFlow, mayApprove, type FlowInfo, type RunRecord } from "./store.ts";
 import { platform } from "./platform.ts";
+import { approveToken, installKey } from "./webhook.ts";
 
 export interface ApprovalDecision {
   decision: "approve" | "reject";
@@ -23,6 +25,174 @@ export interface ApprovalDecision {
   step?: number;
   /** Who decided, as it reads after the verb: "by a human", "via emailed link". */
   by: string;
+  /**
+   * The person behind the decision, when a session made it: their email and
+   * the role they hold. A link and an external event have neither, and are
+   * checked by their token instead — the token IS the authority there.
+   *
+   * Two rules read this. `approvers:` in the flow file names who may decide
+   * that flow's gates at all. And nobody approves a run they started
+   * themselves: a gate exists so that a second person looks, and a flow a
+   * person kicked off and then waved through is a gate that never happened.
+   */
+  actor?: { email?: string | null; role?: string | null } | null;
+  /**
+   * The emailed link's token, when a link is deciding. Read here rather
+   * than trusted from the route, because what a link may decide is policy:
+   * the step it was minted for, before it expires, once, and never a gate
+   * whose flow names its approvers unless the link was minted for one of
+   * them. See readApproveLink.
+   */
+  link?: string;
+}
+
+// ----------------------------------------------------------------- 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;
+
+/** What a link may decide: one step, until a moment, as somebody or as
+ *  nobody. A `run` link is the older kind — bound to the run alone, and
+ *  kept working, once, for runs that were already waiting when this
+ *  changed. */
+export type ApproveLink =
+  | { kind: "step"; step: number; expiresAt: string; approver: string | null }
+  | { kind: "run" };
+
+/** The link's lifetime: the flow's `approve_within:` when it has one —
+ *  after that the gate has expired on its own — else a week. */
+export function approveLinkTtlMs(flow: Pick<FlowInfo, "approveWithin"> | null | undefined): number {
+  return flow?.approveWithin ? flow.approveWithin * 1000 : APPROVE_LINK_DEFAULT_TTL_MS;
+}
+
+const b64 = (s: string) => Buffer.from(s, "utf8").toString("base64url");
+const unb64 = (s: string) => Buffer.from(s, "base64url").toString("utf8");
+
+function signLink(tenant: string, workspace: string, runId: string, step: number, expires: number, approver: string): string {
+  return crypto
+    .createHmac("sha256", installKey())
+    .update(`approve-link:${tenant}/${workspace}/${runId}/${step}/${expires}/${approver}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * The token an emailed link carries. Bound to one step of one run and to
+ * a moment, and — when the notification went to a named approver — to
+ * that person, so the link decides as them. A link that was only bound
+ * to the run approved every later gate of that run for as long as it ran,
+ * and a forwarded one let anyone past `approvers:`.
+ *
+ * `step.expires.approver.signature`; the signature covers all of it plus
+ * the run's identity, under the install key, so rotating the key kills
+ * every link at once, the way it kills every hook.
+ */
+export function approveLinkToken(
+  tenant: string,
+  workspace: string,
+  runId: string,
+  link: { step: number; expiresAt: number; approver?: string | null },
+): string {
+  const approver = (link.approver ?? "").trim().toLowerCase();
+  const expires = Math.floor(link.expiresAt);
+  return `${link.step}.${expires}.${approver ? b64(approver) : "-"}.${signLink(tenant, workspace, runId, link.step, expires, approver)}`;
+}
+
+/** The path an emailed link opens — absolute when the caller prefixes the
+ *  install's public origin. `decision=reject` pre-selects; a GET never
+ *  decides. */
+export function approveLinkPath(
+  tenant: string,
+  workspace: string,
+  runId: string,
+  link: { step: number; expiresAt: number; approver?: string | null },
+): string {
+  return `/api/approve/${tenant}/${workspace}/${runId}?token=${approveLinkToken(tenant, workspace, runId, link)}`;
+}
+
+const same = (a: string, b: string) => a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+
+/**
+ * What a presented token is, or why it is nothing. 401 for a token that
+ * was never minted for this run, 410 for one that was and has expired —
+ * the second deserves a sentence, because the person holding it did
+ * nothing wrong.
+ */
+export function readApproveLink(
+  tenant: string,
+  workspace: string,
+  runId: string,
+  presented: string,
+  now = Date.now(),
+): { link: ApproveLink } | { error: string; status: 401 | 410 } {
+  const invalid = { error: "invalid token", status: 401 as const };
+  if (!presented) return invalid;
+  const parts = presented.split(".");
+  if (parts.length === 4) {
+    const [stepText, expText, approverText, sig] = parts;
+    if (!/^\d+$/.test(stepText) || !/^\d+$/.test(expText)) return invalid;
+    let approver = "";
+    try {
+      approver = approverText === "-" ? "" : unb64(approverText);
+    } catch {
+      return invalid;
+    }
+    const step = Number(stepText);
+    const expires = Number(expText);
+    if (!same(sig, signLink(tenant, workspace, runId, step, expires, approver))) return invalid;
+    if (now >= expires) return { error: "this link has expired — open the run in the dashboard to decide it", status: 410 };
+    return { link: { kind: "step", step, expiresAt: new Date(expires).toISOString(), approver: approver || null } };
+  }
+  if (same(presented, approveToken(tenant, workspace, runId))) return { link: { kind: "run" } };
+  return invalid;
+}
+
+/** A used link is written on the run as a digest, never the token. */
+const linkDigest = (token: string) => crypto.createHash("sha256").update(token).digest("hex").slice(0, 24);
+
+/**
+ * Everything a link has to pass before it decides anything, answered the
+ * same way for the page that shows the gate and the POST that decides it.
+ * Returns which waiting steps the link may decide and who it decides as.
+ */
+export function checkApproveLink(
+  tenant: string,
+  workspace: string,
+  run: RunRecord,
+  presented: string,
+  now = Date.now(),
+): { ok: true; link: ApproveLink; steps: number[]; approver: string | null } | { ok: false; status: number; message: string } {
+  const read = readApproveLink(tenant, workspace, run.id, presented, now);
+  if ("error" in read) return { ok: false, status: read.status, message: read.error };
+  const { link } = read;
+  if (run.approvalLinksUsed?.includes(linkDigest(presented))) {
+    return { ok: false, status: 409, message: "this link was already used — a link decides once" };
+  }
+  // The older, run-bound link: kept for runs already waiting, but not for
+  // longer than a new link would have been.
+  if (link.kind === "run") {
+    const since = Date.parse(run.parkedAt ?? run.startedAt);
+    if (Number.isFinite(since) && now - since > APPROVE_LINK_DEFAULT_TTL_MS) {
+      return { ok: false, status: 410, message: "this link has expired — open the run in the dashboard to decide it" };
+    }
+  }
+  const waiting = run.steps
+    .map((s, i) => ({ s, i }))
+    .filter(({ s, i }) => s.status === "awaiting-approval" && s.waitFor !== "event" && (link.kind === "run" || i === link.step))
+    .map(({ i }) => i);
+  const approver = link.kind === "step" ? link.approver : null;
+  // A flow that names its approvers is asking for a person; a link is a
+  // possession. Only a link minted for one of the named approvers carries
+  // enough of an identity to be checked against the list.
+  const flow = readFlow(tenant, workspace, run.flow);
+  if (flow?.approvers?.length && !approver) {
+    return {
+      ok: false,
+      status: 403,
+      message: `this flow names who may approve it (${flow.approvers.join(", ")}), and an emailed link carries no identity — sign in to the dashboard to decide it`,
+    };
+  }
+  return { ok: true, link, steps: waiting, approver };
 }
 
 /** An error the HTTP layer can map straight to a status — see errorResponse. */
@@ -52,9 +222,19 @@ export async function decideApproval(
   const run = readRun(tenant, workspace, runId);
   if (!run) throw new ApprovalError("run not found", 404);
 
+  // A link decides what it was minted for, as whom it was minted for.
+  let allowed: number[] | null = null;
+  if (d.link !== undefined) {
+    const check = checkApproveLink(tenant, workspace, run, d.link);
+    if (!check.ok) throw new ApprovalError(check.message, check.status);
+    allowed = check.steps;
+    d = { ...d, actor: check.approver ? { email: check.approver, role: null } : null };
+  }
+  assertMayDecide(tenant, workspace, run, d);
+
   const waiting = run.steps
     .map((s, i) => ({ s, i }))
-    .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i));
+    .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i) && (allowed === null || allowed.includes(i)));
   if (waiting.length === 0) throw new ApprovalError("nothing is awaiting approval", 409);
 
   const note = typeof d.note === "string" ? d.note.trim() : "";
@@ -83,6 +263,16 @@ export async function decideApproval(
           : `rejected ${d.by}${reason ? `: ${reason.slice(0, 200)}` : ""}`,
     });
   }
+  // The deadline belonged to the gate that just closed. Leaving it on the
+  // record would hand a later gate in the same run a deadline that has
+  // already passed.
+  if (run.steps.every((s) => s.status !== "awaiting-approval")) run.approveBy = null;
+  // A link decides once. Written as a digest on the record, so a step that
+  // parks again — a loop, a rerun from the gate — is not decided by the
+  // same forwarded mail.
+  if (d.link !== undefined) {
+    run.approvalLinksUsed = [...(run.approvalLinksUsed ?? []), linkDigest(d.link)].slice(-50);
+  }
   writeRun(tenant, workspace, run);
 
   // A parked run has no process polling for this decision — the worker
@@ -96,6 +286,67 @@ export async function decideApproval(
   return { run, steps: waiting.map(({ i }) => i) };
 }
 
+/**
+ * The two rules a person's decision has to pass. A token-bearing door — the
+ * emailed link, an external event — carries no actor and is not checked
+ * here: possession of a token derived from the run is its own authority,
+ * and the link was mailed to whoever the account told us to ask.
+ *
+ * Throws 403, which the routes surface verbatim: a refusal that does not say
+ * which rule refused sends someone to the wrong settings page.
+ */
+function assertMayDecide(tenant: string, workspace: string, run: RunRecord, d: ApprovalDecision): void {
+  if (!d.actor) return;
+  const email = (d.actor.email ?? "").trim().toLowerCase();
+  // Rejecting your own run is always allowed: stopping something you started
+  // needs no second opinion, and the gate's whole purpose is that it does
+  // not proceed. Only approval needs someone else.
+  if (d.decision === "approve" && email && run.startedBy && run.startedBy === email) {
+    throw new ApprovalError(
+      "you started this run — an approval gate asks a second person, so someone else has to answer it",
+      403,
+    );
+  }
+  const flow = readFlow(tenant, workspace, run.flow);
+  if (!mayApprove(flow, d.actor)) {
+    throw new ApprovalError(
+      `this flow's approvers: list does not include you (${flow?.approvers?.join(", ")})`,
+      403,
+    );
+  }
+}
+
+/**
+ * A gate that ran out of time. `approve_within:` in the flow file stamps a
+ * deadline when the run parks; past it, the gate is rejected and the run
+ * fails, exactly as if a person had said no.
+ *
+ * Rejection, not approval, is the only safe way for a clock to answer a
+ * question a person was asked. The whole reason the step is parked is that
+ * someone wanted to look at it first.
+ *
+ * Returns whether it acted. Called from the same sweep that closes abandoned
+ * runs, so an expiry needs nothing running of its own.
+ */
+export async function expireStaleGate(
+  tenant: string,
+  workspace: string,
+  run: RunRecord,
+  now = Date.now(),
+): Promise<boolean> {
+  if (run.status !== "awaiting-approval" || !run.approveBy) return false;
+  if (now < new Date(run.approveBy).getTime()) return false;
+  // A step waiting on `wait: event` is not waiting on a person and is not
+  // this deadline's business.
+  if (!run.steps.some((s) => s.status === "awaiting-approval" && s.waitFor !== "event")) return false;
+  await decideApproval(tenant, workspace, run.id, {
+    decision: "reject",
+    by: "automatically — nobody answered in time",
+    reason: `no decision within the flow's approve_within: (due ${run.approveBy})`,
+  });
+  return true;
+}
+
 /**
  * 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