humanish 0.106.1 → 0.108.0

package/dist/comms/capture-surface.d.ts

@@ -1,7 +1,7 @@
 import type { ReceivingSurfaceFile } from "./receiving-types.js";
 import type { CommsMessage } from "./types.js";
 /** [fromOrigin, toOrigin] pairs: rewrite a link/href whose origin is the app's in-sandbox origin into a
- *  lane-reachable origin, so the persona's browser can actually follow the verify link when it clicks. */
+ *  participant-reachable origin, so the persona's browser can actually follow the verify link when it clicks. */
 export type OriginMap = Array<[string, string]>;
 export interface InboxRenderOptions {
     originMap?: OriginMap;
@@ -13,17 +13,18 @@ export interface InboxRenderOptions {
 export declare function inboxRecipientScope(address: string): string;
 export declare function recipientInboxUrl(inboxUrl: string, address: string): string;
 /** Rewrite a URL's origin per the map (origins are exact strings the harness minted). Leaves
- *  non-matching URLs — including sibling origins sharing a prefix — untouched. */
+ *  non-matching URLs (including sibling origins sharing a prefix) untouched. */
 export declare function rewriteOrigin(url: string, originMap?: OriginMap): string;
 /**
- * Build the [internalOrigin → reachableOrigin] rewrite rows for a run. The app-under-test bakes ITS OWN
+ * Build the [internalOrigin → reachableOrigin] rewrite rows for a run. The app-under-test bakes its own
  * origin into the verify links it emails (usually its loopback serve origin); the persona reaches the
- * app at a possibly-different origin — the same loopback on the CUA route (identity, a no-op), the
- * harness-minted getHost URL on the shared-world route (where the rewrite is REQUIRED). Emits the serve
- * origin plus its loopback aliases at the serve port (127.0.0.1 / localhost / 0.0.0.0) so an app that
- * stamps `localhost` still rewrites, and — because the harness cannot infer an absolute PUBLIC base URL
- * an app was configured with — an operator-declared `linkOrigin` escape hatch, matched first. Origins
- * only (no trailing slash, no path), so replaceOriginBoundary matches on a URL boundary.
+ * app at a possibly-different origin: the same loopback on the computer-use route (identity, a
+ * no-op), the harness-minted getHost URL on the shared-world route (where the rewrite is required).
+ * Emits the serve origin plus its loopback aliases at the serve port (127.0.0.1 / localhost /
+ * 0.0.0.0) so an app that stamps `localhost` still rewrites, and (because the harness cannot infer
+ * an absolute public base URL an app was configured with) an operator-declared `linkOrigin` escape
+ * hatch, matched first. Origins only (no trailing slash, no path), so replaceOriginBoundary matches
+ * on a URL boundary.
  */
 export declare function buildOriginMap(args: {
     internalServeUrl?: string | undefined;
@@ -32,11 +33,11 @@ export declare function buildOriginMap(args: {
 }): OriginMap;
 /** Best-guess primary call-to-action: the first verify/confirm-looking link, else the first link. */
 export declare function pickVerifyUrl(links: string[]): string | undefined;
-/** The inbox LIST page (semantic table; each row links to its message). */
+/** The inbox list page (semantic table; each row links to its message). */
 export declare function renderInboxList(messages: CommsMessage[], options?: InboxRenderOptions): string;
-/** One message, DEFAULT view: the app's real captured email in a minimal high-contrast shell. */
+/** One message, default view: the app's real captured email in a minimal high-contrast shell. */
 export declare function renderInboxMessage(message: CommsMessage, options?: InboxRenderOptions): string;
-/** One message, SYNTHESIZED view: a guaranteed-legible reading pane (big verify button + big OTP). The
+/** One message, synthesized view: a guaranteed-legible reading pane (big verify button + big OTP). The
  *  reliability fallback when the app's real email is a vision minefield; opt-in, never the default. */
 export declare function renderInboxMessageSynth(message: CommsMessage, options?: InboxRenderOptions): string;
 /** JSON projection of one message (the programmatic/CLI actor surface + the reliability backstop). Raw
@@ -46,7 +47,7 @@ export declare function inboxMessageJson(message: CommsMessage, options?: InboxR
  * Build every served file for the inbox surface from the normalized messages. The host writes each to
  * `<servedDir>/<path>`; the in-sandbox catch serves `<servedDir>/<pathname>`, falling back to
  * `<pathname>/index` (so a URL like `/inbox` maps to the `inbox/index` file while `/inbox/{id}` stays a
- * directory) — standard web-server index semantics that avoid a file-vs-directory path collision. The
+ * directory), standard web-server index semantics that avoid a file-vs-directory path collision. The
  * URLs the persona actually sees stay clean (`/inbox`, `/inbox/{id}`, `/inbox/{id}/synth`). Content type
  * is inferred from the `/api/` prefix. Message ids are `comms-NNNN` (never `index`/`latest`), so leaf
  * filenames never collide with an id.

package/dist/comms/capture-surface.js

@@ -1,4 +1,4 @@
-// The inbox surface for captured mail (#297): the pages a computer-use participant opens to read a
+// The inbox surface for captured mail: the pages a computer-use participant opens to read a
 // captured verification email and follow its link. The pages are minimal semantic HTML (native
 // links and tables, black on white, large targets), because vision participants read a simple
 // inbox more reliably than a webmail client. The default view is the app's real captured email,
@@ -27,7 +27,7 @@ function inboxPath(options) {
         : `/inbox/for/${inboxRecipientScope(options.recipient)}`;
 }
 const VERIFY_HINT = /verify|confirm|activate|validate|magic|token|account|sign[\s-]?up/i;
-/** Replace `from` with `to` everywhere it ends on an ORIGIN BOUNDARY — end-of-string or one of the URL
+/** Replace `from` with `to` everywhere it ends on an origin boundary: end-of-string or one of the URL
  *  delimiters `/ ? # " ' <space> > \`. A bare prefix replace would mangle a sibling origin that shares
  *  `from` as a numeric prefix (`:30000` vs `:3000`) or a suffix-domain (`:3000.evil`); the boundary
  *  check prevents that. Works both for a single URL and inside a blob of email HTML. */
@@ -47,7 +47,7 @@ function replaceOriginBoundary(text, from, to) {
     }
 }
 /** Rewrite a URL's origin per the map (origins are exact strings the harness minted). Leaves
- *  non-matching URLs — including sibling origins sharing a prefix — untouched. */
+ *  non-matching URLs (including sibling origins sharing a prefix) untouched. */
 export function rewriteOrigin(url, originMap = []) {
     let out = url;
     for (const [from, to] of originMap)
@@ -75,14 +75,15 @@ function safePort(url) {
     }
 }
 /**
- * Build the [internalOrigin → reachableOrigin] rewrite rows for a run. The app-under-test bakes ITS OWN
+ * Build the [internalOrigin → reachableOrigin] rewrite rows for a run. The app-under-test bakes its own
  * origin into the verify links it emails (usually its loopback serve origin); the persona reaches the
- * app at a possibly-different origin — the same loopback on the CUA route (identity, a no-op), the
- * harness-minted getHost URL on the shared-world route (where the rewrite is REQUIRED). Emits the serve
- * origin plus its loopback aliases at the serve port (127.0.0.1 / localhost / 0.0.0.0) so an app that
- * stamps `localhost` still rewrites, and — because the harness cannot infer an absolute PUBLIC base URL
- * an app was configured with — an operator-declared `linkOrigin` escape hatch, matched first. Origins
- * only (no trailing slash, no path), so replaceOriginBoundary matches on a URL boundary.
+ * app at a possibly-different origin: the same loopback on the computer-use route (identity, a
+ * no-op), the harness-minted getHost URL on the shared-world route (where the rewrite is required).
+ * Emits the serve origin plus its loopback aliases at the serve port (127.0.0.1 / localhost /
+ * 0.0.0.0) so an app that stamps `localhost` still rewrites, and (because the harness cannot infer
+ * an absolute public base URL an app was configured with) an operator-declared `linkOrigin` escape
+ * hatch, matched first. Origins only (no trailing slash, no path), so replaceOriginBoundary matches
+ * on a URL boundary.
  */
 export function buildOriginMap(args) {
     const to = safeOrigin(args.reachableBaseUrl);
@@ -121,7 +122,7 @@ function esc(value) {
         .replace(/>/g, "&gt;")
         .replace(/"/g, "&quot;");
 }
-/** Defense-in-depth stripping before rendering the app's real email HTML. The LOAD-BEARING protection is
+/** Defense-in-depth stripping before rendering the app's real email HTML. The main protection is
  *  the page CSP (`script-src 'none'`, set both as a page() meta and as a catch response header), which is
  *  browser-enforced and neuters inline handlers, `javascript:` URLs, and injected <script> regardless of
  *  what this misses. This strip additionally removes elements CSP does not cover (a redirecting
@@ -133,9 +134,9 @@ function neutralizeEmailHtml(html, originMap) {
         .replace(/<(script|style|iframe|object|embed|svg|math|template)\b[\s\S]*?<\/\1\s*>/gi, "")
         // stray or void dangerous tags, incl. unclosed openers and redirect/reroot tags
         .replace(/<\/?(script|style|iframe|object|embed|svg|math|base|meta|link|form)\b[^>]*>/gi, "")
-        // inline event handlers, whether preceded by whitespace OR a "/" attribute separator
+        // inline event handlers, whether preceded by whitespace or a "/" attribute separator
         .replace(/[\s/]on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, " ")
-        // javascript:/vbscript: in nav/resource attrs — quoted OR unquoted (data: is left for inline images)
+        // javascript:/vbscript: in nav/resource attrs, quoted or unquoted (data: is left for inline images)
         .replace(/(href|src|xlink:href|formaction|action)\s*=\s*(?:"(?:javascript|vbscript):[^"]*"|'(?:javascript|vbscript):[^']*'|(?:javascript|vbscript):[^\s>]*)/gi, '$1="#"');
     // Rewrite the app's origin inside the (now-neutralized) HTML so its own links resolve to a reachable host.
     for (const [from, to] of originMap)
@@ -213,7 +214,7 @@ function renderEmailImages(html, message, originMap) {
             }
         }
         if (!src)
-            return `<span class="email-image-unavailable" role="img" aria-label="${esc(alt || "Email image")}">${esc(alt ? `${alt} — ${unavailable}` : unavailable)}</span>`;
+            return `<span class="email-image-unavailable" role="img" aria-label="${esc(alt || "Email image")}">${esc(alt ? `${alt}: ${unavailable}` : unavailable)}</span>`;
         const sizing = ["width", "height"]
             .map((name) => {
             const value = attributes.get(name);
@@ -241,11 +242,11 @@ const PAGE_CSS = "body{font:16px/1.55 system-ui,-apple-system,Segoe UI,Roboto,sa
     "@media(max-width:560px){.inbox-list thead{display:none}.inbox-list,.inbox-list tbody,.inbox-list tr,.inbox-list td{display:block}" +
     ".inbox-list tr{padding:12px 0;border-bottom:1px solid #ddd}.inbox-list td{padding:3px 0;border:0}" +
     ".inbox-list td:first-child a{display:block;min-height:32px;font-weight:600}.inbox-list td[data-label]::before{content:attr(data-label) ': ';font-size:13px;color:#666}}";
-/** The surface CSP — the browser-enforced, load-bearing protection against the app-authored email running
+/** The surface CSP: the browser-enforced main protection against the app-authored email running
  *  script or hijacking navigation on the surface page. `script-src 'none'` blocks inline handlers,
  *  `javascript:` URLs, and any injected <script>; `object-src`/`frame-src 'none'` block plugins/frames;
  *  `base-uri 'none'` blocks <base> reroot. Images/styles stay permissive so the real email still renders.
- *  Set BOTH as a page() meta (covers direct render use) and as a catch response header (covers serving). */
+ *  Set both as a page() meta (covers direct render use) and as a catch response header (covers serving). */
 const INBOX_SURFACE_CSP = "default-src 'self'; script-src 'none'; object-src 'none'; base-uri 'none'; frame-src 'none'; img-src * data:; style-src 'unsafe-inline'; font-src * data:";
 function page(title, inner) {
     return ('<!doctype html><html lang="en"><head><meta charset="utf-8">' +
@@ -273,7 +274,7 @@ function fmtTime(ms) {
 function toValues(message) {
     return message.to.map((address) => address.value);
 }
-/** The inbox LIST page (semantic table; each row links to its message). */
+/** The inbox list page (semantic table; each row links to its message). */
 export function renderInboxList(messages, options = {}) {
     const base = inboxPath(options);
     const rows = messages
@@ -295,8 +296,8 @@ export function renderInboxList(messages, options = {}) {
         "</td></tr>")
         .join("");
     const body = (options.recipient
-        ? '<div class="bar">Inbox for ' + esc(options.recipient) + " — "
-        : '<div class="bar">Shared operator inbox — all captured recipients — ') +
+        ? '<div class="bar">Inbox for ' + esc(options.recipient) + ": "
+        : '<div class="bar">Shared operator inbox (all captured recipients): ') +
         messages.length +
         " message" +
         (messages.length === 1 ? "" : "s") +
@@ -307,7 +308,7 @@ export function renderInboxList(messages, options = {}) {
         "</tbody></table></main>";
     return page("Inbox", body);
 }
-/** One message, DEFAULT view: the app's real captured email in a minimal high-contrast shell. */
+/** One message, default view: the app's real captured email in a minimal high-contrast shell. */
 export function renderInboxMessage(message, options = {}) {
     const originMap = options.originMap ?? [];
     const base = inboxPath(options);
@@ -336,7 +337,7 @@ export function renderInboxMessage(message, options = {}) {
         "</main>";
     return page(message.subject ?? "Message", body);
 }
-/** One message, SYNTHESIZED view: a guaranteed-legible reading pane (big verify button + big OTP). The
+/** One message, synthesized view: a guaranteed-legible reading pane (big verify button + big OTP). The
  *  reliability fallback when the app's real email is a vision minefield; opt-in, never the default. */
 export function renderInboxMessageSynth(message, options = {}) {
     const originMap = options.originMap ?? [];
@@ -418,7 +419,7 @@ function inboxListJson(messages, options = {}) {
  * Build every served file for the inbox surface from the normalized messages. The host writes each to
  * `<servedDir>/<path>`; the in-sandbox catch serves `<servedDir>/<pathname>`, falling back to
  * `<pathname>/index` (so a URL like `/inbox` maps to the `inbox/index` file while `/inbox/{id}` stays a
- * directory) — standard web-server index semantics that avoid a file-vs-directory path collision. The
+ * directory), standard web-server index semantics that avoid a file-vs-directory path collision. The
  * URLs the persona actually sees stay clean (`/inbox`, `/inbox/{id}`, `/inbox/{id}/synth`). Content type
  * is inferred from the `/api/` prefix. Message ids are `comms-NNNN` (never `index`/`latest`), so leaf
  * filenames never collide with an id.

package/dist/comms/catch-host.d.ts

@@ -9,14 +9,14 @@ export interface CommsCatchHostOptions {
     dir: string;
     /** Bearer token required on GET /deliveries. Strongly recommended when the host is reachable. */
     token?: string;
-    /** SECOND port for the READ-ONLY inbox listener bound to 0.0.0.0, so a persona on another machine
-     *  (or in a per-lane desktop) can reach the inbox. Omit to stay loopback-only. */
+    /** Second port for the read-only inbox listener bound to 0.0.0.0, so a persona on another machine
+     *  (or on a participant's desktop) can reach the inbox. Omit to stay loopback-only. */
     inboxPort?: number;
     /** Optional loopback SMTP listener sharing the HTTP capture and inbox pipeline. */
     smtpPort?: number;
-    /** Restrict the rendered inbox to these addresses. Omit to render whatever the app actually mailed
-     *  — a standalone catch has no lab roster to read recipients from, and an operator who forgets to
-     *  name one should not get a healthy catch that renders an empty inbox forever (#380). */
+    /** Restrict the rendered inbox to these addresses. Omit to render whatever the app actually mailed;
+     *  a standalone catch has no lab roster to read recipients from, and an operator who forgets to
+     *  name one should not get a healthy catch that renders an empty inbox forever. */
     recipients?: string[];
     /** Inbox re-render cadence in ms (test seam). */
     renderIntervalMs?: number;
@@ -24,10 +24,10 @@ export interface CommsCatchHostOptions {
 /**
  * Render the persona-facing inbox surface from the catch's own deliveries file into `surfaceDir`.
  *
- * This is the half that was missing on an adopter-hosted plane (#380). The catch serves /inbox and
- * /api/inbox as STATIC FILES; in-sandbox, humanish-as-host renders those files on a cadence. On a
+ * This is the half that was missing on an adopter-hosted plane. The catch serves /inbox and
+ * /api/inbox as static files; in-sandbox, humanish-as-host renders those files on a cadence. On a
  * plane humanish does not provision there is no such host, so nothing wrote them and every persona
- * that reached /inbox got `message not found` against a catch whose /health was green — the funnel
+ * that reached /inbox got `message not found` against a catch whose /health was green, so the funnel
  * dead-ended at a technically-healthy service.
  *
  * Rebuilding from scratch each pass is deliberate and matches refreshInboxSurface: a fresh channel per

package/dist/comms/catch-host.js

@@ -1,19 +1,19 @@
-// `humanish comms catch` (#328): run the email catch on the OPERATOR's own host.
+// `humanish comms catch`: run the email catch on the operator's own host.
 //
-// Why this exists. The in-sandbox catch only works when humanish provisions the subject itself —
+// Why this exists. The in-sandbox catch only works when humanish provisions the subject itself:
 // it clones the app into a sandbox, injects the email-API base URL at boot, and hosts the catch
-// alongside it. An adopter whose study runs against their OWN deployed environment (an app-url or
+// alongside it. An adopter whose study runs against their own deployed environment (an app-url or
 // operator-provisioned plane) hands humanish a URL instead, so humanish never boots the app and
 // has nowhere to put a catch. Before this, a `comms:` block on that route was warned inert and the
 // personas simply stalled at the verification screen.
 //
 // The fix is to let the adopter host the same catch and declare it (`comms.email.external`).
-// Shipping it as a COMMAND rather than a spec matters: the adopter runs the identical
+// Shipping it as a command rather than a spec matters: the adopter runs the identical
 // implementation humanish deploys in-sandbox, so the capture shape, the inbox surface, and the
 // drain contract cannot drift between the two planes. Point the app's email-API base URL at this
 // server and point the lab's `catchBaseUrl` at it too.
 //
-// Runtime: the catch is a python3 stdlib server with no dependencies (that was the 0.29.0 lesson —
+// Runtime: the catch is a python3 stdlib server with no dependencies (that was the 0.29.0 lesson:
 // a co-located catcher must use a runtime the environment guarantees). This command writes the
 // same script and runs it in the foreground until interrupted.
 import { spawn } from "node:child_process";
@@ -27,10 +27,10 @@ const DEFAULT_RENDER_INTERVAL_MS = 3_000;
 /**
  * Render the persona-facing inbox surface from the catch's own deliveries file into `surfaceDir`.
  *
- * This is the half that was missing on an adopter-hosted plane (#380). The catch serves /inbox and
- * /api/inbox as STATIC FILES; in-sandbox, humanish-as-host renders those files on a cadence. On a
+ * This is the half that was missing on an adopter-hosted plane. The catch serves /inbox and
+ * /api/inbox as static files; in-sandbox, humanish-as-host renders those files on a cadence. On a
  * plane humanish does not provision there is no such host, so nothing wrote them and every persona
- * that reached /inbox got `message not found` against a catch whose /health was green — the funnel
+ * that reached /inbox got `message not found` against a catch whose /health was green, so the funnel
  * dead-ended at a technically-healthy service.
  *
  * Rebuilding from scratch each pass is deliberate and matches refreshInboxSurface: a fresh channel per
@@ -43,7 +43,7 @@ export async function renderInboxSurfaceLocally(args) {
         text = await readFile(args.deliveriesPath, "utf8");
     }
     catch {
-        text = ""; // no mail captured yet — still render, so /inbox answers "No messages yet."
+        text = ""; // no mail captured yet; still render, so /inbox answers "No messages yet."
     }
     const sends = parseDeliveriesNdjson(text);
     const addresses = args.recipients && args.recipients.length > 0
@@ -55,7 +55,7 @@ export async function renderInboxSurfaceLocally(args) {
     }));
     const messages = await inboxMessagesFrom(sends, recipients);
     const files = buildInboxSurface(messages, { recipients: addresses });
-    // A reused catch directory can change recipients or truncate its delivery log. Remove ONLY files
+    // A reused catch directory can change recipients or truncate its delivery log. Remove only files
     // recorded as generated routes, so old recipient/message URLs cannot survive that change.
     const manifestPath = path.join(args.surfaceDir, ".inbox-files.json");
     let previous = [];
@@ -105,8 +105,8 @@ export async function runCommsCatchHost(options, io) {
     const surfaceDir = path.join(dir, "surface");
     await mkdir(surfaceDir, { recursive: true });
     await writeFile(scriptPath, SANDBOX_CATCH_SCRIPT, "utf8");
-    // Render the EMPTY inbox before the server is announced, so /inbox resolves to the "No messages
-    // yet." page from the first request instead of a bare `message not found` (#380) — a persona reads
+    // Render the empty inbox before the server is announced, so /inbox resolves to the "No messages
+    // yet." page from the first request instead of a bare `message not found`, because a persona reads
     // that 404 as a broken product and reports a blocker that is really just an empty mailbox.
     await renderInboxSurfaceLocally({
         deliveriesPath,
@@ -131,7 +131,7 @@ export async function runCommsCatchHost(options, io) {
         ...(inboxPort === undefined
             ? []
             : [
-                `  read-only inbox listener on http://0.0.0.0:${inboxPort} (GET only; expose THIS to personas)`,
+                `  read-only inbox listener on http://0.0.0.0:${inboxPort} (GET only; this is the address to give personas)`,
             ]),
         `  POST /emails        <- point your app's email-API base URL here`,
         `  GET  /inbox         <- shared operator inbox${inboxPort === undefined ? " (loopback only without --inbox-port)" : ""}`,
@@ -149,7 +149,7 @@ export async function runCommsCatchHost(options, io) {
             ? [`        authTokenEnv: HUMANISH_COMMS_TOKEN   # value read at runtime, never persisted`]
             : []),
         ``,
-        `Captured mail is written to ${deliveriesPath}. Raw bodies stay on THIS host: the run bundle`,
+        `Captured mail is written to ${deliveriesPath}. Raw bodies stay on this host: the run bundle`,
         `only ever receives digests (from/to/subject/link) and an OTP count.`,
         ``,
     ].join("\n") + "\n");

package/dist/comms/connections.js

@@ -4,10 +4,10 @@ import path from "node:path";
 import { parse, stringify } from "yaml";
 import { COMMS_PROVIDERS, DEFAULT_COMMS_PROVIDER, isReceivingProviderId, } from "./providers.js";
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { isRecord } from "../run/type-guards.js";
 const COMMS_CONNECTIONS_SCHEMA = "humanish.comms-connections.v1";
 export const COMMS_CONFIG_PATH = ".humanish/local/comms.yaml";
 export { COMMS_PROVIDERS };
-const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const validName = (name) => /^[a-z][a-z0-9-]{0,47}$/.test(name) && name !== "constructor" && name !== "prototype";
 const empty = () => ({ schema: COMMS_CONNECTIONS_SCHEMA, connections: {} });
 async function exists(file) {
@@ -22,16 +22,16 @@ async function exists(file) {
     }
 }
 function parseConnections(raw) {
-    if (!record(raw) ||
+    if (!isRecord(raw) ||
         raw.schema !== COMMS_CONNECTIONS_SCHEMA ||
-        !record(raw.connections) ||
+        !isRecord(raw.connections) ||
         Object.keys(raw).some((key) => key !== "schema" && key !== "connections") ||
         Object.keys(raw.connections).length > 32)
         throw new Error("Invalid connection configuration.");
     const connections = {};
     for (const [name, value] of Object.entries(raw.connections)) {
         if (!validName(name) ||
-            !record(value) ||
+            !isRecord(value) ||
             !isReceivingProviderId(value.provider) ||
             typeof value.apiKeyEnv !== "string" ||
             !/^[A-Z][A-Z0-9_]{0,99}$/.test(value.apiKeyEnv) ||

package/dist/comms/email-catch.d.ts

@@ -10,10 +10,10 @@ interface NormalizedSend {
 }
 /**
  * A provider wire-shape adapter. Vendor-neutral seam: the server owns the HTTP + routing + bus
- * delivery; a profile only knows how ONE provider (or a custom app) shapes its send request.
+ * delivery; a profile only knows how one provider (or a custom app) shapes its send request.
  */
 export interface EmailSendProfile {
-    /** Descriptive name (e.g. "generic", "sendgrid"). Not a dependency — just a label. */
+    /** Descriptive name (e.g. "generic", "sendgrid"). Not a dependency, just a label. */
     name: string;
     /** Request paths (method POST) this profile accepts a send on. */
     sendPaths: string[];
@@ -31,7 +31,7 @@ export interface EmailCatchServer {
     close(): Promise<void>;
 }
 export interface EmailCatchOptions {
-    /** Bind host. Default 127.0.0.1 (loopback ONLY). */
+    /** Bind host. Default 127.0.0.1 (loopback only). */
     host?: string;
     /** Port. Default 0 (ephemeral). */
     port?: number;

package/dist/comms/email-catch.js

@@ -1,9 +1,9 @@
-// A VENDOR-NEUTRAL loopback catch server for email-send APIs (#297). An app hardwired to a hosted
-// email provider is redirected into the fake bus with ONE env var and no code change: point the app's
-// API base URL at this server. The catch does not depend on, or name itself after, any one vendor —
+// A vendor-neutral loopback catch server for email-send APIs. An app hardwired to a hosted
+// email provider is redirected into the fake bus with one env var and no code change: point the app's
+// API base URL at this server. The catch does not depend on, or name itself after, any one vendor:
 // it normalizes each provider's distinct wire shape (Resend's flat body, SendGrid's nested
 // personalizations, Postmark's TitleCase, a custom app's own JSON) to one shape via pluggable
-// PROFILES, and routes the result into a CommsChannel. Resend-compatible and SendGrid-compatible out
+// profiles, and routes the result into a CommsChannel. Resend-compatible and SendGrid-compatible out
 // of the box; extend with a custom profile for anything else. (There is no standardized email-send
 // request shape across vendors, so normalization is by design, not a shortcut.)
 //
@@ -34,8 +34,8 @@ function toAddresses(value) {
     return [];
 }
 // ---------------------------------------------------------------- built-in profiles
-/** The flat-JSON shape: `{ from, to, subject, html, text }`. Matches Resend (POST /emails) AND a
- *  custom app that sends the common shape AND Postmark's TitleCase keys (From/To/HtmlBody/…). */
+/** The flat-JSON shape: `{ from, to, subject, html, text }`. Matches Resend (POST /emails) and a
+ *  custom app that sends the common shape and Postmark's TitleCase keys (From/To/HtmlBody/…). */
 const genericEmailProfile = {
     name: "generic",
     sendPaths: ["/emails", "/emails/batch", "/email", "/email/batch", "/send"],
@@ -125,7 +125,7 @@ function readBody(req, limit) {
         req.on("data", (chunk) => {
             size += chunk.length;
             if (size > limit) {
-                // Reject WITHOUT destroying the socket here: the handler responds 413 cleanly first (a
+                // Reject without destroying the socket here: the handler responds 413 cleanly first (a
                 // write-after-destroy would otherwise reset the connection), then tears the request down.
                 reject(new BodyTooLargeError("request body too large"));
                 return;
@@ -193,7 +193,7 @@ export async function startEmailCatchServer(channel, options = {}) {
         const sends = profile.parse(path, parsed);
         if (sends.length === 0) {
             // A well-formed request that names no deliverable recipient (empty body, or a shape the profile
-            // could not resolve to a send) — return a bad-request rather than a fabricated success id.
+            // could not resolve to a send): return a bad-request rather than a fabricated success id.
             respondJson(res, 422, { error: "no deliverable message in request" });
             return;
         }

package/dist/comms/external-evidence.d.ts

@@ -0,0 +1,27 @@
+import type { LabCommsEmail, LabCommsExternal } from "../lab/types.js";
+import type { PreparedRunArtifactPaths } from "../run/paths.js";
+/**
+ * Why a catch token cannot be used, or undefined when it can. An unset or empty token is none. A
+ * token that is not well-formed Unicode cannot be sent as a header or encoded as a URL, so it is
+ * refused with the short ones.
+ */
+export declare function catchTokenRefusal(token: string | undefined): string | undefined;
+/** The catch token the run sends: the value of `authTokenEnv`, when the lab names one. */
+export declare function catchTokenOf(external: LabCommsExternal, env: Record<string, string | undefined>): string | undefined;
+/**
+ * Drains the catch, routes its sends to the declared recipients' inboxes and writes the thread to
+ * `comms/thread.json`. Returns that path when a message matched, and the warnings to add to the
+ * run, each scrubbed of the run's known secret values and the catch token, then redacted. It never
+ * throws: the run continues without comms evidence.
+ */
+export declare function collectExternalCommsEvidence(args: {
+    external: LabCommsExternal;
+    email: LabCommsEmail;
+    env: Record<string, string | undefined>;
+    runPaths: PreparedRunArtifactPaths;
+    /** The run's known secret values. The route may add to it until the drain runs. */
+    knownSecretValues: readonly string[];
+}): Promise<{
+    path?: string;
+    warnings: string[];
+}>;

package/dist/comms/external-evidence.js

@@ -0,0 +1,93 @@
+// An adopter-hosted catch's thread, collected into a run. The computer-use and shared-world routes
+// both call this, so every warning it returns is scrubbed the same way on both: an error or the
+// catch URL can carry the catch's bearer token or a provisioned value, and neither has a secret's
+// shape for pattern redaction to find.
+import { redactText, toErrorMessage } from "../evidence/redaction.js";
+import { scrubSecretValues } from "../evidence/secret-scrub.js";
+import { addressedRecipients } from "../lab/parse/comms.js";
+import { writeContainedOutputFile } from "../run/contained-output.js";
+import { FakeInbox } from "./fake-inbox.js";
+import { collectExternalCommsThread } from "./sandbox-catch.js";
+/**
+ * The shortest catch bearer token humanish uses. The token guards GET /deliveries on a host the run
+ * reaches over the network, so it must not be guessable: 16 random base64 characters are 96 bits.
+ * The run also scrubs the token from every warning as a literal, and a short token would scrub
+ * ordinary words.
+ */
+const MIN_CATCH_TOKEN_LENGTH = 16;
+/** String.prototype.isWellFormed (ES2024, Node 20+); the ES2023 lib types do not declare it. */
+function isWellFormed(value) {
+    return value.isWellFormed();
+}
+/**
+ * Why a catch token cannot be used, or undefined when it can. An unset or empty token is none. A
+ * token that is not well-formed Unicode cannot be sent as a header or encoded as a URL, so it is
+ * refused with the short ones.
+ */
+export function catchTokenRefusal(token) {
+    if (token === undefined || token.length === 0)
+        return undefined;
+    if (!isWellFormed(token))
+        return "The comms catch token is not well-formed Unicode; use printable ASCII, such as the output of `openssl rand -hex 16`, on the catch and in the run.";
+    if (token.length >= MIN_CATCH_TOKEN_LENGTH)
+        return undefined;
+    return `The comms catch token is ${token.length} characters; it must be at least ${MIN_CATCH_TOKEN_LENGTH}, such as the output of \`openssl rand -hex 16\`, on the catch and in the run.`;
+}
+/** The catch token the run sends: the value of `authTokenEnv`, when the lab names one. */
+export function catchTokenOf(external, env) {
+    return external.authTokenEnv === undefined ? undefined : env[external.authTokenEnv];
+}
+/**
+ * Drains the catch, routes its sends to the declared recipients' inboxes and writes the thread to
+ * `comms/thread.json`. Returns that path when a message matched, and the warnings to add to the
+ * run, each scrubbed of the run's known secret values and the catch token, then redacted. It never
+ * throws: the run continues without comms evidence.
+ */
+export async function collectExternalCommsEvidence(args) {
+    const { external, email, env, runPaths, knownSecretValues } = args;
+    const authToken = catchTokenOf(external, env);
+    // Pattern redaction alone until the literal scrub exists, so a warning built in the catch below
+    // is never unredacted. The scrub is built inside the try, where a failure becomes that warning.
+    let scrubbed = (warnings) => warnings.map(redactText);
+    try {
+        const scrub = scrubSecretValues([
+            ...knownSecretValues,
+            ...(authToken === undefined ? [] : [authToken]),
+        ]);
+        scrubbed = (warnings) => warnings.map((warning) => redactText(scrub(warning)));
+        const channel = new FakeInbox();
+        const inboxes = [];
+        for (const recipient of addressedRecipients(email)) {
+            inboxes.push(await channel.provisionAddress(recipient.participantId, recipient.address));
+        }
+        const collected = await collectExternalCommsThread({
+            external: { ...external, ...(authToken === undefined ? {} : { authToken }) },
+            channel,
+            inboxes,
+        });
+        if (collected.artifact) {
+            const path = "comms/thread.json";
+            await writeContainedOutputFile(runPaths, path, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
+            return { path, warnings: [] };
+        }
+        if (collected.captured > 0) {
+            return {
+                warnings: scrubbed([
+                    `The email catch captured ${collected.captured} email send(s), but none matched a declared recipient inbox, so no email evidence was written. Set comms.email.recipients[].address to the address the app sends to.`,
+                ]),
+            };
+        }
+        return {
+            warnings: scrubbed([
+                `The email catch captured no email sends: the app never delivered mail through the catch at ${external.catchBaseUrl}. Verify the app's email API base URL points at it and that the flow reached an email step.`,
+            ]),
+        };
+    }
+    catch (error) {
+        return {
+            warnings: scrubbed([
+                `Comms evidence collection failed against the adopter-hosted catch (run continues): ${String(toErrorMessage(error))}`,
+            ]),
+        };
+    }
+}

package/dist/comms/extract.js

@@ -48,8 +48,8 @@ export function extractOtpCodes(body) {
             list.push(c);
         }
     };
-    // The alphanumeric alternative requires at least one DIGIT (lookahead) so a labeled prose word like
-    // "your code is INVALID" isn't captured as a code; pure-digit codes (4–8) match directly.
+    // The alphanumeric alternative requires at least one digit (lookahead) so a labeled prose word like
+    // `your code is INVALID` isn't captured as a code; pure-digit codes (4–8) match directly.
     const labeledRe = /(?:one[-\s]?time\s+(?:pass)?code|verification\s+code|security\s+code|access\s+code|login\s+code|confirmation\s+code|passcode|\bOTP\b|\bPIN\b|\bcode\b)\D{0,15}\b([0-9]{4,8}|(?=[A-Za-z0-9]*[0-9])[A-Z0-9]{6,8})\b/gi;
     let m;
     while ((m = labeledRe.exec(text)) !== null)

package/dist/comms/fake-inbox.d.ts

@@ -1,6 +1,6 @@
 import type { CommsAddress, CommsChannel, CommsChannelKind, CommsMessage, InboundRaw, OutboundMessage } from "./types.js";
 export interface FakeInboxOptions {
-    /** "email" (default) or "sms" — the address shape + surface differ; machinery is identical. */
+    /** "email" (default) or "sms": the address shape + surface differ; machinery is identical. */
     channel?: CommsChannelKind;
     /** Email domain for minted addresses. Default example.test, an RFC 6761 reserved, unroutable
      *  test domain. */
@@ -21,7 +21,7 @@ export declare class FakeInbox implements CommsChannel {
     constructor(options?: FakeInboxOptions);
     provision(participantId: string): Promise<CommsAddress>;
     /**
-     * Provision an inbox for `participantId` at an EXPLICIT address (a lab-declared recipient), so
+     * Provision an inbox for `participantId` at an explicit address (a lab-declared recipient), so
      * the app-under-test's send to that literal address resolves in `deliverRaw` (which drops
      * recipients with no provisioned inbox). Declaring the same address intentionally shares its
      * inbox; if `participantId` already held a different auto-generated address, the declared

package/dist/comms/fake-inbox.js

@@ -1,4 +1,4 @@
-// The in-process email/SMS bus (#297): a working, in-memory implementation of the CommsChannel
+// The in-process email/SMS bus: a working, in-memory implementation of the CommsChannel
 // port. Deterministic, offline and free: a message the app under test sends (through an ingress
 // such as the email catch) is routed to the addressed inbox and read back through the same port.
 // Nothing leaves the process. See types.ts for the port and its public-safety notes.
@@ -60,7 +60,7 @@ export class FakeInbox {
         return address;
     }
     /**
-     * Provision an inbox for `participantId` at an EXPLICIT address (a lab-declared recipient), so
+     * Provision an inbox for `participantId` at an explicit address (a lab-declared recipient), so
      * the app-under-test's send to that literal address resolves in `deliverRaw` (which drops
      * recipients with no provisioned inbox). Declaring the same address intentionally shares its
      * inbox; if `participantId` already held a different auto-generated address, the declared