toolroll 0.9.103 → 0.9.105

package/dist/webhook-readers.js

@@ -1,26 +1,12 @@
-/**
- * What a proven webhook delivery says, read by its sender's reader (docs/plans/webhook-tasks.md §2). A signature proves
- * who sent a delivery, not that it belongs in this flow: Sentry's and Vercel's readers check its shape, its action and
- * the configured scope first, and only then give it an identity. Anything else is ignored, with why, and claims no
- * identity. The generic senders pick their fields by dot-paths. Every outside value is screened for secrets before it
- * is used anywhere (a key, a held item, a card, a task), and every link is made safe before it is kept.
- */
 import { scanForSecrets } from "./evidence.js";
 const HIDDEN = /[\u0000-\u001f\u007f​-‏‪-‮⁦-⁩]/;
 const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 const pick = (body, path) => path.split(".").reduce((node, part) => record(node)[part], body);
 const text = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : null;
-/** A string or a safe integer, as an identity's words exactly as sent; anything else isn't one. */
 const idWords = (value) => typeof value === "string" ? value : typeof value === "number" && Number.isSafeInteger(value) ? String(value) : null;
-/** Whether outside words could hold a key or password (the same check cards' words get). */
 export const looksSecret = (value) => scanForSecrets(value).length > 0;
 export const SENTRY_HOSTS = [{ host: "sentry.io", subdomains: true }];
 export const VERCEL_HOSTS = [{ host: "vercel.com", subdomains: false }];
-/**
- * A link kept from a delivery: absolute https, at most 2,000 characters, no user information, and with its query and
- * fragment dropped (where tokens travel). `hosts` narrows it to a sender's own site (and its subdomains). Null when it
- * isn't one, or when what is left could still hold a secret.
- */
 export function safeLink(value, hosts) {
     if (typeof value !== "string" || value.length > 2000 || HIDDEN.test(value))
         return null;
@@ -37,10 +23,8 @@ export function safeLink(value, hosts) {
     if (hosts !== null && !hosts.some(one => host === one.host || (one.subdomains && host.endsWith(`.${one.host}`))))
         return null;
     const kept = `${url.origin}${url.pathname}`;
-    // Judged as it will be kept: an address that only normalises past 2,000 characters (escaped non-ASCII) isn't kept.
     if (kept.length > 2000)
         return null;
-    // Screened as kept and as read: a token spelled with percent-escapes is the same token. A path that won't decode isn't kept.
     let decoded;
     try {
         decoded = decodeURIComponent(url.pathname);
@@ -50,39 +34,31 @@ export function safeLink(value, hosts) {
     }
     return looksSecret(kept) || looksSecret(decoded) || HIDDEN.test(decoded) ? null : kept;
 }
-/** The identity words a key may carry: at most 120 characters, nothing hidden, and nothing that looks like a secret. */
 export function identityOf(value) {
     const sent = idWords(value);
     if (sent === null || sent.trim() === "")
         return { ok: false, why: "its identity is missing" };
-    // Judged as sent, before anything is trimmed: padding, hidden characters or length make it unusable, never another id.
     if (sent.length > 120 || HIDDEN.test(sent) || sent !== sent.trim())
         return { ok: false, why: "its identity isn't usable" };
     if (looksSecret(sent))
         return { ok: false, why: "it looked like it held a key or password" };
     return { ok: true, id: sent };
 }
-/** Sentry's API address for an event names its project's slug (…/api/0/projects/<org>/<project>/events/<id>/): read
- * only from that exact shape on Sentry's own host. */
 function sentrySlugOf(value) {
     const link = typeof value === "string" ? value : "";
     const match = /^https:\/\/(?:[a-z0-9-]+\.)?sentry\.io\/api\/0\/projects\/[a-z0-9_-]+\/([a-z0-9_-]+)\/events\/[A-Za-z0-9-]+\/?$/.exec(link);
     return match?.[1] ?? null;
 }
-/** Sentry: an issue alert (action "triggered", with the event) or a new issue (action "created", with the issue). */
 function readSentry(body, settings) {
     const action = text(record(body)["action"]);
     const data = record(record(body)["data"]);
     const alert = action === "triggered" && Object.keys(record(data["event"])).length > 0;
     const created = action === "created" && Object.keys(record(data["issue"])).length > 0;
-    // A fixed reason: nothing the sender wrote is kept for an event Toolroll doesn't take.
     if (!alert && !created)
         return { kind: "ignored", why: "not an issue alert or a new issue" };
     const thing = record(alert ? data["event"] : data["issue"]);
-    // Scope from the body alone (the resource header isn't signed): the project's id or slug, as Sentry sends it.
     if (settings.project !== null) {
         const project = record(thing["project"]);
-        // An alert's event names its project by number, and by slug only in its API address; a new issue names both.
         const names = [idWords(thing["project"]), idWords(project["id"]), text(project["slug"]), sentrySlugOf(thing["url"])].filter((one) => one !== null);
         if (!names.some(one => one.toLowerCase() === settings.project.toLowerCase()))
             return { kind: "ignored", why: "from another Sentry project" };
@@ -94,7 +70,6 @@ function readSentry(body, settings) {
     const culprit = text(thing["culprit"]);
     return { kind: "item", identity: identity.id, url: safeLink(thing["web_url"], SENTRY_HOSTS), title, description: culprit === null ? "From a Sentry issue." : `From a Sentry issue, in ${culprit}.`, label: "Sentry issue" };
 }
-/** Vercel: a failed deployment only, from the configured project and team. */
 function readVercel(body, settings) {
     const type = text(record(body)["type"]);
     if (type !== "deployment.error")
@@ -112,13 +87,11 @@ function readVercel(body, settings) {
     return { kind: "item", identity: identity.id, url: safeLink(record(payload["links"])["deployment"], VERCEL_HOSTS), title: name === null ? settings.title : `${name} failed to deploy`,
         description: "From a failed Vercel deployment.", label: "Vercel deployment" };
 }
-/** Any JSON: the trigger's own paths, then the usual names; shown whole when they find no text. */
 function readGeneric(body, settings) {
     const at = (path) => path === null ? undefined : pick(body, path);
     let identity = null;
     if (settings.idField !== null) {
         const read = identityOf(at(settings.idField));
-        // A configured identity that can't be used makes nothing: it never falls back to some other identity.
         if (!read.ok)
             return { kind: "skip", why: read.why };
         identity = read.id;
@@ -129,10 +102,7 @@ function readGeneric(body, settings) {
         title: typeof title === "string" && title.trim() !== "" ? title : settings.title,
         description: `From a webhook:\n\n${typeof details === "string" ? details : JSON.stringify(body, null, 2)}`.slice(0, 4000), label: "Webhook" };
 }
-/** Whether each provider's reader has read a real, captured delivery (test/fixtures/webhooks/*.captured.json), or only
- * its sender's documented examples so far: the panel says which until a captured one is in the suite. */
 export const READER_CAPTURED = { sentry: false, vercel: false };
-/** What a proven delivery says, by its sender's reader. */
 export function readDelivery(body, settings) {
     return settings.sender === "sentry" ? readSentry(body, settings) : settings.sender === "vercel" ? readVercel(body, settings) : readGeneric(body, settings);
 }

package/dist/webhook-signing.js

@@ -1,20 +1,13 @@
-/**
- * How a webhook proves who sent it (docs/plans/webhook-tasks.md §1). Each sender's check runs over the raw bytes,
- * before anything is parsed; a security header sent more than once, or not at all, is refused. Nothing here reads or
- * writes the store: the caller passes the current generation's secret, and a refusal writes nothing.
- */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { WEBHOOK_SENDERS } from "./contracts/flow.js";
 export { WEBHOOK_SENDERS };
 export const SENDER_WORDS = {
     none: "Unsigned", standard: "Standard Webhooks", "github-style": "GitHub-style signature", sentry: "Sentry", vercel: "Vercel",
 };
-/** A Standard Webhooks timestamp may be this far from now, either way. */
 export const STANDARD_TOLERANCE_MS = 5 * 60_000;
 const HEX = (bytes) => new RegExp(`^[0-9a-f]{${bytes * 2}}$`);
 const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
 const HIDDEN = /[\u0000-\u001f\u007f]/;
-/** Exactly one value for a security header, or why not. */
 function single(headers, name) {
     const values = headers[name] ?? [];
     if (values.length === 0)
@@ -26,7 +19,6 @@ function single(headers, name) {
 function same(expected, given) {
     return expected.length === given.length && timingSafeEqual(expected, given);
 }
-/** A `whsec_` secret's key bytes, or null when it isn't one. */
 export function standardKey(secret) {
     if (!secret.startsWith("whsec_"))
         return null;
@@ -36,7 +28,6 @@ export function standardKey(secret) {
     const key = Buffer.from(encoded, "base64");
     return key.length >= 24 && key.length <= 64 ? key : null;
 }
-/** Whether a delivery was signed with this secret by this sender. `none` proves nothing and is never passed here. */
 export function proveDelivery(sender, secret, headers, body, now) {
     switch (sender) {
         case "github-style": {
@@ -77,13 +68,11 @@ export function proveDelivery(sender, secret, headers, body, now) {
             const idText = id.value, stampText = stamp.value, signatureText = signature.value;
             if (idText === "" || idText.length > 200 || HIDDEN.test(idText))
                 return { ok: false, said: "The webhook-id header isn't usable." };
-            // Unix seconds, as an integer: milliseconds, decimals and signs are refused, not guessed at.
             if (!/^\d{1,11}$/.test(stampText))
                 return { ok: false, said: "The webhook-timestamp isn't Unix seconds." };
             if (Math.abs(now.getTime() - Number(stampText) * 1000) > STANDARD_TOLERANCE_MS)
                 return { ok: false, said: "Too old, or from the future." };
             const expected = createHmac("sha256", key).update(Buffer.concat([Buffer.from(`${idText}.${stampText}.`, "utf8"), body])).digest();
-            // Any well-formed v1 entry may match; a malformed entry is passed over, and none well-formed is a refusal.
             let wellFormed = 0;
             for (const entry of signatureText.split(" ")) {
                 if (!entry.startsWith("v1,"))
@@ -102,7 +91,6 @@ export function proveDelivery(sender, secret, headers, body, now) {
         }
     }
 }
-/** Whether a pasted secret has its sender's shape (Sentry's and Vercel's come from them; the others can be made here). */
 export function secretShapeOk(sender, secret) {
     switch (sender) {
         case "sentry": return /^[0-9a-fA-F]{32,128}$/.test(secret);
@@ -111,9 +99,7 @@ export function secretShapeOk(sender, secret) {
         case "github-style": return /^[\x21-\x7e]{16,200}$/.test(secret);
     }
 }
-/** A new secret for a sender Toolroll can make one for; Sentry's and Vercel's are pasted from them. */
 export function makeSecret(sender) {
     return sender === "standard" ? `whsec_${randomBytes(32).toString("base64")}` : randomBytes(32).toString("hex");
 }
-/** Whether Toolroll makes this sender's secret (and shows it once), rather than asking for the sender's own. */
 export const makesSecret = (sender) => sender === "standard" || sender === "github-style";

package/dist/webhooks.js

@@ -3,13 +3,6 @@ import { notificationClaimHeld, claimNotifications, finalizeNotification, notifi
 import { loadDiscordCredentials } from "./discord-api.js";
 import { loadTeamsCredentials } from "./teams-api.js";
 import { loadSlackCredentials } from "./slack-api.js";
-/**
- * Messaging settings beside the database: which connected chat service
- * receives alerts (the primary), and the console URL that links in chats
- * and phone pushes open. The chat services themselves — Telegram and the
- * interactive Slack, Discord and Teams adapters — keep their own
- * credentials; this file only reads whether they are configured.
- */
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { envValue } from "./names.js";
@@ -24,9 +17,6 @@ export function isMessagingChannel(value) {
     return MESSAGING_CHANNELS.includes(value);
 }
 export function saveConsoleUrl(dir, url) {
-    // Parsed, not pattern-matched (attended review, finding 11): the stored
-    // value becomes every deep link's base, so userinfo, queries, and
-    // fragments are refused rather than smuggled into each link.
     let parsed;
     try {
         parsed = new URL(url.trim());
@@ -57,7 +47,6 @@ function readTrimmed(path) {
         return null;
     }
 }
-/** Every configured mirror. Environment wins over files, like the bot token. */
 export function loadWebhookTargets(env, dir) {
     const targets = [];
     const slack = envValue(env, "SLACK_WEBHOOK") ?? readTrimmed(join(dir, FILE_OF.slack));
@@ -68,7 +57,6 @@ export function loadWebhookTargets(env, dir) {
         targets.push({ kind: "discord", url: discord });
     return targets;
 }
-/** The operator's explicit choice of which service carries the pages. */
 export function savePrimary(dir, channel) {
     writeFileSync(join(dir, PRIMARY_FILE), `${channel}\n`, { mode: 0o600 });
 }
@@ -76,14 +64,6 @@ export function loadPrimary(env, dir) {
     const configured = envValue(env, "MESSAGING_PRIMARY") ?? readTrimmed(join(dir, PRIMARY_FILE));
     return configured !== undefined && configured !== null && isMessagingChannel(configured) ? configured : null;
 }
-/**
- * Which service actually carries the pages, and whether that was chosen or
- * merely fell out of what happens to be configured. Explicit choice wins
- * WHEN its channel is actually configured (a primary pointing at nothing
- * falls through rather than silencing every page); otherwise Telegram if
- * present (it can hold buttons), else the first other connected service. `implicit` is the flag
- * every status surface uses to say "you have several — pick one".
- */
 export function effectivePrimary(env, dir, telegramConfigured) {
     const targets = loadWebhookTargets(env, dir);
     const warning = targets.length ? { legacyWarning: LEGACY_WEBHOOK_WARNING } : {};
@@ -107,7 +87,6 @@ export function loadConsoleUrl(env, dir) {
     const configured = envValue(env, "CONSOLE_URL") ?? readTrimmed(join(dir, CONSOLE_FILE));
     return configured === undefined || configured === null || configured === "" ? null : configured.replace(/\/+$/, "");
 }
-/** Where `up` last served its console, kept beside the database so `onboard` names the same address (operate.ts). */
 export const UP_CONSOLE_FILE = "up-console.json";
 export function readUpConsoleUrl(dir) {
     try {
@@ -118,8 +97,6 @@ export function readUpConsoleUrl(dir) {
         return null;
     }
 }
-/** This machine's own console, where `up` last served it: only a plain http address on a loopback name (127.0.0.1,
- * localhost, ::1), never a host guessed from it; null otherwise. */
 export function localConsoleUrl(dir) {
     const served = readUpConsoleUrl(dir);
     if (served === null)
@@ -132,20 +109,10 @@ export function localConsoleUrl(dir) {
         return null;
     }
 }
-/** A dotted IPv4 that names this machine or no machine: loopback, unspecified. */
 function isLocalIpv4(address) {
     return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(address) || address === "0.0.0.0";
 }
-/**
- * Names a browser cannot leave this machine with: never a phone destination.
- * The URL parser hands back a canonical hostname, so an IPv6 literal arrives
- * compressed — `::1`, `::`, and an embedded IPv4 as two hex groups
- * (`::ffff:7f00:1` is 127.0.0.1 mapped; `::7f00:1` the deprecated
- * compatible form) — and those groups are decoded and judged as the IPv4
- * they carry.
- */
 function isLoopbackHost(hostname) {
-    // A DNS root dot changes the spelling, not the destination (localhost.).
     const host = hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
     if (host === "localhost" || host.endsWith(".localhost") || host === "::1" || host === "::" || isLocalIpv4(host))
         return true;
@@ -155,17 +122,6 @@ function isLoopbackHost(hostname) {
     const high = parseInt(embedded[1], 16), low = parseInt(embedded[2], 16);
     return isLocalIpv4(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
 }
-/**
- * The origin a phone link may open, or null. The SAME console-url setting
- * chat links use — read again on every call, never cached, so a changed or
- * removed setting stops the next link — held to a stricter shape than a
- * desktop link: exactly an https origin (no credentials, path, query,
- * fragment), not loopback, and, when the console this process co-hosts
- * states its own `--public-url`, exactly that origin. A model, a Host
- * header or a proposal field never supplies it, and nothing here probes
- * the address: a valid shape is a place to send a person, not a promise
- * that it answers.
- */
 export function phoneOrigin(env, dir, options = {}) {
     const configured = loadConsoleUrl(env, dir);
     if (configured === null)
@@ -196,21 +152,14 @@ export function phoneOrigin(env, dir, options = {}) {
     }
     return parsed.origin;
 }
-/** Where in the console this notification wants a person. */
 export function linkFor(consoleUrl, notification) {
     if (consoleUrl === null)
         return null;
     const decision = /^decision:(\d+)$/.exec(notification.dedupeKey);
     if (decision !== null)
         return `${consoleUrl}/d/${decision[1]}`;
-    // Everything else that wants a person is triaged where acting lives.
     return `${consoleUrl}/next`;
 }
-/**
- * One notification, one platform. The payloads are the simplest thing each
- * platform documents; the console link is the call to action, because the
- * message is a mirror and the UI is the instrument.
- */
 export async function postWebhook(target, notification, link, fetcher = fetch) {
     const body = target.kind === "slack"
         ? {
@@ -235,7 +184,6 @@ export async function postWebhook(target, notification, link, fetcher = fetch) {
             signal: AbortSignal.timeout(POST_TIMEOUT_MS),
         });
         if (!response.ok) {
-            // Status only — the URL is a credential and never rides an error.
             return { ok: false, error: `${target.kind} answered ${response.status}` };
         }
         return { ok: true };
@@ -244,11 +192,9 @@ export async function postWebhook(target, notification, link, fetcher = fetch) {
         return { ok: false, error: `${target.kind} delivery failed` };
     }
 }
-/** Only the chosen service sends; an interactive adapter suppresses its old mirror. */
 export function activeWebhookTargets(env, dir, channel) {
     return loadWebhookTargets(env, dir).filter(one => one.kind === channel && (one.kind === "slack" ? loadSlackCredentials(dir) === null : loadDiscordCredentials(dir) === null));
 }
-/** Each destination owns its claim and receipt; a successful one never hides another's retry. */
 export async function webhookPass(store, options) {
     const clock = options.clock ?? (() => new Date()), owner = options.owner ?? `webhooks-${randomUUID()}`;
     const report = { sent: 0, problems: [] };

package/dist/welcome-facts.js

@@ -1,11 +1,3 @@
-/**
- * The welcome's facts read from this computer, for the screens that are not the console: `toolroll welcome` and the
- * terminal UI's Setup screen. The console's /welcome reads the same facts from its runtime (server/welcome.ts); both
- * go through first-run.ts's one model (welcomeModel), so the three steps say the same thing everywhere.
- *
- * Reads only: the project registry beside the database, the store, and each agent CLI's own sign-in check (no model,
- * nothing spent).
- */
 import { basename, dirname, join } from "node:path";
 import { resolvePhaseAgent } from "./agentconfig.js";
 import { builderReadyFor, firstRunBuilderRepo } from "./dispatch.js";
@@ -13,7 +5,6 @@ import { SAMPLE_FIRST_TASKS, SAMPLE_PROJECT_NAME, GENERIC_FIRST_TASKS, welcomeMo
 import { createConnectionChecker } from "./provider-connection.js";
 import { loadProjectRegistry } from "./repos.js";
 const AGENT_OF = { "claude-subscription": "claude", "codex-subscription": "codex" };
-/** The welcome model for this computer now. `check`: the agent sign-in check (tests pass their own). */
 export async function welcomeHere(store, databaseFile, now, options = {}) {
     const registry = await loadProjectRegistry(join(dirname(databaseFile), "repos.json"));
     const repos = "error" in registry ? [] : registry.repos;
@@ -27,7 +18,6 @@ export async function welcomeHere(store, databaseFile, now, options = {}) {
         agents: { claude: states[0] ?? null, codex: states[1] ?? null },
         inUse: AGENT_OF[store.getChatConfig()?.provider ?? ""] ?? null,
         buildsOn: build.ok ? build.spec.provider : null,
-        // Choosing the agent is the console's act ("Use this one"); these screens show the step and its sign-in command.
         canChoose: false,
         projects: repos.map(path => ({ name: basename(path), path })),
         projectRoot: root,
@@ -39,7 +29,6 @@ export async function welcomeHere(store, databaseFile, now, options = {}) {
     return { model, projects: repos };
 }
 export const WELCOME_STEPS = ["agent", "project", "task"];
-/** One step as lines for a terminal: its number and name, Done or what to do next, in plain words. */
 export function welcomeStepLines(model, key) {
     const mark = (done) => (done ? "Done" : "To do");
     const lines = [];
@@ -57,14 +46,14 @@ export function welcomeStepLines(model, key) {
         for (const one of model.project.projects.slice(0, 3))
             lines.push(`   ${one.name}  ${one.path}`);
         if (model.project.projects.length === 0)
-            lines.push("   Add a git repository: run `toolroll repos add <folder>`, or `toolroll open --web` and choose one.");
+            lines.push("   Add a git repository: run `toolroll repos add <folder>`, or `toolroll --web` and choose one.");
         else if (model.project.notTakingWork)
             lines.push("   Tasks can't start yet: nothing on this computer is taking work. Run `toolroll`.");
     }
     else {
         lines.push(`3. First task · ${mark(model.task.done)}`);
         if (model.task.done)
-            lines.push("   Filed. Its plan waits for your approval.");
+            lines.push(model.agent.done || model.agent.checking ? "   Filed. Its plan waits for your approval." : "   Filed. It starts by itself once an agent is signed in (step 1).");
         else if (!model.task.open)
             lines.push("   Add a project first.");
         else
@@ -73,7 +62,6 @@ export function welcomeStepLines(model, key) {
     }
     return lines;
 }
-/** The welcome as lines for a terminal: how many steps are left, then each step. */
 export function welcomeLines(model) {
     return [model.left === 0 ? "Setup is done." : `${model.left} ${model.left === 1 ? "step" : "steps"} left.`, "", ...WELCOME_STEPS.flatMap(key => welcomeStepLines(model, key))];
 }

package/dist/when-html.js

@@ -1,14 +1,6 @@
-/**
- * A time a person reads. A desk shows the full stamp, as before; a phone (760px and narrower) shows the short
- * one — "16:39" today, "Yesterday 16:39", "Sep 28" otherwise — and the full stamp stays in the title. Stamps are
- * UTC to the minute, so the server counts in UTC; in the browser `localizeTimes` rewords each of these with the same
- * formatter in the viewer's own zone, as the React views do. The CSS that picks one lives in the shared page
- * stylesheet (`.so-when-*` in serve.ts).
- */
 import { html } from "./html.js";
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 const DAY_MS = 86_400_000;
-/** One `Intl.DateTimeFormat` per zone: building one is the slow part, and every time on a page shares a few zones. */
 const formats = new Map();
 function formatIn(zone) {
     let format = formats.get(zone);
@@ -18,7 +10,6 @@ function formatIn(zone) {
     }
     return format;
 }
-/** A stamp's calendar day, clock and month in a time zone ("UTC" on the server, the viewer's own zone in a browser). */
 function partsIn(at, zone) {
     const read = (z) => Object.fromEntries(formatIn(z).formatToParts(at).map(part => [part.type, part.value]));
     let parts;
@@ -31,7 +22,6 @@ function partsIn(at, zone) {
     return { year: Number(parts["year"]), month: Number(parts["month"]), day: Number(parts["day"]), clock: `${parts["hour"]}:${parts["minute"]}` };
 }
 const dayNumber = (p) => Math.floor(Date.UTC(p.year, p.month - 1, p.day) / DAY_MS);
-/** The viewer's own time zone (a browser's); UTC where there is none to read. */
 export function viewerZone() {
     try {
         return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
@@ -40,9 +30,6 @@ export function viewerZone() {
         return "UTC";
     }
 }
-/** The one formatter for a time a person reads, on every surface: "16:39" today, "Yesterday 16:39" /
- * "Tomorrow 16:39" beside it, "Sep 28" otherwise ("Sep 28 2025" in another year), counted in `zone`. With `clock`,
- * a date further out keeps its time of day too ("Sep 28 16:39"), for deadlines and histories where the hour matters. */
 export function shortWhen(iso, now = new Date(), zone = "UTC", clock = false) {
     const at = new Date(iso);
     if (Number.isNaN(at.getTime()))
@@ -58,15 +45,12 @@ export function shortWhen(iso, now = new Date(), zone = "UTC", clock = false) {
     const date = `${MONTHS[then.month - 1]} ${then.day}`;
     return `${then.year === today.year ? date : `${date} ${then.year}`}${clock ? ` ${then.clock}` : ""}`;
 }
-/** A flow card's deadline in the viewer's zone, always with its time of day: "No reply by 16:30" today,
- * "No reply by Tomorrow 16:30", "Moves on Oct 2 16:30" further out (a label's trailing " at" reads wrong before a date). */
 export function deadlineWords(deadline, now = new Date(), zone = viewerZone()) {
     if (Number.isNaN(new Date(deadline.at).getTime()))
         return deadline.label;
     const words = shortWhen(deadline.at, now, zone, true);
     return /^(?:\d|Tomorrow|Yesterday)/.test(words) ? `${deadline.label} ${words}` : `${deadline.label.replace(/ at$/, "")} ${words}`;
 }
-/** How long ago, in one short mark: "now", "4m", "2h", "3d". A future stamp reads "now"; an unreadable one, "". */
 export function shortAge(iso, now = new Date()) {
     const at = new Date(iso).getTime();
     if (Number.isNaN(at))
@@ -79,7 +63,6 @@ export function shortAge(iso, now = new Date()) {
     const hours = Math.floor(minutes / 60);
     return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
 }
-/** The exact minute in `zone` ("2026-09-30 16:39", with " UTC" when it is UTC): a time's title, one hover away. */
 export function fullWhen(iso, zone = "UTC") {
     const at = new Date(iso);
     if (Number.isNaN(at.getTime()))
@@ -87,11 +70,6 @@ export function fullWhen(iso, zone = "UTC") {
     const p = partsIn(at, zone);
     return `${p.year}-${String(p.month).padStart(2, "0")}-${String(p.day).padStart(2, "0")} ${p.clock}${zone === "UTC" ? " UTC" : ""}`;
 }
-/** Every server-rendered stamp (`whenHtml`'s `<time data-when>`) inside `root`, reworded by the one formatter in the
- * viewer's zone: the same words on a desk and a phone, the exact minute in the title. An exact stamp
- * (`exactWhenHtml`'s `data-when="exact"`, the ledger's seconds) keeps its seconds, in the viewer's zone, and its
- * ISO title. The server's UTC words stay only without script. Times React writes and relative ages ("3 min ago")
- * carry no `data-when` and are never touched. */
 export function localizeTimes(root, now = new Date(), zone = viewerZone()) {
     root.querySelectorAll("time[data-when][datetime]").forEach(node => {
         const iso = node.getAttribute("datetime") ?? "";
@@ -110,7 +88,6 @@ export function localizeTimes(root, now = new Date(), zone = viewerZone()) {
             node.textContent = words;
     });
 }
-/** The exact second in `zone` ("2026-09-30 16:39:12", with " UTC" when it is UTC): an audit record's stamp. */
 export function exactWhen(iso, zone = "UTC") {
     const at = new Date(iso);
     if (Number.isNaN(at.getTime()))
@@ -119,17 +96,13 @@ export function exactWhen(iso, zone = "UTC") {
     const minute = fullWhen(iso, zone);
     return zone === "UTC" ? minute.replace(/ UTC$/, `:${seconds} UTC`) : `${minute}:${seconds}`;
 }
-/** The `<time>` for an exact stamp: its seconds in UTC words on the server, the viewer's zone in a browser. */
 export function exactWhenHtml(iso) {
     return html `<time data-when="exact" datetime="${iso}" title="${iso}">${exactWhen(iso)}</time>`;
 }
-/** The `<time>` for a stamp: `full` is the words a desk shows ("2026-09-30 16:39 UTC"). Empty for no stamp. */
 export function whenHtml(iso, full, now = new Date()) {
     if (iso === null || iso === "")
         return html ``;
     return html `<time data-when datetime="${iso}" title="${full}"><span class="so-when-full">${full}</span><span class="so-when-short">${shortWhen(iso, now)}</span></time>`;
 }
-/** "2026-09-30 16:39 UTC" — the desk's words for a stamp. */
 export const utcMinute = (iso) => `${iso.slice(0, 16).replace("T", " ")} UTC`;
-/** Both the desk and phone forms of a UTC stamp. */
 export const whenUtc = (iso, now = new Date()) => iso === null || iso === "" ? html `` : whenHtml(iso, utcMinute(iso), now);