toolroll 0.9.103 → 0.9.105

package/dist/flow-replies.js

@@ -3,7 +3,6 @@ import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./
 import { cardFollowers, notifyPeople } from "./flow-people.js";
 const WATCH_EVERY_MS = 60_000;
 const BACKOFF_MS = [60_000, 5 * 60_000, 15 * 60_000];
-/** A first read (or one after a long pause) looks this many messages back, so a reply that came just before isn't missed. */
 const LOOK_BACK = 50;
 const PER_READ = 50;
 const REPLY_CHARS = 4000;
@@ -16,14 +15,12 @@ const definitionOf = (store, flow) => {
         return null;
     }
 };
-/** Everyone a card's conversation is with: whom it wrote to, who wrote back, and who sent the email it came from. */
 function peopleOf(store, card) {
     const people = new Set(store.flowMailOf(card.id).flatMap(one => one.address.split(",")).filter(one => one !== ""));
     if (card.source?.mail?.from)
         people.add(card.source.mail.from.toLowerCase());
     return people;
 }
-/** Where the next email to this card's conversation goes in the thread: its latest message, and the chain before it. */
 export function threadOf(store, card) {
     const source = card.source?.mail;
     const ids = [...(source?.references ?? []), ...(source?.id ? [source.id] : []), ...store.flowMailOf(card.id).map(one => one.messageId)];
@@ -31,7 +28,6 @@ export function threadOf(store, card) {
     const latest = chain.at(-1);
     return latest === undefined ? null : { inReplyTo: latest, references: chain.slice(-20), people: peopleOf(store, card) };
 }
-/** What a Send email step sent, kept so a reply can find the card (and the email the card came from, which a reply may name). */
 export function recordSent(store, card, sent, now) {
     if (!/^<[^<>\s]{3,250}>$/.test(sent.id))
         return;
@@ -40,7 +36,6 @@ export function recordSent(store, card, sent, now) {
     if (source?.id)
         store.recordFlowMail({ messageId: source.id, card: card.id, direction: "received", address: source.from }, now);
 }
-/** Take one email as a reply to the card whose conversation it answers; null when it answers none that is active. */
 export function takeReply(store, mail, own, now) {
     if (mail.automatic || mail.messageId === null || mail.from === "" || mail.from === own.toLowerCase())
         return null;
@@ -53,7 +48,6 @@ export function takeReply(store, mail, own, now) {
         const card = store.getFlowCard(known.card);
         if (card === null || card.state !== "active" || !peopleOf(store, card).has(mail.from))
             continue;
-        // A trigger and the watcher can both read it: it is taken once.
         if (!store.recordFlowMail({ messageId: mail.messageId, card: card.id, direction: "received", address: mail.from }, now))
             return { card, moved: false, again: true };
         const text = mail.text.length > REPLY_CHARS ? `${mail.text.slice(0, REPLY_CHARS).trimEnd()}…` : mail.text;
@@ -62,7 +56,6 @@ export function takeReply(store, mail, own, now) {
         const definition = definitionOf(store, card.flow);
         const stage = definition?.stages.find(one => one.id === card.stage);
         const waiting = stage?.kind === "wait" && stage.wait?.for === "reply" && stage.next !== null;
-        // The people on the card hear about it; it needs them only when the flow wasn't waiting for it.
         const people = card.owner === null ? cardFollowers(store, card) : [card.owner];
         notifyPeople(store, card, people, null, { key: `reply:${mail.messageId}`, subject: `${mail.fromName ?? mail.from} replied to “${card.title}”`, body: text || "(no text)", attention: !waiting }, now);
         if (waiting) {
@@ -74,7 +67,6 @@ export function takeReply(store, mail, own, now) {
     }
     return null;
 }
-/** Read the mailbox for replies to cards in an email conversation, when it is due. */
 export async function watchFlowReplies(store, now, io) {
     const quiet = { read: 0, taken: 0, problem: null };
     const watch = store.flowMailWatch();
@@ -91,7 +83,6 @@ export async function watchFlowReplies(store, now, io) {
     if (!signed.ok)
         return failed(signed.said);
     const reader = io.mail ?? readThroughImap;
-    // After a long pause the mailbox may hold a lot: start again from now, looking a little way back.
     const stale = watch.nextAt === null || now.getTime() - Date.parse(watch.nextAt) > 24 * 60 * 60_000;
     let after = stale ? null : mailCursorOf(watch.cursor);
     if (after === null) {

package/dist/flow-result-card.js

@@ -1,7 +1,3 @@
-/**
- * A flow's result as a card (docs/plans/toolroll-cards.md): its steps from what the flow recorded (flow_event), with no
- * model, and a research report's items shown as the agent's report, never as Toolroll's records.
- */
 import { CARD_LIMITS, readChatCard } from "./contracts/chat-card.js";
 import { publicChatText } from "./chat-display.js";
 import { CHAT_CONTROLS } from "./chat-controls.js";
@@ -9,7 +5,6 @@ import { flowCardHref, flowDefinitionOf } from "./flow-engine.js";
 const OUTCOME_WORDS = { created: "Started", ok: "Passed", fail: "Failed", moved: "Moved on", approved: "Approved", "sent-back": "Sent back", cancelled: "Cancelled" };
 const clean = (text, cap) => publicChatText(text, cap);
 const tookWords = (ms) => ms < 60_000 ? `${Math.max(1, Math.round(ms / 1000))} sec` : ms < 7_200_000 ? `${Math.round(ms / 60_000)} min` : `${Math.round(ms / 3_600_000)} h`;
-/** The steps a card went through, in order: where it was, how it left, and for how long. */
 function stepsOf(store, definition, card, now) {
     const events = store.flowEvents(card.id);
     const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? id;
@@ -20,7 +15,6 @@ function stepsOf(store, definition, card, now) {
         return { title: titleOf(event.toStage), result: next === undefined ? (card.state === "active" ? "In progress" : "Finished") : OUTCOME_WORDS[next.outcome], ms };
     });
 }
-/** The result card of one flow card, as its records stand now; null when there is nothing recorded to show. */
 export function flowResultCard(store, flow, definition, card, now, extra = {}) {
     const steps = stepsOf(store, definition, card, now);
     if (steps.length === 0)
@@ -43,9 +37,7 @@ export function flowResultCard(store, flow, definition, card, now, extra = {}) {
     const buttons = [{ label: "Open card", path: flowCardHref(flow.id, card.id) }, ...(extra.links ?? []).filter(one => one.label !== "Card").map(one => ({ label: clean(one.label, CARD_LIMITS.label), path: one.path })), { label: CHAT_CONTROLS.flows.label, path: CHAT_CONTROLS.flows.href }];
     return readChatCard({ version: 1, title: heading, asOf: now.toISOString(), repos: [flow.repo], blocks, buttons: buttons.slice(0, CARD_LIMITS.buttons), actions: [] });
 }
-/** A card's "Done" notice: `flow-card:<card>:done:<entry>:<person>` (flow-engine.ts). */
 const FLOW_DONE_KEY = /^flow-card:([1-9][0-9]{0,14}):done:[1-9][0-9]{0,9}:/;
-/** The result card a "Done" notice carries; null for every other notice. */
 export function flowDoneCard(store, notification, now) {
     const visit = FLOW_DONE_KEY.exec(notification.dedupeKey);
     const card = visit === null ? null : store.getFlowCard(Number(visit[1]));

package/dist/flow-schedule.js

@@ -1,12 +1,3 @@
-/**
- * Schedules (v115: flow-owned; routines became scheduled flows).
- *
- * A schedule trigger fires on one of four readable cadences. Its two failure modes are subtle enough to deserve
- * names: advancing one interval after downtime leaves the next firing in the past — a catch-up burst; advancing to
- * `now + interval` drifts the cadence forever. The rule is ALIGNED advancement: the next occurrence strictly after
- * now, anchored to the occurrence that just fired (for `every`) or to the clock itself (for calendar schedules).
- * Missed slots while nothing was running fire ONCE — the overdue occurrence — and are never backfilled.
- */
 import { createHash } from "node:crypto";
 import { fileTaskProposal } from "./proposal.js";
 import { reportsCost } from "./provider.js";
@@ -29,15 +20,8 @@ export function validTimezone(value) {
         return false;
     }
 }
-/** Bounds a person would pick on purpose: 5 minutes to 7 days. */
 export const MIN_EVERY_MINUTES = 5;
 export const MAX_EVERY_MINUTES = 7 * 24 * 60;
-/**
- * Existing daily schedules remain UTC. Calendar schedules may name an IANA
- * timezone, whose wall-clock time stays fixed across daylight saving changes.
- * No cron expressions in v1 — a schedule the operator cannot read at a
- * glance is a schedule they cannot honestly approve.
- */
 export function parseSchedule(text) {
     if (text.trim() !== text)
         return null;
@@ -61,7 +45,6 @@ export function parseSchedule(text) {
 export function scheduleText(schedule) {
     return schedule.kind === "every" ? `every:${schedule.minutes}` : `${schedule.kind === "weekly" ? `weekly:${schedule.day}` : schedule.kind}:${schedule.hhmm}${schedule.timezone === undefined ? "" : `@${schedule.timezone}`}`;
 }
-/** The schedule, in words an operator agrees to. */
 export function describeSchedule(schedule) {
     if (schedule.kind !== "every")
         return `${schedule.kind === "daily" ? "daily" : schedule.kind === "weekdays" ? "weekdays" : `every ${WEEKDAYS[schedule.day]}`} at ${schedule.hhmm} ${schedule.timezone ?? "UTC"}`;
@@ -72,36 +55,23 @@ export function describeSchedule(schedule) {
         return `every ${minutes / 60} hour(s)`;
     return `every ${minutes} minutes`;
 }
-/**
- * The first occurrence after approval: the schedule starts counting from the
- * yes, because "approved at 14:07, every 60 minutes" firing instantly would
- * spend before the approver's hand left the keyboard.
- */
 export function firstFireAt(schedule, now) {
     if (schedule.kind === "every") {
         return new Date(now.getTime() + schedule.minutes * 60_000).toISOString();
     }
     return nextCalendar(schedule, now);
 }
-/**
- * Aligned advancement: the smallest cadence occurrence STRICTLY after now.
- * `anchor` is the occurrence that just fired (or was just skipped) — the
- * cadence grid grows from it, so a pass that ran late does not tilt every
- * later firing by its lateness.
- */
 export function nextFireAt(schedule, anchorIso, now) {
     if (schedule.kind !== "every")
         return nextCalendar(schedule, now);
     const interval = schedule.minutes * 60_000;
     const anchor = new Date(anchorIso).getTime();
     const elapsed = now.getTime() - anchor;
-    // Strictly after now: an occurrence landing exactly on now already fired.
     const steps = Math.max(1, Math.floor(elapsed / interval) + 1);
     return new Date(anchor + steps * interval).toISOString();
 }
 function nextCalendar(schedule, now) {
     const format = new Intl.DateTimeFormat("en-US", { timeZone: schedule.timezone ?? "UTC", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
-    // Represent wall-clock components as a UTC number solely for arithmetic.
     const wall = (instant) => {
         const parts = Object.fromEntries(format.formatToParts(instant).map(part => [part.type, part.value]));
         return Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute));
@@ -115,9 +85,6 @@ function nextCalendar(schedule, now) {
             continue;
         if (schedule.kind === "weekdays" && (new Date(target).getUTCDay() === 0 || new Date(target).getUTCDay() === 6))
             continue;
-        // Nearby dates expose both offsets around a daylight-saving transition.
-        // A missing clock time skips its slot. An ambiguous time uses the first
-        // occurrence only, even if the scheduler advances during the repeated hour.
         const offsets = [...new Set([-36, 0, 36].map(hours => { const sample = target + hours * 3_600_000; return wall(sample) - sample; }))];
         const matches = offsets.map(offset => target - offset).filter(instant => wall(instant) === target);
         if (matches.length > 0) {
@@ -128,18 +95,10 @@ function nextCalendar(schedule, now) {
     }
     throw new Error("No calendar occurrence within the next fifteen days");
 }
-// ------------------------------------------------------------------ standing orders
-/** The rolling window a standing order's cost ceiling counts over: seven days, and every surface says so. */
 export const BUDGET_WINDOW_MS = 7 * 24 * 60 * 60_000;
-/** A firing's task id: the order's stem stamped with its slot (`nightly-deps-20261008-0700`). */
 export function instanceId(stem, slotIso) {
     return `${stem}-${slotIso.replace(/[-:]/g, "").slice(0, 13).replace("T", "-")}`;
 }
-/**
- * The exact standing order an approver agreed to, as 128 bits — byte for byte what a routine's digest was, so a
- * routine's approval moved onto a scheduled flow (v115) still verifies: the project, the terms, the schedule, the
- * ceiling, and the agents the approval froze. Editing any of them (or moving the flow) strands the approval.
- */
 export function standingDigestOf(repo, schedule, order, acceptance, profile, route) {
     return createHash("sha256").update(JSON.stringify({
         repo,
@@ -156,11 +115,6 @@ export function standingDigestOf(repo, schedule, order, acceptance, profile, rou
         route: routeDigestOf(route),
     }), "utf8").digest("hex").slice(0, 32);
 }
-/**
- * Whether a standing order's carried approval still stands, read whole before anything is written: the frozen agents
- * read back, re-hash with the order's terms, this schedule and project to the digest the approver signed, state no
- * problem, and build and repair on the approved profile's own agents. `problem` is null when there is no approval.
- */
 export function standingApproval(order, repo, schedule) {
     const read = parseAcceptanceCriteria(order.acceptance);
     const acceptance = read.problems.length === 0 && read.criteria.length > 0 ? read.criteria : null;
@@ -184,27 +138,16 @@ export function standingApproval(order, repo, schedule) {
     }
     return { live: true, by: order.approval.by, profile, route, acceptance };
 }
-/** A firing that must not stand: thrown inside the transaction so nothing it wrote survives. */
 export class StandingOrderRefused extends Error {
 }
-/**
- * File one firing of a standing order (v115, what firing a routine did), inside the caller's transaction. It skips,
- * saying why, while the last task is unfinished or the rolling 7-day ceiling is reached (an unmeasured paid run fails
- * closed). Otherwise it files the order's terms unchanged: approved by the carried approval when that still verifies
- * — on exactly the agents it froze, sealed like any automatic approval under the project's rules — or else as an
- * ordinary proposal that waits for the project's approval rules like any other.
- */
 export function fileStandingOrder(store, input, now) {
     const { order, repo } = input;
-    // The nightly full check on main files a check-only task of its own (nightly-check.ts).
     if (order.check !== undefined)
         return fileNightlyCheck(store, input, now);
     const blocker = store.standingOrderBlocker(input.trigger, order.routine, now);
     if (blocker !== null)
         return { made: "skipped", note: `Skipped: the last one (${blocker.taskId}, ${blocker.state}) hasn't finished.` };
     const standing = standingApproval(order, repo, input.schedule);
-    // The carried approval stands only while its approver still can approve here (approval policy §1.6): a demoted
-    // person, one off the project, or an approval that names nobody files an ordinary proposal instead.
     const approverStands = standing.live && standing.by !== null && (() => {
         const account = store.accountOf(standing.by);
         return account !== null && account.revokedAt === null && account.role === "approver" && store.accountCanAccess(standing.by, repo);
@@ -241,8 +184,6 @@ export function fileStandingOrder(store, input, now) {
             store.setRequirements(ref.id, order.requirements);
         return { made: "filed", taskId: filed.id, approved: false, note: approval.problem === null ? null : `Its earlier approval no longer applies (${approval.problem}), so this one waits for approval.` };
     }
-    // The approved road: the frozen agents are the pin, the terms are the scope byte for byte, and the seal must read
-    // back as the frozen route — or nothing of this firing stands.
     store.createTask({ id: taskId, title: input.title, filedBy }, now);
     const ref = store.refFor(BUILT_IN, taskId, "ours");
     store.placeTask(ref.id, repo);
@@ -251,11 +192,7 @@ export function fileStandingOrder(store, input, now) {
         store.setRequirements(ref.id, order.requirements);
     const draft = { goal: order.goal, outOfScope: order.outOfScope, touches: [...order.touches], acceptance: approval.acceptance, ...(order.budgetPerRunMicrousd == null ? {} : { budgetMicrousd: order.budgetPerRunMicrousd }) };
     const digest = digestOf(draft, approval.profile, approval.route);
-    // Filed unapproved; only the seal below approves it (no approval fields are written beside it).
     store.saveScope({ taskId, ...draft, proposedAt: now.toISOString(), digest, budgetMicrousd: order.budgetPerRunMicrousd ?? null, approvedAt: null, approvedBy: null, approvedDigest: null }, {}, { profile: approval.profile, route: approval.route });
-    // Its own authority (approval policy §1.6): the standing order's carried approval, never a person's ceremony. A seal
-    // the project's rules refuse to an automatic approval (checks beyond the sandbox, protected work, policy) leaves the
-    // task filed and waiting for a person, as any unapproved firing does — never a dropped firing.
     const sealed = store.sealScopeApproval(taskId, approval.by, now, {}, { kind: "schedule", modeDigest: order.approval.digest }, "automation");
     if (!sealed)
         return { made: "filed", taskId, approved: false, note: "Its approval can't stand on its own here (its checks reach beyond the sandbox, or the project's rules need a person), so this one waits for approval." };
@@ -265,7 +202,6 @@ export function fileStandingOrder(store, input, now) {
     }
     return { made: "filed", taskId, approved: true, note: null };
 }
-/** A standing order in the words a person reads before turning its schedule on. */
 export function describeStandingOrder(order, repo, schedule) {
     const approval = standingApproval(order, repo, schedule);
     return [
@@ -279,10 +215,8 @@ export function describeStandingOrder(order, repo, schedule) {
         approval.live ? `Approved by ${approval.by ?? "an approver"}: each run builds without asking, on the agents approved then.` : approval.problem === null ? "Each run waits for approval under the project's rules." : `Each run waits for approval: its earlier approval no longer applies (${approval.problem}).`,
     ];
 }
-/** Every problem with a standing order's terms and schedule at once, as `field: problem` lines (none when it can be set up). */
 export function standingTermsProblems(terms, schedule) {
     const problems = [];
-    // What an approver reads must be what it appears to be (no control, invisible or direction-override text), bounded in bytes too.
     const unfit = (text, chars, bytes) => text.length > chars || Buffer.byteLength(text, "utf8") > bytes || hasForbiddenControls(text) || hasDisguisedText(text);
     if (terms.goal.trim() === "" || unfit(terms.goal, 2_000, 8_000))
         problems.push("goal: required, at most 2000 characters, no control or hidden characters");
@@ -292,7 +226,6 @@ export function standingTermsProblems(terms, schedule) {
         problems.push("touches: at most 50 paths, each non-empty and under 200 characters");
     if (terms.requirements.length > 20 || terms.requirements.some(one => parseCapabilityKey(one) === null || unfit(one, 400, 400)))
         problems.push("requirements: capability keys, `kind:name`, at most 20");
-    // Each firing copies its success checks forward unchanged and never asks again, so there must be at least one.
     const read = parseAcceptanceCriteria(terms.acceptance);
     if (read.problems.length > 0)
         problems.push(`acceptance: ${read.problems.map(one => one.message).join("; ")}`);
@@ -306,13 +239,6 @@ export function standingTermsProblems(terms, schedule) {
         problems.push("budgetPerRunMicrousd: a positive whole micro-dollar amount, or none");
     return problems;
 }
-/**
- * A scheduled flow a person set up (a template or a recipe; v115, what filing a routine was): a Build step that follows
- * the task each firing files, then Done, and a schedule trigger carrying the terms as its standing order — with no
- * approval, so each firing waits for approval under the project's rules. The schedule starts PAUSED with no time:
- * nothing repeats until a person turns it on, and it starts counting then. Its tasks are filed as `filedBy`'s (default
- * `by`; null files them as automation's). Inside the caller's transaction, if any.
- */
 export function createScheduledFlow(store, input, now) {
     const problems = standingTermsProblems(input.terms, input.schedule);
     if (!/^[a-z0-9][a-z0-9-]{0,40}$/.test(input.stem))

package/dist/flow-scripts.js

@@ -1,17 +1,6 @@
-/**
- * Project scripts (v84): a library of reusable steps that run with no AI.
- * A script is named — "run-tests", "enrich-lead", "export-orders" — and
- * made on a flow's Scripts panel or drafted by the lead in chat. v90: it is
- * written in shell, Python or Node, or runs a file already in the project.
- * Any flow in the project uses it by name from a "Run a script" zone (and a
- * schedule can run one to make cards), so one script can be improved once
- * for every flow, and the insights show how each script does across them.
- * Each save is a new version; runs record which ran.
- */
 import { createHash } from "node:crypto";
 import { scanForSecrets } from "./evidence.js";
 import { SCRIPT_LANGUAGES, SCRIPT_NAME } from "./flows.js";
-/** A script as it would be saved, checked in plain words. Throws. */
 export function validateScript(input) {
     const name = typeof input.name === "string" ? input.name.trim().toLowerCase() : "";
     if (!SCRIPT_NAME.test(name))
@@ -41,9 +30,7 @@ export function validateScript(input) {
         throw new Error("A script may run for 1 to 60 minutes.");
     return { name, about, body, timeoutMinutes: minutes, language: language, file };
 }
-/** What a run is held to. A shell script written here keeps its v84 digest. */
 export const scriptDigest = (draft) => createHash("sha256").update((draft.language ?? "shell") === "shell" && (draft.file ?? null) === null ? `${draft.body}\0${draft.timeoutMinutes}` : `${draft.body}\0${draft.timeoutMinutes}\0${draft.language}\0${draft.file ?? ""}`).digest("hex").slice(0, 32);
-/** Save a script (a new version when it exists). */
 export function saveScript(store, repo, input, actor, now) {
     let draft;
     try {

package/dist/flow-secrets.js

@@ -1,17 +1,8 @@
-/**
- * A project's flow secrets (v87; v90 for scripts too): named values kept in
- * a 0600 file beside the database, one file per project. Web requests use
- * them in headers ({{secret.NAME}}), and code steps get the ones they name as
- * environment variables. Their values never reach a card, a log or a page.
- * Its own module, with nothing but the file system, so triggers and the step
- * runners can read it without an import cycle.
- */
 import { createHash } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 export const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,39}$/;
 const secretsFile = (dir, repo) => join(dir, "flow-secrets", `${createHash("sha256").update(repo).digest("hex").slice(0, 24)}.json`);
-/** Any saved secret's value that shows up in output, replaced (a web response, a tool's answer, a script's output). */
 export const scrubSecrets = (text, secrets) => Object.values(secrets).filter(value => value.length >= 6).reduce((out, value) => out.split(value).join("[secret]"), text);
 export function readFlowSecrets(dir, repo) {
     if (dir === null)
@@ -26,7 +17,6 @@ export function readFlowSecrets(dir, repo) {
 export function flowSecretNames(dir, repo) {
     return Object.keys(readFlowSecrets(dir, repo)).sort();
 }
-/** Set (or, with an empty value, remove) one of a project's secrets. Names are CAPITALS_AND_UNDERSCORES. */
 export function setFlowSecret(dir, repo, name, value) {
     if (!SECRET_NAME.test(name))
         return { ok: false, message: "Name the secret in capitals, like API_TOKEN." };

package/dist/flow-send.js

@@ -1,18 +1,3 @@
-/**
- * "Send to me" and "Person chooses" zones (flows.ts): what a card's step before produced, sent to the card's person.
- *
- * - The person is the card's owner, else the flow's.
- * - What is sent: the card's title and the step it comes from, a summary (the build's own report, a research report,
- *   or what the step before wrote), its links (the result, its pull request, the report, the card) and the build's
- *   screenshots. It is worked out once per visit and kept (flow_send), so every chat app and the card show the same.
- * - It goes as one notification to that person, which each chat app they paired delivers (Telegram: the screenshots as
- *   one album; Slack and Discord: uploads in its thread; Teams: a link to them), and the card shows it in the console.
- * - A choose visit carries the zone's options as buttons (telegram-flow.ts, chat-flow.ts, and the card). Each leads to
- *   a zone, or ends the card as Ignored; a reply instead is the {{note}} for where replies go. Every choice is made
- *   here (chooseFlowCard), for exactly the visit the person saw, by that person alone, and ledgered with where.
- *
- * Deterministic and model-free, in the worker's flow pass.
- */
 import { assignmentOf } from "./assignment.js";
 import { TEXT_LIMITS } from "./text-limits.js";
 import { withActor } from "./actor.js";
@@ -25,21 +10,16 @@ import { flowResultCard } from "./flow-result-card.js";
 import { readVerifiedReport } from "./evidence.js";
 import { FLOW_END, replyTarget } from "./flows.js";
 import { FLOW_SHOTS_KIND } from "./store.js";
-/** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
 export const FLOW_SEND_KEY = /^flow-send:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/;
-/** The notice a "Person chooses" visit sends: `flow-choose:<card>:<entry>`, a "flow-decision" like an approval's. */
 export const FLOW_CHOOSE_KEY = /^flow-choose:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/;
-/** What the person is asked under the buttons. */
 export const REPLY_ASK = "Or reply with what you'd change.";
 const SUMMARY_CHARS = 1500;
 const STEP_CHARS = 500;
-/** Who a card's "Send to me" and "Person chooses" zones are for: its owner, else the flow's. */
 export function flowPersonOf(card, flow) {
     return card.owner ?? flow.owner;
 }
 const cut = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1).trimEnd()}…`;
 const plain = (text) => text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").replace(/\n{3,}/g, "\n\n").trim();
-/** The zone the card came from into this visit: its latest move, else a zone that leads here. */
 function stepBefore(store, definition, card) {
     const events = store.flowEvents(card.id);
     const last = events[events.length - 1];
@@ -47,7 +27,6 @@ function stepBefore(store, definition, card) {
     return definition.stages.find(one => one.id === from)
         ?? definition.stages.find(one => one.next === card.stage || one.onFail === card.stage || (one.options ?? []).some(option => option.to === card.stage)) ?? null;
 }
-/** A result's facts for the person, read as the operator would: its report, its pull request and screenshots. */
 function resultOf(store, taskId, now, evidenceRoot) {
     const repo = store.lookupRef(taskId)?.repo ?? null;
     if (repo === null)
@@ -61,7 +40,6 @@ function resultOf(store, taskId, now, evidenceRoot) {
         shots: receipt !== null && store.artifactsFor(receipt.runId).some(one => one.kind === "screenshot") ? { taskId: receipt.taskId, run: receipt.runId } : null,
     };
 }
-/** A research task's latest delivered report, when its run saved screenshots: what that step produced to show. */
 function reportShotsOf(store, taskId) {
     const ref = store.lookupRef(taskId);
     if (ref === null)
@@ -69,7 +47,6 @@ function reportShotsOf(store, taskId) {
     const run = store.runsFor(ref.id).find(one => one.finishedAt !== null && one.role === "scout");
     return run !== undefined && run.outcome === "built" && store.artifactsFor(run.id).some(one => one.kind === "screenshot") ? { taskId, run: run.id } : null;
 }
-/** A research task's report items, each with its source, how it plugs in, and its screenshot from that run. */
 function reportItemsOf(store, taskId, shots, evidenceRoot) {
     const ref = store.lookupRef(taskId);
     const view = ref === null || evidenceRoot === undefined ? null : readVerifiedReport(store, evidenceRoot, ref.id);
@@ -81,11 +58,9 @@ function reportItemsOf(store, taskId, shots, evidenceRoot) {
         return { title: plain(item.title), why: plain(item.why), url: item.url, source: itemSource(item.url), plug: plain(itemPlug(item.why, image?.caption ?? null)), shot };
     });
 }
-/** What a visit sends its person, worked out from the card as it is now. */
 export function flowSendContent(store, flow, definition, stage, card, now, evidenceRoot) {
     const before = stepBefore(store, definition, card);
     const output = before === null ? undefined : card.outputs[before.id]?.trim() || undefined;
-    // The task the step before produced (a build or research zone hands it over), and the card's main build.
     const handed = card.task !== null && before !== null && (before.kind === "task" || before.kind === "report") ? card.task : null;
     const report = handed !== null && before?.kind === "report" ? handed : null;
     const build = before?.kind === "task" && handed !== null ? handed : card.primaryTask;
@@ -101,7 +76,6 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
     else if (output !== undefined)
         lines.push(cut(output, SUMMARY_CHARS));
     else {
-        // Nothing from the step before: the latest thing any zone wrote, else the card's own details.
         const latest = [...definition.stages].reverse().find(one => one.id !== stage.id && card.outputs[one.id]?.trim());
         lines.push(latest !== undefined ? `${latest.title}: ${cut(card.outputs[latest.id].trim(), SUMMARY_CHARS)}` : card.description === null ? "Nothing was written down for this step." : cut(card.description, SUMMARY_CHARS));
     }
@@ -114,10 +88,8 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
         links.push({ label: "Report", path: `/t/${encodeURIComponent(report)}` });
     links.push({ label: "Card", path: flowCardHref(flow.id, card.id) });
     const options = stage.kind === "choose" ? (stage.options ?? []).map((one, choice) => ({ choice, label: one.label })) : undefined;
-    // After research, its own screenshots are what that step produced; otherwise the build's.
     const shots = (report === null ? null : reportShotsOf(store, report)) ?? built?.shots ?? null;
     const items = report === null ? [] : reportItemsOf(store, report, shots?.taskId === report ? shots : null, evidenceRoot);
-    // A "Send to me" is what a flow hands over: the steps it took, as a card under the words.
     const result = stage.kind === "send" ? flowResultCard(store, flow, definition, card, now, { links: links.flatMap(one => "path" in one ? [one] : []), items }) : null;
     return {
         title: cut(plain(before === null ? card.title : `${card.title} · ${before.title}`), 200), ...(before === null ? {} : { from: before.title }),
@@ -125,8 +97,6 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
         ...(options === undefined ? {} : { options, reply: replyTarget(stage) !== null }),
     };
 }
-/** A kept content, read back (src/contracts/flow-send.ts: one kept before it carried a version reads as it did); null
- * when it can't be, and the visit's content is worked out again. */
 export function readFlowSend(json) {
     let raw;
     try {
@@ -138,16 +108,13 @@ export function readFlowSend(json) {
     const read = readFlowSendPayload(raw);
     return read.ok ? read.value : null;
 }
-/** The words of a sent visit: its title, summary and pull request (the one link that isn't a page of Toolroll's). */
 export function flowSendText(content) {
     const pull = content.links.find((one) => "url" in one);
     return [content.title, content.summary, ...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`])].filter(one => one !== "").join("\n\n");
 }
-/** The links a sent visit's message carries as buttons: Toolroll's own pages, the first one first. */
 export function flowSendPaths(content) {
     return content.links.filter((one) => "path" in one);
 }
-/** A visit's content, kept the first time; later passes (and every chat app) read the same one. */
 function keep(store, flow, definition, stage, card, now, evidenceRoot) {
     const person = flowPersonOf(card, flow);
     const kept = store.flowSend(card.id, card.entry);
@@ -158,7 +125,6 @@ function keep(store, flow, definition, stage, card, now, evidenceRoot) {
     const fresh = store.recordFlowSend({ card: card.id, entry: card.entry, stage: stage.id, person, contentJson: flowSendForStore(content) }, now);
     return { content, person, fresh };
 }
-/** One notice to the person, and its screenshots after it. Never as anyone's own act: they asked for it in the flow. */
 function enqueue(store, flow, card, person, content, notice, now) {
     if (!store.accountCanAccess(person, flow.repo))
         return;
@@ -171,7 +137,6 @@ function enqueue(store, flow, card, person, content, notice, now) {
         }
     });
 }
-/** A "Send to me" visit: what the step before produced, to the person once; the card moves on after. */
 export function sendStep(store, flow, definition, stage, card, now, evidenceRoot) {
     const { content, person, fresh } = keep(store, flow, definition, stage, card, now, evidenceRoot);
     if (!fresh)
@@ -180,7 +145,6 @@ export function sendStep(store, flow, definition, stage, card, now, evidenceRoot
     enqueue(store, flow, card, person, content, { key: `flow-send:${card.id}:${card.entry}`, kind: "flow-card", attention: false,
         subject: `${flow.name}: ${content.title}`, body: [content.summary, ...content.links.filter((one) => "url" in one).map(one => `${one.label}: ${one.url}`)].join("\n\n") }, now);
 }
-/** A "Person chooses" visit: the same content with the zone's options, to the person once; the card waits for their choice. */
 export function chooseStep(store, flow, definition, stage, card, now, evidenceRoot) {
     const { content, person, fresh } = keep(store, flow, definition, stage, card, now, evidenceRoot);
     const waiting = `Waiting for ${person} to choose`;
@@ -191,16 +155,13 @@ export function chooseStep(store, flow, definition, stage, card, now, evidenceRo
     enqueue(store, flow, card, person, content, { key: `flow-choose:${card.id}:${card.entry}`, kind: "flow-decision", attention: true,
         subject: `${flow.name}: ${content.title}`, body: flowChooseBody(content) }, now);
 }
-/** The words above a choice's buttons: what was done, then what to do. */
 export function flowChooseBody(content) {
     return [content.summary, ...flowSendTail(content)].join("\n\n");
 }
-/** What a sent visit's message ends with, after its summary (and items): its pull request, and for a choice what to do. */
 export function flowSendTail(content) {
     const pull = content.links.find((one) => "url" in one);
     return [...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`]), ...(content.options === undefined ? [] : [content.reply === true ? `Choose one. ${REPLY_ASK}` : "Choose one."])];
 }
-/** The card, if it is still at that visit, waiting for its person's choice. */
 export function flowChoiceAt(store, cardId, entry) {
     const card = store.getFlowCard(cardId);
     const flow = card === null ? null : store.getFlow(card.flow);
@@ -213,13 +174,7 @@ export function flowChoiceAt(store, cardId, entry) {
     return { card, flow, stage, definition, person: flowPersonOf(card, flow) };
 }
 const via = (where) => where === "" ? "" : ` in ${where}`;
-/**
- * A person's choice on a card waiting at a "Person chooses" zone: an option (by its place, and the words and zone they saw), or a
- * reply (`choice` null) that becomes the note for where replies go. `where` names the place it was made, for the card's
- * history and the ledger: "Telegram", "Slack", "the console".
- */
 export function chooseFlowCard(store, input, now) {
-    // The answer itself (src/contracts/flow-send.ts): an option that isn't one of the places offered is a changed option.
     const { actor: _actor, where: _where, repos: _repos, evidenceRoot: _root, ...given } = input;
     const answer = readFlowChoiceAnswer(given);
     if (!answer.ok)