toolroll 0.9.104 → 0.9.105

package/dist/flow-triggers.js

@@ -1,35 +1,5 @@
 import { adapterPolicy } from "./server/route-policy.js";
 import { html, htmlString, postForm, styleElement } from "./html.js";
-/**
- * Flow triggers (v82): what starts cards in a flow without someone adding
- * them by hand.
- *
- * - button   — a named button with questions; pressing it makes a card from the answers.
- * - schedule — a card on a schedule (every N minutes, daily, weekdays, weekly), or a standing order's task;
- *              v90: or a project script run on the schedule, each item it prints a card.
- * - github   — new issues (optionally with a label), new pull requests, or failed checks on a branch.
- * - linear   — Linear issues in a team, moving into a state, and/or with a label.
- * - flow     — another flow's cards reaching one of its zones.
- * - webhook  — anything that can post JSON to the trigger's secret address.
- * - email    — mail arriving in a folder of the account set up in Settings → Email (v89),
- *              read-only over IMAP; optionally only from some senders or with words in the subject.
- * - chat     — messages in a Slack, Discord or Teams channel (v89), connected from the
- *              channel itself (chat-inbox.ts), never from here.
- * - plane-review — every day at a set time (07:30 in the computer's time zone unless it says),
- *              the plane's last 24 hours read straight from the store (plane-review.ts): one card
- *              per distinct problem worth fixing, and the same problem on a later day joins its
- *              card while that card is still open. A clean day makes nothing. Waits only a person
- *              can end make no card; ones over three days are mentioned once in its summary line,
- *              linked to Needs you. Its row is kept as a
- *              'schedule' (the table's kinds are fixed); its settings say what it is.
- *
- * GitHub and Linear are checked by the worker's pass — `gh` and one HTTPS
- * request, never a model — or pushed to a secret webhook address when the
- * console has a public one. Either way one outside thing makes at most one
- * card; outside text is checked for keys before it becomes a card; GitHub
- * text from outside the team is left out unless the trigger says anyone;
- * and a card's work is an ordinary task under the usual approvals.
- */
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { SecretStoreError, readHeldSecret, writeHeldSecret } from "./tool-secret-store.js";
@@ -55,25 +25,15 @@ import { isRecord } from "./is-record.js";
 import { folderAnswers } from "./folder-gate.js";
 export { FLOW_TRIGGER_KINDS };
 export const CHAT_APP_NAMES = { slack: "Slack", discord: "Discord", teams: "Teams", telegram: "Telegram" };
-/** What each kind is called on the canvas. */
 export const FLOW_TRIGGER_WORDS = {
     button: "Button", schedule: "Schedule", github: "GitHub", linear: "Linear", flow: "Another flow", webhook: "Webhook", email: "Email inbox", chat: "Chat channel", "plane-review": "Plane review",
 };
-/** How often the worker checks GitHub and Linear, and how it backs off when they don't answer. */
 export const POLL_EVERY_MS = 2 * 60_000;
 const BACKOFF_MS = [5 * 60_000, 15 * 60_000, 60 * 60_000];
-/** At most this many cards from one check or one delivery; the rest wait for the next. */
 export const CARDS_PER_CHECK = 10;
 const HOOK_BYTES = 1_000_000;
-/** Authors GitHub says have write access to the repository. */
 const TEAM = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
-// ------------------------------------------------------------ the terms
 const HIDDEN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/;
-/**
- * A trigger's settings read by their one schema (`label: required`, `unknown key 'flows'`). A setting given as null is
- * left out, and a button's blank question lines are dropped, as every release has read them. Then what the schema can't
- * say, named by its path: no hidden characters and nothing that looks like a key, anywhere in the settings.
- */
 export function readTriggerSettings(raw) {
     const body = isRecord(raw) ? Object.fromEntries(Object.entries(raw).filter(([, value]) => value !== null).map(([key, value]) => [key, key === "questions" && Array.isArray(value) ? value.filter(one => typeof one !== "string" || one.trim() !== "") : value])) : raw;
     const read = parseContract(triggerInputSchema, body, FLOW_ALIASES);
@@ -92,7 +52,6 @@ export function readTriggerSettings(raw) {
     }
     return read;
 }
-/** A schedule said in words ("every 2 hours", "daily 09:00 Europe/London", "monday 09:00") or in its stored form ("daily:09:00"). */
 export function scheduleFromWords(text) {
     const raw = text.trim().replace(/\s+/g, " ");
     if (parseSchedule(raw) !== null)
@@ -123,9 +82,7 @@ export function scheduleFromWords(text) {
     }
     return null;
 }
-/** A GitHub repository as owner/name, read from a project's origin remote when it is on GitHub. */
 export function githubRepoOf(path) {
-    // In the console, a folder that hasn't answered a look lately is not read on its thread (folder-gate.ts).
     if (!folderAnswers(path))
         return null;
     try {
@@ -139,10 +96,7 @@ export function githubRepoOf(path) {
         return null;
     }
 }
-/** A trigger's settings, checked whole against the flow it starts cards in (readTriggerSettings, then the flow, its zones,
- * the project's scripts and the schedule). Throws FlowContractError, each line naming its setting. */
 export function validateTriggerConfig(raw, context) {
-    // Connecting a channel proves it's one the person is in: it happens in the channel, not here.
     if (isRecord(raw) && raw["kind"] === "chat")
         throw new FlowContractError([`kind: connect a chat channel from the channel itself: where Toolroll is in Slack, Discord, Teams or a Telegram group, send “flow ${context.flow.id}”`]);
     const read = readTriggerSettings(raw);
@@ -150,7 +104,6 @@ export function validateTriggerConfig(raw, context) {
         throw new FlowContractError(read.issues.map(one => one.line));
     const input = read.value;
     const refuse = (path, what) => { throw new FlowContractError([`${path}: ${what}`]); };
-    /** A setting's words, trimmed; blank is left out. */
     const said = (value) => value === undefined || value.trim() === "" ? null : value.trim();
     const named = said(input.zone);
     const zoneStage = named === null ? null : context.definition.stages.find(one => one.id === named || one.title.toLowerCase() === named.toLowerCase());
@@ -170,7 +123,6 @@ export function validateTriggerConfig(raw, context) {
         case "schedule": {
             const said_ = said(input.schedule) ?? refuse("schedule", "required");
             const schedule = scheduleFromWords(said_) ?? refuse("schedule", "say it like “every 2 hours”, “daily 09:00 Europe/London”, “weekdays 09:00” or “monday 09:00”");
-            // A script on a schedule (v90): each item it prints becomes a card.
             const script = said(input.script);
             if (script !== null) {
                 if (context.store.flowScript(context.flow.repo, script) === null)
@@ -216,8 +168,6 @@ export function validateTriggerConfig(raw, context) {
         }
         case "webhook":
             {
-                // v126: Sentry and Vercel deliveries are read by their own readers, scoped by project (and Vercel's by team); the
-                // others pick their fields from the JSON by dot-paths. A setting that the sender doesn't read is refused, not kept.
                 const sender = input.sender ?? "none";
                 const provider = sender === "sentry" || sender === "vercel";
                 const project = said(input.project), team = said(input.team), idField = said(input.idField), urlField = said(input.urlField);
@@ -256,7 +206,6 @@ export function validateTriggerConfig(raw, context) {
         }
     }
 }
-/** The computer's time zone, as a schedule names one. */
 function localTimeZone() {
     try {
         return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
@@ -265,11 +214,9 @@ function localTimeZone() {
         return "UTC";
     }
 }
-/** Addresses and domains from "priya@example.com, @shop.com, example.org". */
 function sendersOf(text) {
     return [...new Set(text.split(/[\s,;]+/).map(one => one.trim().toLowerCase().replace(/^@/, "")).filter(one => /^([a-z0-9._%+-]+@)?[a-z0-9-]+(\.[a-z0-9-]+)*\.[a-z]{2,}$/.test(one)))].slice(0, 20);
 }
-/** Whether an email is one this trigger takes: from a named sender (or domain), with the words in its subject. */
 export function mailMatches(config, mail) {
     const from = mail.from.toLowerCase();
     const senders = config.sender === null ? [] : sendersOf(config.sender);
@@ -277,7 +224,6 @@ export function mailMatches(config, mail) {
         return false;
     return config.subject === null || mail.subject.toLowerCase().includes(config.subject.toLowerCase());
 }
-/** The trigger in the words the canvas and its cards use. */
 export function describeTrigger(config, store) {
     const from = (value) => value === "team" ? ", from people with write access" : ", from anyone";
     const way = (delivery) => delivery === "poll" ? " (checked every 2 minutes)" : " (sent to its webhook address)";
@@ -286,7 +232,6 @@ export function describeTrigger(config, store) {
         case "schedule": {
             const schedule = parseSchedule(config.schedule);
             const when = schedule === null ? config.schedule : describeSchedule(schedule);
-            // Its limits and terms are said once, in "What each run files" (describeStandingOrder).
             if (config.order !== undefined)
                 return `${when.charAt(0).toUpperCase()}${when.slice(1)}: files the task “${config.title}”`;
             return config.script !== undefined ? `${when.charAt(0).toUpperCase()}${when.slice(1)}: runs the ${config.script} script, and each item it prints becomes a card` : `${when.charAt(0).toUpperCase()}${when.slice(1)}: “${config.title}”`;
@@ -310,7 +255,6 @@ export function describeTrigger(config, store) {
         case "email": return `Email arriving in ${config.folder === "INBOX" ? "the inbox" : config.folder}${config.sender === null ? "" : ` from ${config.sender}`}${config.subject === null ? "" : ` with “${config.subject}” in the subject`} (checked every 2 minutes)`;
     }
 }
-/** The trigger in two short lines for the canvas: what it is, and the one detail that tells it apart. */
 export function triggerHeadline(config, store) {
     switch (config.kind) {
         case "button": return { name: config.label, detail: `Asks ${config.questions.length} question${config.questions.length === 1 ? "" : "s"}` };
@@ -345,40 +289,31 @@ export function triggerConfigOf(trigger) {
     const read = readTriggerConfig(raw);
     return read.ok ? read.value : null;
 }
-/** What a saved trigger leaves out, it had as these (every release has saved them whole; a hand-made row may not). */
 const SAVED_DEFAULTS = {
     button: { questions: ["What needs doing?", "Details"] }, schedule: { description: null }, github: { label: null, branch: null, from: "team", delivery: "poll" },
     linear: { team: null, state: null, label: null, delivery: "poll" }, webhook: { title: "Webhook", titleField: null, bodyField: null, sender: "none", project: null, team: null, idField: null, urlField: null }, email: { folder: "INBOX", sender: null, subject: null },
 };
-/** A saved trigger's config (`configJson`, which carries no version) read by its one schema, what it leaves out filled. */
 export function readTriggerConfig(raw) {
     const kind = isRecord(raw) ? raw["kind"] : undefined;
     const body = isRecord(raw) ? { zone: null, ...SAVED_DEFAULTS[kind], ...raw } : raw;
     return parseContract(triggerConfigSchema, body);
 }
-/** v126: what a webhook trigger takes, in words: what its sender sends it, or anything posted when it's unsigned. */
 function webhookWords(config) {
     const sender = senderOf(config);
     const scope = config.project == null ? "" : ` from ${config.project}`;
     return sender === "sentry" ? `Sentry issue alerts and new issues${scope}` : sender === "vercel" ? `Failed Vercel deployments${scope}`
         : sender === "none" ? "Anything posted to its webhook address" : `Requests signed ${sender === "standard" ? "the Standard Webhooks way" : "GitHub-style"} to its webhook address`;
 }
-/** v126: who signs a webhook trigger's deliveries; one saved before senders were chosen is unsigned. */
 export const senderOf = (config) => config.sender ?? "none";
-/** Whether this trigger takes deliveries at a secret address rather than being checked. */
-/** Whether a raw trigger the caller is about to add would take deliveries (an address): read leniently, before validation. */
 export function rawTakesDeliveries(raw) {
     if (raw === null || typeof raw !== "object")
         return false;
     const one = raw;
     return one["kind"] === "webhook" || ((one["kind"] === "github" || one["kind"] === "linear") && one["delivery"] === "webhook");
 }
-/** Whether a trigger brings in items from anyone (chat-management.md §0a.3): GitHub issues or pull requests from anyone,
- * or mail from any sender. A widening: it takes a person's password, on every road that adds one. */
 export function admitsAnyone(config) {
     return (config.kind === "github" && config.from === "anyone") || (config.kind === "email" && config.sender === null);
 }
-/** The same, read leniently from a raw trigger before validation (so the form can ask for the password first). */
 export function rawAdmitsAnyone(raw) {
     if (raw === null || typeof raw !== "object")
         return false;
@@ -388,26 +323,16 @@ export function rawAdmitsAnyone(raw) {
 export function takesDeliveries(config) {
     return config.kind === "webhook" || ((config.kind === "github" || config.kind === "linear") && config.delivery === "webhook");
 }
-// ------------------------------------------------------ secrets on disk
 const hookHash = (token) => createHash("sha256").update(token).digest("hex");
-/**
- * A webhook's signing secret: kept by Toolroll (tool-secret-store.ts) as `flow-hook.<trigger>`, in a file of that name
- * before. v126: each secret has its own address, named by an id made for the one change that writes it, so no two
- * changes ever write the same place; the trigger points at it (flow_trigger.hook_credential) only once it is whole.
- * "legacy" is the address every secret saved before v126 has, so those keep authenticating with nothing moved; ""
- * (or an id that isn't one) has no address at all.
- */
 const hookSecret = (trigger, credential) => credential === "legacy"
     ? { name: `flow-hook.${trigger}`, file: ["flow-hooks", `${trigger}.json`] }
     : /^[0-9a-f]{32}$/.test(credential) ? { name: `flow-hook.${trigger}.${credential}`, file: ["flow-hooks", `${trigger}.${credential}.json`] } : null;
-/** A webhook's signing secret (made here, or pasted from its sender). In the keychain (or an owner-only file where there's none), never a column. */
 export function saveHookSecret(dir, trigger, secret, credential = "legacy") {
     const held = hookSecret(trigger, credential);
     if (held === null)
         throw new Error("not a credential id");
     writeHeldSecret(dir, held.name, held.file, `${JSON.stringify({ secret })}\n`);
 }
-/** Exactly this credential's secret, or null: never another's. */
 export function readHookSecret(dir, trigger, credential = "legacy") {
     const held = hookSecret(trigger, credential);
     if (held === null)
@@ -420,7 +345,6 @@ export function readHookSecret(dir, trigger, credential = "legacy") {
         return null;
     }
 }
-/** Cleanup only: a secret no trigger points at is never read, whether or not its file is gone. */
 function dropHookSecret(dir, trigger, credential) {
     const held = hookSecret(trigger, credential);
     if (held === null)
@@ -428,10 +352,9 @@ function dropHookSecret(dir, trigger, credential) {
     try {
         writeHeldSecret(dir, held.name, held.file, null);
     }
-    catch { /* never read: nothing points at it */ }
+    catch { }
 }
 const LINEAR = { name: "linear-key", file: ["linear-key"] };
-/** The Linear API key the worker checks Linear with: the environment, or kept by Toolroll (the keychain, or an owner-only file beside the database). */
 export function readLinearKey(dir) {
     const env = envValue(process.env, "LINEAR_KEY")?.trim();
     if (env)
@@ -460,7 +383,6 @@ export function saveLinearKey(dir, key) {
 }
 export function removeLinearKey(dir) { writeHeldSecret(dir, LINEAR.name, LINEAR.file, null); }
 const HOOKS_FILE = "hooks-url";
-/** The public address webhooks reach this console at (a reverse proxy such as Caddy, exposing /hooks/ only). */
 export function readHooksBase(dir) {
     if (dir === null)
         return null;
@@ -491,12 +413,6 @@ export function saveHooksBase(dir, value) {
     return { ok: true, base: readHooksBase(dir) };
 }
 export const HOOK_PATH = "/hooks/flow/";
-/** Add a trigger to a flow. A webhook trigger's address (and GitHub's signing secret) is returned once and never stored readable. */
-/**
- * `ingress: "proved"`: the caller proved a password typed now (a credential act, docs/plans/passwordless.md) — only then
- * may a trigger that takes deliveries be made with an address. Without it a webhook is made with none (its panel's
- * set-up, which asks for the password, makes one), and GitHub/Linear webhook delivery is refused.
- */
 export function addFlowTriggerTo(store, flow, raw, actor, now, dir, options = {}) {
     const definition = flowDefinitionOf(flow);
     if (definition === null || flow.state !== "active")
@@ -512,19 +428,13 @@ export function addFlowTriggerTo(store, flow, raw, actor, now, dir, options = {}
         return { ok: false, message: "Webhook addresses are set up on the console." };
     if (takesDeliveries(config) && config.kind !== "webhook" && options.ingress !== "proved")
         return { ok: false, message: "Webhook delivery is set up on the flow's trigger panel, with your password." };
-    // Items from anyone come in only on a person's proof (chat-management.md §0a.3): never from a card, an import or a template alone.
     if (admitsAnyone(config) && options.ingress !== "proved" && options.widening !== "proved")
         return { ok: false, message: "A trigger that brings in items from anyone takes your password. Add it on the flow's Triggers panel." };
-    // v126: a webhook made where no one is shown its address (the gallery, an import) is made with none: its first
-    // set-up or New address makes one and shows it. A webhook made on its panel is shown its address now.
     const token = takesDeliveries(config) && options.ingress === "proved" && (options.shown !== false || config.kind !== "webhook") ? randomBytes(24).toString("base64url") : null;
     const schedule = config.kind === "schedule" || config.kind === "plane-review" ? parseSchedule(config.schedule) : null;
     const id = store.addFlowTrigger({
-        // The table's kinds were fixed before plane reviews: one is kept as the daily schedule it is.
         flow: flow.id, kind: config.kind === "plane-review" ? "schedule" : config.kind, configJson: JSON.stringify(config), hookHash: token === null ? null : hookHash(token),
-        // Only what happens from now on: never the backlog of issues, runs or finished cards.
         cursor: config.kind === "flow" ? String(store.latestFlowEvent()) : config.kind === "github" || config.kind === "linear" ? now.toISOString() : null,
-        // Email: the first check notes where the mailbox stands (no cursor yet), so only mail after this becomes cards.
         nextAt: schedule !== null ? firstFireAt(schedule, now) : polled(config) ? now.toISOString() : null,
         by: actor,
     }, now);
@@ -533,22 +443,17 @@ export function addFlowTriggerTo(store, flow, raw, actor, now, dir, options = {}
         secret = randomBytes(24).toString("hex");
         saveHookSecret(dir, id, secret);
     }
-    // v126: a webhook starts with no secret at all (not the legacy address): it is set up on its panel, never here.
     if (config.kind === "webhook")
         store.swapFlowHookCredential(id, { credential: "legacy", configJson: JSON.stringify(config), hookHash: token === null ? null : hookHash(token) }, { credential: "" }, null, now);
     const reveal = token === null ? null : { path: `${HOOK_PATH}${token}`, address: dir === null || readHooksBase(dir) === null ? null : `${readHooksBase(dir)}${HOOK_PATH}${token}`, secret };
     return { ok: true, id, said: token === null ? "Trigger added." : "Trigger added. Copy its address now; it isn't shown again.", reveal };
 }
-/** A new secret address for a webhook trigger (the old one stops working at once). */
 export function renewFlowHook(store, trigger, now, dir) {
     const config = triggerConfigOf(trigger);
     if (config === null || !takesDeliveries(config) || trigger.state === "removed")
         return { ok: false, message: "That trigger has no webhook address." };
     const token = randomBytes(24).toString("base64url");
     let secret = null;
-    // GitHub's own trigger gets a new secret with its new address (as it always has); a webhook keeps its secret. Either
-    // way the address moves in one conditional write with the secret it is proven by, from the pair read here: a renewal
-    // that fails (or loses to another) leaves the working address and its secret exactly as they were.
     if (config.kind === "github") {
         secret = randomBytes(24).toString("hex");
         const saved = nextHookCredential(store, trigger, secret, null, now, dir, hookHash(token));
@@ -561,10 +466,6 @@ export function renewFlowHook(store, trigger, now, dir) {
     const base = readHooksBase(dir);
     return { ok: true, id: trigger.id, said: "New address made; the old one no longer works. Copy it now; it isn't shown again.", reveal: { path: `${HOOK_PATH}${token}`, address: base === null ? null : `${base}${HOOK_PATH}${token}`, secret } };
 }
-/**
- * Pause a trigger, or turn it on again. A schedule that never had a time (a routine moved to a flow while it waited
- * for approval, v115) starts counting from now, as a new schedule does; one that was due while it was off fires once.
- */
 export function setFlowTriggerOn(store, trigger, on, now, by) {
     const config = on && trigger.nextAt === null ? triggerConfigOf(trigger) : null;
     const schedule = config !== null && (config.kind === "schedule" || config.kind === "plane-review") ? parseSchedule(config.schedule) : null;
@@ -575,20 +476,17 @@ export function removeFlowTrigger(store, trigger, now, dir, by) {
     if (dir !== null)
         dropHookSecret(dir, trigger.id, trigger.hookCredential);
 }
-/** Checked by the worker's pass (rather than pushed, fired on a schedule or followed). */
 function polled(config) {
     return config.kind === "email" || ((config.kind === "github" || config.kind === "linear") && config.delivery === "poll");
 }
 function startZone(config, definition) {
     return config.zone !== null && definition.stages.some(one => one.id === config.zone) ? config.zone : definition.start;
 }
-/** The active flow that already made a card for this failing commit in a project, if any. */
 function checksCardOf(store, repo, key) {
     const row = store.handle.prepare(`SELECT f.name FROM flow_trigger_event e JOIN flow_trigger t ON t.id = e.trigger JOIN flow f ON f.id = t.flow
     WHERE f.repo = ? AND f.state = 'active' AND e.key = ? AND e.card IS NOT NULL LIMIT 1`).get(repo, key);
     return row === undefined ? null : `“${String(row["name"])}”`;
 }
-/** One outside thing into one card, at most once per trigger (a failing run, once per project). Keys and control characters never reach a card. */
 function makeCard(store, trigger, config, item, by, now, byKind = "automation") {
     const flow = store.getFlow(trigger.flow);
     const definition = flow === null ? null : flowDefinitionOf(flow);
@@ -602,11 +500,9 @@ function makeCard(store, trigger, config, item, by, now, byKind = "automation")
         store.recordFlowTriggerEvent(trigger.id, item.key, null, note, now);
         return { made: "skipped", note: `${item.source.label}: ${note}`, card: null };
     }
-    // Claimed inside the write lock: a worker and a console (or an old and a new worker) checking at once make one card.
     return store.transact(() => {
         if (store.flowTriggerSaw(trigger.id, item.key))
             return { made: "seen", note: null, card: null };
-        // One failing run is one fix: a second trigger watching the same checks in this project leaves it to the first.
         const filed = item.key.startsWith("checks:") ? checksCardOf(store, flow.repo, item.key) : null;
         if (filed !== null) {
             const note = `already a card in ${filed}`;
@@ -618,11 +514,6 @@ function makeCard(store, trigger, config, item, by, now, byKind = "automation")
         return { made: "added", note: null, card };
     });
 }
-/**
- * v115: a schedule with a standing order (what a routine was) files its task and the card that follows it, together or
- * not at all; a slot it skips says why on the trigger. The card starts in the schedule's build step, which follows the
- * task it was filed with.
- */
 function fileOrderCard(store, trigger, config, order, item, slot, now) {
     const flow = store.getFlow(trigger.flow);
     const definition = flow === null ? null : flowDefinitionOf(flow);
@@ -647,7 +538,6 @@ function fileOrderCard(store, trigger, config, order, item, slot, now) {
             }
             const card = store.addFlowCard({ flow: flow.id, title: text.title, description: text.description, stage: zone, by: "Schedule", byKind: "automation", source: item.source }, now);
             store.updateFlowCard(card, { task: fired.taskId, primaryTask: fired.taskId, waiting: "Filed as a task" }, now);
-            // The firing keeps its task: one-at-a-time and the weekly limit count it however the card moves later.
             store.recordFlowTriggerEvent(trigger.id, item.key, card, null, now, fired.taskId);
             return { made: "added", note: fired.note ?? (fired.approved ? `Filed ${fired.taskId}, approved.` : `Filed ${fired.taskId}; it waits for approval.`), card };
         });
@@ -669,15 +559,12 @@ function outcomeWords(results, more) {
         parts.push("More on the next check.");
     return parts.join(" ");
 }
-/** One outside thing into one card through a trigger (a chat channel's message, v89): at most once per key. */
 export function addTriggerCard(store, trigger, item, by, now) {
     const config = triggerConfigOf(trigger);
     if (config === null || trigger.state !== "active")
         return { made: "skipped", note: "the trigger isn't active", card: null };
-    // A channel's message is the app's word for who sent it, not a signed-in account: automation (v126).
     return makeCard(store, trigger, config, item, by, now, "automation");
 }
-/** Press a button trigger: the first answer is the card's title, the rest its details. */
 export function pressFlowButton(store, trigger, answers, actor, now) {
     const config = triggerConfigOf(trigger);
     if (config?.kind !== "button" || trigger.state !== "active")
@@ -693,7 +580,6 @@ export function pressFlowButton(store, trigger, answers, actor, now) {
     store.updateFlowTrigger(trigger.id, { lastAt: now.toISOString(), lastOutcome: `Pressed by ${actor}.` }, now);
     return { ok: true, said: "Card added.", card: result.card };
 }
-/** Every trigger in one project that is due: schedules and other flows here, GitHub, Linear and email by asking them. */
 export async function runFlowTriggers(store, repo, now, io) {
     const pass = { added: 0, checked: 0, problems: [] };
     const triggers = store.activeFlowTriggers(repo);
@@ -704,7 +590,6 @@ export async function runFlowTriggers(store, repo, now, io) {
         if (config === null)
             continue;
         try {
-            // v126: deliveries held over the hourly limit become their cards as the hour makes room.
             if (takesDeliveries(config))
                 pass.added += drainHeldDeliveries(store, trigger, now);
             if (config.kind === "schedule" && config.script !== undefined && trigger.nextAt !== null && Date.parse(trigger.nextAt) <= now.getTime()) {
@@ -733,10 +618,8 @@ export async function runFlowTriggers(store, repo, now, io) {
     }
     return pass;
 }
-/** "Check now" on the canvas: one trigger, right away, in words. */
 export async function checkFlowTriggerNow(store, trigger, now, io) {
     const config = triggerConfigOf(trigger);
-    // A schedule's script runs now, once; its schedule stays as it is.
     if (config?.kind === "schedule" && config.script !== undefined) {
         const fired = await fireScript(store, trigger, config, now, io, false);
         return { ok: fired.ok, said: fired.said };
@@ -756,12 +639,10 @@ function fireSchedule(store, trigger, config, now) {
         return 0;
     const slot = trigger.nextAt;
     const next = nextFireAt(schedule, slot, now);
-    // One card at a time: while the last one still waits where it started, the slot is skipped, not piled up.
     const last = config.order === undefined ? store.lastFlowTriggerCard(trigger.id) : null;
     const card = last === null ? null : store.getFlowCard(last);
     const flow = store.getFlow(trigger.flow);
     const definition = flow === null ? null : flowDefinitionOf(flow);
-    // A standing order says itself when it waits (its last task unfinished); other schedules wait on their last card.
     if (card !== null && definition !== null && card.state === "active" && card.stage === startZone(config, definition) && card.entry === 1) {
         store.recordFlowTriggerEvent(trigger.id, `slot:${slot}`, null, "the last one hadn't been picked up", now);
         store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: "Skipped: the last card hasn't been picked up yet." }, now);
@@ -775,20 +656,12 @@ function fireSchedule(store, trigger, config, now) {
     store.updateFlowTrigger(trigger.id, { nextAt: next, lastAt: now.toISOString(), lastOutcome: made.made === "added" ? made.note ?? "Added a card." : made.note ?? "Nothing new." }, now);
     return made.made === "added" ? 1 : 0;
 }
-/** The problem a plane review's event key names, and the day: `plane:<problem>:<YYYY-MM-DD>`. */
 const planeKey = (problem, day) => `plane:${problem}:${day}`;
-/** The card a plane review last made or joined for one problem, if any. */
 function planeCardOf(store, trigger, problem) {
     const prefix = `plane:${problem}:`;
     const row = store.handle.prepare("SELECT card FROM flow_trigger_event WHERE trigger = ? AND substr(key, 1, ?) = ? AND card IS NOT NULL ORDER BY rowid DESC LIMIT 1").get(trigger, prefix.length, prefix);
     return row === undefined ? null : Number(row["card"]);
 }
-/**
- * A plane review: the last 24 hours, one card per problem worth fixing. Each problem is noted once a day; a problem
- * whose card is still open joins it (a note with the day's counts and evidence) instead of making another, and one
- * whose card is finished starts a new card, since it came back. A clean day adds nothing and tells nobody.
- * `scheduled` moves the trigger to its next morning; "Run now" leaves its times alone.
- */
 export async function firePlaneReview(store, trigger, config, now, scheduled) {
     const schedule = parseSchedule(config.schedule);
     const next = scheduled && schedule !== null && trigger.nextAt !== null ? nextFireAt(schedule, trigger.nextAt, now) : trigger.nextAt;
@@ -799,13 +672,10 @@ export async function firePlaneReview(store, trigger, config, now, scheduled) {
     };
     if (flow === null || flow.state !== "active")
         return done("The flow isn't active.");
-    // Loaded when a review first runs: the reader reaches the integrations and task status, which reach back to these triggers.
     const { longPersonWaits, longWaitWords, problemCard, problemText, reviewPlane } = await import("./plane-review.js");
-    // Only the projects the flow's owner may see: a flow's cards are read by everyone on its project.
     const owner = store.accountOf(flow.owner);
     const canSee = (repo) => owner === null || (repo !== null && store.accountCanAccess(flow.owner, repo)) || (repo === null && owner.projects === null);
     const problems = reviewPlane(store, now, canSee);
-    // Long waits on a person are said here once, linked to Needs you (planeStatusLink), and file nothing.
     const waited = longWaitWords(longPersonWaits(store, now, canSee));
     const said = (words) => waited === null ? words : `${words} ${waited}`;
     const timeZone = schedule !== null && schedule.kind !== "every" ? schedule.timezone ?? "UTC" : "UTC";
@@ -840,13 +710,10 @@ export async function firePlaneReview(store, trigger, config, now, scheduled) {
         skipped.length > 0 ? `Left out ${plural(skipped.length, "problem")}: ${skipped[0]}.` : null].filter(one => one !== null);
     return done(said(parts.length === 0 ? "Nothing new since this morning's review." : parts.join(" ")), added, joined);
 }
-/** Where a person sees everything that waits on them. */
 export const NEEDS_YOU_HREF = "/tasks?view=needs-you";
-/** A plane review whose summary mentions long waits on a person links to Needs you. */
 export function planeStatusLink(config, status) {
     return config?.kind === "plane-review" && status !== null && /waited over \d+ days for you\.$/.test(status) ? { label: "Needs you", href: NEEDS_YOU_HREF } : null;
 }
-/** v96: a schedule (a subagent's routine) makes its card now, once per press, and keeps its own times. */
 export function runScheduleNow(store, trigger, actor, now) {
     const config = triggerConfigOf(trigger);
     if (config?.kind !== "schedule" || config.script !== undefined)
@@ -860,7 +727,6 @@ export function runScheduleNow(store, trigger, actor, now) {
     store.updateFlowTrigger(trigger.id, { lastAt: now.toISOString(), lastOutcome: `${made.note ?? "Added a card."} (run now)` }, now);
     return { ok: true, card: made.card };
 }
-/** A schedule's script (v90): it runs in a clean folder inside the agents' fence; each item it prints is a card, once. */
 async function fireScript(store, trigger, config, now, io, scheduled) {
     const schedule = parseSchedule(config.schedule);
     const next = scheduled && schedule !== null && trigger.nextAt !== null ? nextFireAt(schedule, trigger.nextAt, now) : trigger.nextAt;
@@ -878,15 +744,12 @@ async function fireScript(store, trigger, config, now, io, scheduled) {
     const missing = (config.secrets ?? []).filter(name => saved[name] === undefined);
     if (missing.length > 0)
         return done(false, `${script.name} needs the secret${missing.length === 1 ? "" : "s"} ${missing.join(", ")}. Save ${missing.length === 1 ? "it" : "them"} on the flow first.`);
-    // Loaded when a script first runs: the runner reaches the builder's modules, which reach back to these triggers.
     const { cardsFromOutput, cleanFolder, flowLaunch, runCode } = await import("./flow-code.js");
     const scratch = io.scratch ?? join(io.dir ?? tmpdir(), "flow-scratch");
     const folder = cleanFolder(scratch, `flow-trigger-${trigger.id}`);
-    // Its cards run on their own only if it ran the very code a grant signed: pinned just before and just after the run.
     const pin = scheduled && grantSignsScriptOf(store, flow.id, trigger.id, now) ? () => scriptProvenanceOf(store, flow.repo, script.name) : null;
     const before = pin === null ? null : await pin();
     let ran;
-    // A full boundary around its clean folder, though it has no checkout (flow-code.ts flowLaunch).
     const launch = await flowLaunch(store, { repo: flow.repo, folder, scratch, copy: false, policy: store.flowFencePolicy(flow.id), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }), ...(io.home === undefined ? {} : { home: io.home }) });
     try {
         if (launch !== null && "problem" in launch)
@@ -930,26 +793,20 @@ async function checkTrigger(store, trigger, config, now, io) {
         store.updateFlowTrigger(trigger.id, { failures, lastAt: now.toISOString(), lastOutcome: fetched.problem, nextAt: new Date(now.getTime() + BACKOFF_MS[Math.min(failures, BACKOFF_MS.length) - 1]).toISOString() }, now);
         return { ok: false, said: fetched.problem, added: 0 };
     }
-    // Tidy's CI evidence (task-tidy.md): the watched branch's completed runs, green and red, beside the failures it carded.
     if (config.kind === "github" && config.watch === "checks")
         await observeBranchRuns(store, trigger, config, io.gh, now);
     const by = config.kind === "github" ? "GitHub" : config.kind === "linear" ? "Linear" : "Email";
-    // Known items are left out before the batch is taken (v126): a page of things already received can't keep the unseen
-    // ones behind it waiting.
     const fresh = fetched.items.filter(item => !store.flowTriggerSaw(trigger.id, item.key));
     const due = fresh.slice(0, CARDS_PER_CHECK);
     const results = due.map(item => "skip" in item
         ? (store.recordFlowTriggerEvent(trigger.id, item.key, null, item.skip, now) ? { made: "skipped", note: `${item.label}: ${item.skip}`, card: null } : { made: "seen", note: null, card: null })
         : makeCard(store, trigger, config, item, by, now));
-    // A mailbox says itself whether more is waiting; its cursor is already just past what it read.
     const more = fetched.more ?? fresh.length > CARDS_PER_CHECK;
-    // The cursor moves past what was handled, never past what is still waiting.
     const cursor = fetched.more !== undefined ? fetched.cursor ?? trigger.cursor : more ? due.at(-1)?.at ?? trigger.cursor : fetched.cursor ?? trigger.cursor;
     const said = results.length === 0 && fetched.said !== undefined ? fetched.said : outcomeWords(results, more);
     store.updateFlowTrigger(trigger.id, { failures: 0, cursor, lastAt: now.toISOString(), lastOutcome: said, nextAt: new Date(now.getTime() + POLL_EVERY_MS).toISOString() }, now);
     return { ok: true, said, added: results.filter(one => one.made === "added").length };
 }
-/** New mail in the folder since the last check, each message a card (or why it was left out). */
 async function fetchMail(store, config, trigger, io, now) {
     const signed = await mailboxAccess(io.dir, io.fetch);
     if (!signed.ok)
@@ -962,14 +819,12 @@ async function fetchMail(store, config, trigger, io, now) {
     const items = read.mails.map(readInboundMail).filter(mail => mailMatches(config, mail)).map(mail => {
         const key = `mail:${read.at.validity}:${mail.uid}`, at = mailCursorText({ validity: read.at.validity, uid: mail.uid });
         const label = `Email from ${mail.from || "an unknown sender"}`.slice(0, 120);
-        // Machines and this account itself never start cards: a flow that answers mail mustn't answer them.
         if (mail.automatic)
             return { key, skip: "an automatic reply", label, at };
         if (mail.from === own)
             return { key, skip: "sent from this account", label, at };
         if (mail.from === "")
             return { key, skip: "it had no sender", label, at };
-        // A reply to a card's email (v91) joins that card instead of starting another.
         const reply = takeReply(store, mail, own, now);
         if (reply !== null)
             return { key, skip: `a reply to “${reply.card.title}”`, label, at };
@@ -981,7 +836,6 @@ async function fetchMail(store, config, trigger, io, now) {
         : read.renumbered ? "The mail server renumbered this folder; watching it from now." : undefined;
     return { ok: true, items, cursor: mailCursorText(read.at), more: read.more, ...(said === undefined ? {} : { said }) };
 }
-/** A GitHub issue or pull request as a card, or why it is left out; null when it doesn't match. */
 export function githubItem(config, raw, what) {
     const item = readGithubIssue(raw);
     const number = Number(item.number);
@@ -1004,7 +858,6 @@ export function githubItem(config, raw, what) {
         description: `From ${what === "issue" ? "GitHub issue" : "pull request"} #${number} by @${login}${branches}:\n\n${item.body ?? ""}`.trim().slice(0, 4000),
         source: { kind: "github", label, url: item.html_url || null } };
 }
-/** A failed workflow run as a card: one card per failing commit on the watched branch. */
 export function githubRunItem(config, raw) {
     const run = readGithubRun(raw);
     if (run.conclusion !== "failure" || (config.branch !== null && (run.head_branch ?? "") !== config.branch))
@@ -1020,7 +873,6 @@ export function githubRunItem(config, raw) {
 }
 async function fetchGitHub(config, trigger, gh) {
     const since = trigger.cursor ?? trigger.createdAt;
-    // A label trigger follows the moment the label is added (issue events), so an old labeled issue that merely gets a comment makes no card.
     const labelEvents = config.watch === "issues" && config.label !== null;
     const path = labelEvents ? `repos/${config.repo}/issues/events?per_page=50`
         : config.watch === "issues" ? `repos/${config.repo}/issues?state=open&sort=created&direction=desc&per_page=30`
@@ -1057,7 +909,6 @@ async function fetchGitHub(config, trigger, gh) {
         const items = labeled.map(one => { const item = githubItem(config, one.issue, "issue"); return item === null ? null : { ...item, at: one.created_at || null }; }).filter((one) => one !== null);
         return { ok: true, items: unique(items), cursor: labeled.map(one => one.created_at ?? "").at(-1) ?? trigger.cursor };
     }
-    // New issues and pull requests: opened after the trigger was added, oldest first; the key keeps each to one card.
     const what = config.watch === "pulls" ? "pull" : "issue";
     const items = readGithubIssueList(body).filter(one => Date.parse(one.created_at ?? "") > created).reverse().map(one => githubItem(config, one, what)).filter((one) => one !== null);
     return { ok: true, items, cursor: trigger.cursor };
@@ -1065,7 +916,6 @@ async function fetchGitHub(config, trigger, gh) {
 const unique = (items) => items.filter((item, index) => items.findIndex(one => one.key === item.key) === index);
 export const LINEAR_URL = "https://api.linear.app/graphql";
 export const LINEAR_QUERY = "query FlowTrigger($filter: IssueFilter) { issues(filter: $filter, first: 50, orderBy: updatedAt) { nodes { identifier title description url updatedAt state { name } team { key } labels { nodes { name } } } } }";
-/** A Linear issue as a card; null when it doesn't match the trigger. */
 export function linearItem(config, raw) {
     const issue = readLinearIssue(raw);
     const identifier = issue.identifier ?? "";
@@ -1118,14 +968,11 @@ async function fetchLinear(config, trigger, io) {
     const items = issues.map(one => linearItem(config, one)).filter((one) => one !== null);
     return { ok: true, items, cursor: issues.map(one => one.updatedAt ?? "").filter(one => one !== "").at(-1) ?? trigger.cursor };
 }
-/** A header that only describes the delivery (not a security header): its first value. */
 const header = (delivery, name) => delivery.headers[name]?.[0] ?? "";
 function sameHex(expected, given) {
     const a = Buffer.from(expected, "utf8"), b = Buffer.from(given, "utf8");
     return a.length === b.length && timingSafeEqual(a, b);
 }
-/** How a webhook trigger's deliveries are proven, before anything in them is read: its sender's signature over the raw
- * bytes with the current generation's secret. Null when proven (or unsigned); otherwise the refusal, which writes nothing. */
 function proveHook(trigger, config, delivery, dir, now) {
     if (config.kind === "github") {
         const secret = readHookSecret(dir, trigger.id, trigger.hookCredential);
@@ -1152,10 +999,7 @@ function proveHook(trigger, config, delivery, dir, now) {
     const proof = proveDelivery(sender, secret, delivery.headers, delivery.body, now);
     return proof.ok ? { signedId: proof.signedId } : { status: 401, said: proof.said };
 }
-/** A webhook delivery at a trigger's secret address: prove it, read it, make at most the cards it names. Nothing runs here. */
 export function receiveFlowHook(store, token, delivery, dir, now) {
-    // v126 floods (webhook-limits.ts): what doesn't prove itself is counted per address, and past the minute's limit is
-    // answered 429 and does nothing. A delivery that proves itself is never refused by this count.
     const unproven = (address, answer) => {
         const count = countUnproven(store, address, now);
         return count.over ? { status: 429, said: "Too many. Try again later.", retryAfter: count.retryAfterSeconds } : answer;
@@ -1169,7 +1013,6 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
     if (!adapterPolicy({ caller: "service", capability: "none" }, undefined, source => source === "flow" && store.getFlow(trigger.flow) !== null).ok)
         return { status: 403, said: "No access to this flow." };
     const address = trigger.hookHash ?? UNKNOWN_ADDRESS;
-    // An unsigned webhook has nothing to prove: every delivery to it counts (and it is lossy under a flood, by design).
     const unsigned = config.kind === "webhook" && senderOf(config) === "none";
     if (unsigned) {
         const counted = unproven(address, { status: 0, said: "" });
@@ -1178,14 +1021,10 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
     }
     if (delivery.body.length > HOOK_BYTES)
         return unsigned ? { status: 413, said: "Too large." } : unproven(address, { status: 413, said: "Too large." });
-    // Proven over the raw bytes before anything in them is read; a refusal writes nothing, not even the last outcome.
     const proven = proveHook(trigger, config, delivery, dir, now);
     if ("status" in proven)
         return unsigned ? proven : unproven(address, proven);
     const note = (said) => { store.updateFlowTrigger(trigger.id, { lastAt: now.toISOString(), lastOutcome: said }, now); };
-    // Every write a delivery makes is bound to the trigger as it was proven against (v126): its secret, settings, address
-    // and state, read again in the same transaction. A change that landed meanwhile (a new secret, another sender, a new
-    // address, a pause) means this delivery writes nothing at all.
     const written = (write) => store.transact(() => {
         const current = store.getFlowTrigger(trigger.id);
         if (current === null || current.state !== "active" || current.hookCredential !== trigger.hookCredential || current.configJson !== trigger.configJson || current.hookHash !== trigger.hookHash) {
@@ -1208,14 +1047,11 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
             return written(() => { note("GitHub connected."); return { status: 200, said: "Connected." }; });
         if (repository.toLowerCase() !== config.repo.toLowerCase())
             return { status: 202, said: "Not this repository." };
-        // A label trigger takes the moment its label is added (or an issue opened with it); a plain one takes new issues.
         const labeledNow = action === "labeled" && config.label !== null && (body.label?.name ?? "").toLowerCase() === config.label.toLowerCase();
         const found = config.watch === "issues" && event === "issues" && (action === "opened" || labeledNow) ? githubItem(config, body.issue, "issue")
             : config.watch === "pulls" && event === "pull_request" && ["opened", "ready_for_review", "labeled", "reopened"].includes(action) ? githubItem(config, body.pull_request, "pull")
                 : config.watch === "checks" && event === "workflow_run" && action === "completed" ? githubRunItem(config, body.workflow_run) : null;
         items = found === null ? [] : [found];
-        // A signed workflow run on the watched branch is tidy's CI evidence too (task-tidy.md), green or red: recorded only
-        // inside `written`, which re-proves the trigger is still active with the same config, credential and address.
         if (config.watch === "checks" && config.branch !== null && event === "workflow_run" && action === "completed") {
             const branch = config.branch;
             const recorded = written(() => { recordBranchCheckRun(store, { repo: config.repo, branch }, readGithubRun(body.workflow_run), now); return { status: 200, said: "Recorded." }; });
@@ -1225,31 +1061,20 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
     }
     else if (config.kind === "linear") {
         const body = readLinearEvent(payload), sent = Number(body.webhookTimestamp);
-        // Signed but stale: as unproven as no signature at all, so it counts toward the address's minute.
         if (!Number.isFinite(sent) || Math.abs(now.getTime() - sent) > 5 * 60_000)
             return unproven(address, { status: 401, said: "Too old." });
         if (body.type !== "Issue" || !["create", "update"].includes(body.action ?? ""))
             return { status: 202, said: "Ignored." };
-        // A state trigger fires when the issue arrives in that state, not on every later edit there.
         const moved = body.action === "create" || body.updatedFrom?.stateId !== undefined || config.state === null;
         const found = moved ? linearItem(config, body.data) : null;
         items = found === null ? [] : [found];
     }
     else if (config.kind === "webhook") {
-        // v126: read by its sender's reader (webhook-readers.ts): Sentry's and Vercel's check shape, action and scope before
-        // an identity is claimed; the others pick their fields by dot-paths.
         const body = readWebhookPayload(payload);
         const sender = senderOf(config);
         const read = readDelivery(body, { sender, title: config.title, titleField: config.titleField, bodyField: config.bodyField, idField: config.idField ?? null, urlField: config.urlField ?? null, project: config.project ?? null, team: config.team ?? null });
-        // A delivery's own key: an unsigned webhook's is what the sender says (as before); a signed one's only what its
-        // signature covers — Standard Webhooks' signed id, or the raw bytes. Keys carry the sender, so nothing unsigned
-        // stands for anything signed.
         const bodyHash = createHash("sha256").update(delivery.body).digest("hex");
-        // A signed delivery id is outside words too: one that isn't a usable identity (padded, hidden characters, too long,
-        // or looking like a key) is never a key; the delivery is received under its bytes, and made into nothing.
         const signedId = proven.signedId === null ? null : identityOf(proven.signedId);
-        // An unsigned sender's own id is outside words too: judged as sent, and when it isn't a usable identity (padded,
-        // hidden characters, too long, looking like a key) the delivery keys on its bytes instead, as when there is none.
         const saidId = header(delivery, "x-request-id") || header(delivery, "x-delivery-id") || header(delivery, "idempotency-key");
         const headerId = saidId === "" ? null : identityOf(saidId);
         const deliveryKey = sender === "none"
@@ -1257,7 +1082,6 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
             : signedId?.ok === true ? `v3:${sender}:wid:${signedId.id}` : `v3:${sender}:body:${bodyHash}`;
         if (signedId?.ok === false)
             items = [{ key: deliveryKey, skip: `its delivery id: ${signedId.why}`, label: "Webhook", at: null }];
-        // Not for this flow: received under the delivery's own key, so it never uses up the identity of what it names.
         else if (read.kind === "ignored")
             return written(() => {
                 const before = store.flowReceipt(trigger.id, deliveryKey);
@@ -1269,7 +1093,6 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
         else if (read.kind === "skip")
             items = [{ key: deliveryKey, skip: read.why, label: "Webhook", at: null }];
         else {
-            // The outside thing's identity, when it has one, groups its deliveries: one card per issue or deployment.
             const key = read.identity === null ? deliveryKey : `v3:${sender}:id:${read.identity}`;
             items = [{ key, at: null, title: read.title, description: read.description,
                     source: { kind: sender === "sentry" || sender === "vercel" ? sender : "webhook", label: read.label, url: read.url,
@@ -1278,47 +1101,33 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
     }
     if (items.length === 0)
         return { status: 202, said: "Nothing for this flow." };
-    // Every key is outside words until judged (v126): a GitHub or Linear identifier, like any identity, that is too long,
-    // carries hidden characters or looks like a key is never a key — the delivery is received under its bytes instead,
-    // and made into nothing.
-    // (A webhook's identities were judged by its reader, raw, before its key was made: only GitHub's and Linear's here.)
     const deliveryBytes = createHash("sha256").update(delivery.body).digest("hex");
     if (config.kind !== "webhook")
         items = items.map(item => {
             const identity = item.key.slice(item.key.indexOf(":") + 1);
             const judged = identityOf(identity);
-            // A fixed label: nothing of the refused identity is kept, not even in the words the panel shows.
             if (!judged.ok)
                 return { key: `v3:${config.kind}:body:${deliveryBytes}`, skip: judged.why, label: "A delivery", at: null };
             if ("skip" in item)
                 return item;
-            // A signed GitHub or Linear delivery says, at its receipt, who proved it and what it names (v126) — a polled item
-            // never does, so the two stay apart; nothing is inferred later from today's settings.
             const url = safeLink(item.source.url, config.kind === "github" ? [{ host: "github.com", subdomains: false }] : [{ host: "linear.app", subdomains: false }]);
             return { ...item, source: { ...item.source, url, verified: config.kind, external: { id: judged.id, url }, receipt: item.key } };
         });
     const by = config.kind === "github" ? "GitHub" : config.kind === "linear" ? "Linear" : "Webhook";
     return written(() => {
-        // Received before (v126): said for what it was, never as a card that isn't there.
         const first = items[0];
         const before = items.length === 1 ? store.flowReceipt(trigger.id, first.key) : null;
         if (before !== null)
             return repeatAnswer(before);
-        // The hourly card limit (v126), decided in this same transaction, counted when each card was made: a signed delivery
-        // over it is held whole and made into its card when there's room; an unsigned one is turned away.
         const making = items.filter((item) => !("skip" in item));
         if (making.length > 0 && store.flowCardsAcceptedSince(trigger.id, new Date(now.getTime() - 3_600_000)) >= CARDS_PER_HOUR) {
-            // Rejections are decided before anything is written: an unsigned one writes nothing at all.
             if (unsigned)
                 return { status: 429, said: "Too many in the last hour. Try again later.", retryAfter: 3600 };
             if (store.heldFlowReceiptCount(trigger.id) >= HELD_AT_MOST) {
-                // Turned away, written nowhere but the trigger's lasting count.
                 store.noteFlowDeliveryDropped(trigger.id, now);
                 return { status: 503, said: "Too many waiting already. Resend it later from the sender's delivery log." };
             }
             const item = making[0];
-            // Screened and bounded whole before it is kept — its words as a card's are, and where it came from (label, link,
-            // identity) as a delivery's are: a held item is never something a card couldn't hold.
             const words = flowCardText(item.title, item.description);
             const source = heldSourceOf(item.source, item.key);
             const problem = "problem" in words ? (words.problem.startsWith("That looks like a key") ? "it looked like it held a key or password" : words.problem) : source === null ? "where it came from couldn't be kept safely" : null;
@@ -1341,16 +1150,10 @@ export function receiveFlowHook(store, token, delivery, dir, now) {
             : makeCard(store, trigger, config, item, by, now));
         const said = outcomeWords(results, false);
         note(said);
-        // The sender's answer is made from public reasons, not edited out of the panel's words.
         return { status: 202, said: outcomeWords(results.map(one => ({ ...one, note: publicReason(one.note) })), false) };
     });
 }
-/** A held item's whole size, at most, as saved: room for the largest card-sized item there can be (a 200-character
- * title and 4,000-character details, a label and two 2,000-character links) with every character escaped six-fold in
- * JSON, so no item a card could hold is ever refused for its size. */
 const HELD_ITEM_BYTES = 6 * (200 + 4_000 + 120 + 2 * 2_000 + 400) + 2_000;
-/** Where a held delivery came from, made safe to keep: a bounded label and kind with nothing that looks like a key, a
- * link made safe (https, no user information, query or fragment), a screened identity. Null when it can't be. */
 function heldSourceOf(source, key) {
     const label = source.label.slice(0, 120), kind = source.kind.slice(0, 40);
     if (looksSecret(label) || looksSecret(kind))
@@ -1376,13 +1179,6 @@ function readHeldItem(json) {
         return null;
     }
 }
-/**
- * v126: make a trigger's held deliveries into their cards while the last hour has room, oldest first. Each card in its
- * own write transaction, which reads everything it acts on under the write lock: the trigger (still active, still
- * taking deliveries), the hour's room, the oldest held receipt, the flow; then the same guards intake has (a failing
- * run already owned by another card in the project is left out). The card and the receipt's move to accepted land
- * together, or neither does.
- */
 export function drainHeldDeliveries(store, trigger, now) {
     let added = 0;
     for (;;) {
@@ -1406,7 +1202,6 @@ export function drainHeldDeliveries(store, trigger, now) {
                 store.skipHeldReceipt(current.id, next.key, "problem" in words ? words.problem : "it couldn't be read back");
                 return "left";
             }
-            // One failing run is one fix, held or not: a card another trigger in this project already made for it wins.
             const filed = next.key.startsWith("checks:") ? checksCardOf(store, flow.repo, next.key) : null;
             if (filed !== null) {
                 store.skipHeldReceipt(current.id, next.key, `already a card in ${filed}`);
@@ -1423,35 +1218,21 @@ export function drainHeldDeliveries(store, trigger, now) {
             added++;
     }
 }
-/**
- * v126: a delivery refused before it could be read (too large, a body that wouldn't read): it proves nothing, so it
- * counts toward its address's minute like any unproven delivery. The answer to give instead when that count is over.
- */
 export function hookRefusedUnread(store, token, now) {
     const trigger = /^[A-Za-z0-9_-]{20,64}$/.test(token) ? store.flowTriggerByHook(hookHash(token)) : null;
     const count = countUnproven(store, trigger?.hookHash ?? UNKNOWN_ADDRESS, now);
     return count.over ? { status: 429, said: "Too many. Try again later.", retryAfter: count.retryAfterSeconds } : null;
 }
-/** v126: a delivery received before, answered for what it was — never as a card that isn't there. */
 function repeatAnswer(before) {
     return { status: 202, said: before.state === "accepted" ? "Already received." : before.state === "held" ? "Already received; waiting for room."
             : before.state === "skipped" ? `Already received; it wasn't added${before.note === null ? "" : `: ${publicReason(before.note)}`}.` : "Already received." };
 }
-/** Why an item was left out, as its sender is told (v126): reasons about what it sent, but never this installation's
- * flows or cards — a reason that names one is said without it. The full words stay on the signed-in panel. */
 function publicReason(note) {
     if (note === null)
         return null;
     const at = note.indexOf("already a card in");
     return at === -1 ? note : `${note.slice(0, at)}already on a card`;
 }
-/**
- * v126: a webhook's credentials change. A new secret is written whole at an address of its own (an id made for this
- * change alone, so a change racing it never writes there), and only then does the trigger point at it — only from the
- * secret and settings read here, so of two changes at once exactly one lands. No secret means "": nothing is ever
- * adopted from a place an unfinished change may have left something. The loser removes only what it wrote; the winner
- * removes the secret it replaced, as cleanup only (nothing points at it any more).
- */
 function nextHookCredential(store, trigger, secret, configJson, now, dir, hookHash) {
     const credential = secret === null ? "" : randomBytes(16).toString("hex");
     if (secret !== null) {
@@ -1469,8 +1250,6 @@ function nextHookCredential(store, trigger, secret, configJson, now, dir, hookHa
     dropHookSecret(dir, trigger.id, trigger.hookCredential);
     return { ok: true };
 }
-/** A signing secret pasted on the secure panel behind the password, never in chat: Linear's, or a signed webhook's
- * sender's (Sentry's or Vercel's own, or a Standard or GitHub-style one made elsewhere). */
 export function saveSigningSecret(store, trigger, secret, now, dir) {
     const config = triggerConfigOf(trigger);
     const clean = secret.trim();
@@ -1494,11 +1273,6 @@ const SECRET_SHAPE_WORDS = {
     standard: "Paste the secret exactly as the sender shows it: whsec_ followed by its key.",
     "github-style": "Paste the secret exactly as the sender shows it (16 to 200 characters, no spaces).",
 };
-/**
- * v126: a new secret for a webhook whose sender Toolroll makes secrets for (Standard Webhooks, GitHub-style), shown once.
- * Its address stays as it is (New address is its own action). Sentry's and Vercel's secrets are theirs, pasted instead.
- * The only place such a secret is made: creating a trigger (from the panel, the gallery or an import) never does.
- */
 export function setUpFlowHook(store, trigger, now, dir) {
     const config = triggerConfigOf(trigger);
     if (config?.kind !== "webhook" || trigger.state === "removed")
@@ -1507,9 +1281,6 @@ export function setUpFlowHook(store, trigger, now, dir) {
     if (sender === "none" || !makesSecret(sender))
         return { ok: false, message: sender === "none" ? "An unsigned webhook has no secret. Choose who signs its deliveries first." : `${SENDER_WORDS[sender]} makes its own secret: paste it here instead.` };
     const secret = makeSecret(sender);
-    // A webhook with no address yet (made by the gallery or an import, where no one was shown one) gets its address with
-    // its secret, both shown together once. One that has an address keeps it — a replaced secret, a set-up after its
-    // sender changed — because the sender already has it.
     const first = trigger.hookHash === null;
     const token = first ? randomBytes(24).toString("base64url") : null;
     const saved = nextHookCredential(store, trigger, secret, null, now, dir, token === null ? undefined : hookHash(token));
@@ -1522,11 +1293,6 @@ export function setUpFlowHook(store, trigger, now, dir) {
         : { ok: true, id: trigger.id, said: `New secret made; any earlier one no longer works. Copy it now; it isn't shown again. The address stays as it is.`,
             reveal: { path: "", address: null, secret } };
 }
-/**
- * v126: change who signs a webhook's deliveries, in place: the trigger keeps its id, address and what it has received
- * (keys carry the sender, so nothing received unsigned stands for anything signed). Its credentials move to the next
- * generation with no secret: it isn't ready until it is set up again. Settings the new sender doesn't read are left out.
- */
 export function changeFlowHookSender(store, trigger, sender, actor, now, dir) {
     const config = triggerConfigOf(trigger);
     const flow = store.getFlow(trigger.flow);
@@ -1556,11 +1322,6 @@ export function changeFlowHookSender(store, trigger, sender, actor, now, dir) {
             : makesSecret(next) ? `Now signed by ${SENDER_WORDS[next]}. Set it up (its address and secret are shown together) before deliveries are taken: until then they are refused.`
                 : `Now signed by ${SENDER_WORDS[next]}. Paste ${SENDER_WORDS[next]}'s secret before deliveries are taken: until then they are refused.` };
 }
-/**
- * v126: which project (and, for Vercel, team) a Sentry or Vercel webhook takes deliveries from, set in place: the
- * trigger keeps its id, address, secret and history; blank takes any project the secret covers. Only from the settings
- * read here, so a change racing it doesn't land on top of it.
- */
 export function setFlowHookScope(store, trigger, scope, actor, now) {
     const config = triggerConfigOf(trigger);
     const flow = store.getFlow(trigger.flow);
@@ -1584,8 +1345,6 @@ export function setFlowHookScope(store, trigger, scope, actor, now) {
     const project = changed.kind === "webhook" ? changed.project ?? null : null;
     return { ok: true, said: project === null ? `Any ${SENDER_WORDS[sender]} project this secret covers can add cards.` : `Only deliveries from ${project} add cards now.` };
 }
-/** Whether a webhook trigger can prove its deliveries: an unsigned webhook always (its address is all it has), the others
- * once the current generation's secret is saved. */
 export function hookReady(trigger, dir) {
     const config = triggerConfigOf(trigger);
     if (config === null || !takesDeliveries(config))
@@ -1594,11 +1353,8 @@ export function hookReady(trigger, dir) {
         return true;
     return dir !== null && readHookSecret(dir, trigger.id, trigger.hookCredential) !== null;
 }
-// ------------------------------------------------------ public forms (v84)
 export const FORM_PATH = "/hooks/form/";
-/** At most this many cards an hour from one shared form. */
 const FORM_CARDS_PER_HOUR = 30;
-/** Share a button as a secret link anyone can fill in, without signing in. The link is shown once; only its hash is kept. */
 export function shareFlowButton(store, trigger, now, dir) {
     if (triggerConfigOf(trigger)?.kind !== "button" || trigger.state === "removed")
         return { ok: false, message: "Only a button can be shared as a form." };
@@ -1619,12 +1375,10 @@ label{display:grid;gap:6px;margin:0 0 16px;font-weight:600}input,textarea{font:i
 textarea{min-height:96px;resize:vertical}button{font:inherit;font-weight:600;border:0;border-radius:10px;padding:12px 18px;min-height:44px;background:var(--accent);color:var(--bg);cursor:pointer}
 p{color:var(--muted)}.trap{position:absolute;left:-10000px;width:1px;height:1px;overflow:hidden}a{color:var(--accent)}
 `;
-/** The public page: the button's name and its questions, nothing about the flow, the project or anyone in it. */
 function formHtml(label, body) {
     return htmlString(html `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex">
 <title>${label}</title>${styleElement(FORM_CSS)}</head><body><main><h1>${label}</h1><div class="card">${body}</div></main></body></html>`);
 }
-/** GET a shared form: its questions. */
 export function flowFormPage(store, token, now) {
     const trigger = /^[A-Za-z0-9_-]{20,64}$/.test(token) ? store.flowTriggerByHook(hookHash(token)) : null;
     const config = trigger === null ? null : triggerConfigOf(trigger);
@@ -1633,10 +1387,8 @@ export function flowFormPage(store, token, now) {
     if (!adapterPolicy({ caller: "anonymous", capability: "none" }, undefined, source => source === "flow" && store.getFlow(trigger.flow) !== null).ok)
         return { status: 403, html: "" };
     const fields = config.questions.map((question, index) => html `<label>${question}${index === 0 ? html `<input name="a${index}" required maxlength="200" autocomplete="off">` : html `<textarea name="a${index}" maxlength="3000"></textarea>`}</label>`);
-    // Signed out by nature: no session, so no CSRF; the trap, the shown time and the hourly limit guard it. It posts back to its own address.
     return { status: 200, html: formHtml(config.label, postForm("", html `${fields}<div class="trap" aria-hidden="true"><label>Leave this empty<input name="website" tabindex="-1" autocomplete="off"></label></div><input type="hidden" name="t" value="${now.getTime()}"><button>Send</button>`, { signedOut: true })) };
 }
-/** POST a shared form: at most one card per submission, keys refused, a limit per hour, and quiet about what a bot did wrong. */
 export function receiveFlowForm(store, token, fields, now) {
     const trigger = /^[A-Za-z0-9_-]{20,64}$/.test(token) ? store.flowTriggerByHook(hookHash(token)) : null;
     const config = trigger === null ? null : triggerConfigOf(trigger);
@@ -1646,7 +1398,6 @@ export function receiveFlowForm(store, token, fields, now) {
         return { status: 403, html: "" };
     const again = html `<p><a href="${FORM_PATH + token}">Send another</a></p>`;
     const thanks = formHtml(config.label, html `<p>Thanks — it's been sent.</p>${again}`);
-    // A filled trap, or a page posted faster than a person could, gets thanks and makes nothing.
     const form = readFormSubmission(fields, config.questions.length);
     const shown = Number(form.t);
     if ((form.website ?? "") !== "" || !Number.isFinite(shown) || now.getTime() - shown < 2000 || now.getTime() - shown > 86_400_000)
@@ -1664,9 +1415,6 @@ export function receiveFlowForm(store, token, fields, now) {
     store.updateFlowTrigger(trigger.id, { lastAt: now.toISOString(), lastOutcome: "Someone sent the form." }, now);
     return { status: 200, html: thanks };
 }
-/** Tidy's CI evidence (docs/plans/task-tidy.md): the watched branch's recent completed workflow runs, read through the
- * person's own gh login. Recorded only while the trigger still watches exactly that repository and branch once GitHub
- * answered; any failure records nothing (tidy then keeps the notices). */
 async function observeBranchRuns(store, trigger, config, gh, now) {
     if (config.branch === null)
         return;
@@ -1688,16 +1436,14 @@ async function observeBranchRuns(store, trigger, config, gh, now) {
         return;
     }
     const runs = [...readGithubRunList(body).workflow_runs ?? []];
-    // A few older failure cards' own runs, so tidy can tell whether each was a push to this branch (task-tidy.md).
     for (const id of unprovenNoticeRuns(store, trigger.id, config.repo)) {
         try {
             const one = await gh("gh", ["api", "-H", "Accept: application/vnd.github+json", `repos/${config.repo}/actions/runs/${id}`], { timeoutMs: 20_000 });
             if (one.code === 0)
                 runs.push(readGithubRun(JSON.parse(one.stdout)));
         }
-        catch { /* read again next time */ }
+        catch { }
     }
-    // Re-proved and recorded in one transaction: a trigger paused or changed meanwhile records nothing.
     store.transact(() => {
         const current = store.getFlowTrigger(trigger.id);
         const still = current === null ? null : triggerConfigOf(current);