humanish 0.107.0 → 0.109.0

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

@@ -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
+    /** 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 study 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.
+// server and point the study'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,15 +131,15 @@ 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)" : ""}`,
-        `  GET  /inbox/for/... <- assigned participant inbox (linked by the lab)`,
+        `  GET  /inbox/for/... <- assigned participant inbox (linked by the study)`,
         `  GET  /deliveries    <- humanish drains this${options.token ? " (bearer token required)" : ""}`,
         `  GET  /health        <- readiness marker humanish probes before a run`,
         ``,
-        `Declare it in the lab:`,
+        `Declare it in the study:`,
         `  comms:`,
         `    email:`,
         `      external:`,
@@ -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.d.ts

@@ -16,5 +16,5 @@ export interface CommsSetupResult {
 }
 /** Offline and non-mutating. Unsafe storage is an error, never an empty configuration. */
 export declare function readCommsConnections(cwd: string): Promise<CommsConnections>;
-/** Add one exact profile. No lab mutation, network, provider resources or credential values. */
+/** Add one exact profile. No study mutation, network, provider resources or credential values. */
 export declare function saveCommsConnection(cwd: string, name?: string, apiKeyEnv?: string): Promise<CommsSetupResult>;

package/dist/comms/connections.js

@@ -65,7 +65,7 @@ export async function readCommsConnections(cwd) {
         throw new Error("Invalid connection configuration.");
     }
 }
-/** Add one exact profile. No lab mutation, network, provider resources or credential values. */
+/** Add one exact profile. No study mutation, network, provider resources or credential values. */
 export async function saveCommsConnection(cwd, name = DEFAULT_COMMS_PROVIDER.id, apiKeyEnv = DEFAULT_COMMS_PROVIDER.keyEnv) {
     const provider = DEFAULT_COMMS_PROVIDER.id;
     try {
@@ -94,7 +94,7 @@ export async function saveCommsConnection(cwd, name = DEFAULT_COMMS_PROVIDER.id,
             await writeContainedOutputFile(root, "comms.yaml", stringify(config), "utf8");
             return {
                 ok: true,
-                message: "Connection saved for this project. Select it in a supported lab to use fresh real inboxes.",
+                message: "Connection saved for this project. Select it in a supported study to use fresh real inboxes.",
             };
         }
         finally {

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

@@ -1,4 +1,4 @@
-import type { LabCommsEmail, LabCommsExternal } from "../lab/types.js";
+import type { StudyCommsEmail, StudyCommsExternal } from "../study/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
@@ -6,8 +6,8 @@ import type { PreparedRunArtifactPaths } from "../run/paths.js";
  * 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;
+/** The catch token the run sends: the value of `authTokenEnv`, when the study names one. */
+export declare function catchTokenOf(external: StudyCommsExternal, 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
@@ -15,8 +15,8 @@ export declare function catchTokenOf(external: LabCommsExternal, env: Record<str
  * throws: the run continues without comms evidence.
  */
 export declare function collectExternalCommsEvidence(args: {
-    external: LabCommsExternal;
-    email: LabCommsEmail;
+    external: StudyCommsExternal;
+    email: StudyCommsEmail;
     env: Record<string, string | undefined>;
     runPaths: PreparedRunArtifactPaths;
     /** The run's known secret values. The route may add to it until the drain runs. */

package/dist/comms/external-evidence.js

@@ -4,10 +4,11 @@
 // 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 { addressedRecipients } from "../study/parse/comms.js";
 import { writeContainedOutputFile } from "../run/contained-output.js";
 import { FakeInbox } from "./fake-inbox.js";
 import { collectExternalCommsThread } from "./sandbox-catch.js";
+import { plural } from "../run/text.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.
@@ -33,7 +34,7 @@ export function catchTokenRefusal(token) {
         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. */
+/** The catch token the run sends: the value of `authTokenEnv`, when the study names one. */
 export function catchTokenOf(external, env) {
     return external.authTokenEnv === undefined ? undefined : env[external.authTokenEnv];
 }
@@ -73,13 +74,13 @@ export async function collectExternalCommsEvidence(args) {
         if (collected.captured > 0) {
             return {
                 warnings: scrubbed([
-                    `Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`,
+                    `The email catch captured ${plural(collected.captured, "email send")}, 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([
-                `Comms catch captured ZERO email sends — your 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.`,
+                `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.`,
             ]),
         };
     }

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,11 +21,11 @@ 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 study-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
-     * address supersedes it (the lab's declaration wins). Idempotent: re-declaring the same address
+     * address supersedes it (the study's declaration wins). Idempotent: re-declaring the same address
      * returns the existing inbox without clearing it.
      */
     provisionAddress(participantId: string, value: string): Promise<CommsAddress>;

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,11 +60,11 @@ 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 study-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
-     * address supersedes it (the lab's declaration wins). Idempotent: re-declaring the same address
+     * address supersedes it (the study's declaration wins). Idempotent: re-declaring the same address
      * returns the existing inbox without clearing it.
      */
     async provisionAddress(participantId, value) {

package/dist/comms/receiving-render.d.ts

@@ -7,7 +7,7 @@ export declare const MAX_RECEIVING_MESSAGES = 100;
 export declare const MAX_SURFACE_FILES: number;
 /** A local message or lease id: safe as one path segment. */
 export declare const LOCAL_ID: RegExp;
-/** Totals describe the whole snapshot (not increments). Register secrets BEFORE publishing files. */
+/** Totals describe the whole snapshot (not increments). Register secrets before publishing files. */
 export declare function renderReceivingInbox(options: {
     address: string;
     messages: ParticipantEmail[];

package/dist/comms/receiving-render.js

@@ -91,7 +91,7 @@ function safeStyle(style) {
     }
     return declarations.join(";");
 }
-/** Totals describe the whole snapshot (not increments). Register secrets BEFORE publishing files. */
+/** Totals describe the whole snapshot (not increments). Register secrets before publishing files. */
 export function renderReceivingInbox(options) {
     if (!options.address ||
         options.address.length > 512 ||
@@ -358,7 +358,7 @@ function renderImage(m, attrs) {
     const alt = attrs.get("alt")?.slice(0, 1024) || "Email image";
     if (!data) {
         m.assets++;
-        return `<span class="blocked-image" role="img" aria-label="${esc(alt)}">${esc(alt)} — Image unavailable. Remote images are blocked; embedded images must be supported and within the size limit.</span>`;
+        return `<span class="blocked-image" role="img" aria-label="${esc(alt)}">${esc(alt)}: image unavailable. Remote images are blocked, and an embedded image must use a supported format and fit the size limit.</span>`;
     }
     // srcset, background and all network-bearing image attributes are deliberately absent.
     const width = /^\d{1,3}$/.test(attrs.get("width") ?? "") ? ` width="${attrs.get("width")}"` : "";

package/dist/comms/receiving-runtime.d.ts

@@ -1,4 +1,4 @@
-import type { LabConfig } from "../lab/types.js";
+import type { StudyConfig } from "../study/types.js";
 import { type CommsConnection } from "./connections.js";
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 import type { ReceivingAdapter } from "./receiving-types.js";
@@ -14,9 +14,9 @@ export declare function resolveReceivingConnection(cwd: string, name: string, en
     apiKey: string;
     adapter: ReceivingAdapter;
 }>;
-/** What receiving reads from a lab: its email declaration and the subject env it guards. */
+/** What receiving reads from a study: its email declaration and the subject env it guards. */
 export interface ReceivingSource {
-    readonly comms?: LabConfig["comms"];
+    readonly comms?: StudyConfig["comms"];
     readonly subject: {
         readonly env?: readonly string[];
         readonly envValues?: Readonly<Record<string, string>>;
@@ -32,7 +32,7 @@ export declare function prepareReceivingRun(args: {
     registerSecrets(values: string[]): void;
 }): Promise<import("./receiving.js").CommsReceivingRun | undefined>;
 /** The restriction survives restarts and screenshot redaction; it is not a claim of local processing. */
-export declare function receivingPublication(config: Pick<LabConfig, "comms">, dryRun: boolean): {
+export declare function receivingPublication(config: Pick<StudyConfig, "comms">, dryRun: boolean): {
     publication: {
         restrictions: ["real-communications"];
     };

package/dist/comms/sandbox-catch-script.d.ts

@@ -1,15 +1,15 @@
 /**
- * The self-contained in-sandbox capture server — a plain **python3** script (stdlib only), because the
- * stock E2B desktop template ships python3 but NOT node, and the co-located catcher must run in a
+ * The self-contained in-sandbox capture server: a plain **python3** script (stdlib only), because the
+ * stock E2B desktop template ships python3 but not node, and the co-located catcher must run in a
  * runtime the sandbox guarantees (the precedented choice: LocalStack is a python catcher the app points
  * at; you pick the runtime the environment has). It runs on the sandbox's own python3, imports nothing
- * from humanish. DELIBERATELY dumb: it records each POST verbatim as an NDJSON line `{t, path, body}`
- * and returns a plausible provider success — all normalization/profile parsing happens host-side on the
+ * from humanish. Deliberately dumb: it records each POST verbatim as an NDJSON line `{t, path, body}`
+ * and returns a plausible provider success; all normalization/profile parsing happens host-side on the
  * drained lines, so the typed, tested profiles stay in one place. It also serves the host-rendered inbox
  * surface statically at /inbox + /api/inbox (with a script-forbidding CSP). argv: <port> <deliveriesFile>
- * <servedDir> [inboxPort]. The capture listener binds 127.0.0.1 (loopback) — the app under test reaches
+ * <servedDir> [inboxPort]. The capture listener binds 127.0.0.1 (loopback): the app under test reaches
  * it in-sandbox, nothing on the internet can inject a fake send. When an [inboxPort] is given (the
- * shared-world route, where the persona lives in a DIFFERENT sandbox), it ALSO starts a READ-ONLY inbox
+ * shared-world route, where the persona lives in a different sandbox), it also starts a read-only inbox
  * listener on 0.0.0.0:<inboxPort> so getHost can proxy the persona's inbox reads to it; that listener
  * serves GET only (POST → 405). The CUA same-sandbox route omits it and stays loopback-only.
  */