humanish 0.106.1 → 0.108.0

package/dist/comms/lease-store.js

@@ -4,6 +4,7 @@ import { constants } from "node:fs";
 import { lstat, mkdir, open, readdir, realpath, rename, unlink } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import path from "node:path";
+import { isRecord } from "../run/type-guards.js";
 import { isReceivingProviderId } from "./providers.js";
 const SCHEMA = "humanish.comms-lease-journal.v1";
 const MAX_BYTES = 1_048_576;
@@ -30,7 +31,6 @@ function fail(code = "authority_unavailable") {
 }
 const digest = (value) => createHash("sha256").update(value).digest("hex");
 const clone = (value) => structuredClone(value);
-const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const safeString = (value, max = 512) => typeof value === "string" &&
     value.length > 0 &&
     value.length <= max &&
@@ -45,14 +45,14 @@ export function sameReceivingIdentity(a, b) {
         a.scopeId === b.scopeId);
 }
 export function validReceivingIdentity(value) {
-    return (plain(value) &&
+    return (isRecord(value) &&
         isReceivingProviderId(value.provider) &&
         safeString(value.accountId) &&
         ["organization", "pod", "inbox"].includes(String(value.scopeType)) &&
         safeString(value.scopeId));
 }
 export function validReceivingLease(value, clientId) {
-    return (plain(value) &&
+    return (isRecord(value) &&
         value.clientId === clientId &&
         safeString(value.resourceId) &&
         safeString(value.address, 320) &&
@@ -79,7 +79,7 @@ function ownerLiveness(owner) {
     }
 }
 function validateOwner(value) {
-    return (plain(value) &&
+    return (isRecord(value) &&
         Number.isSafeInteger(value.pid) &&
         value.pid > 0 &&
         safeString(value.host) &&
@@ -95,9 +95,9 @@ function parseJournal(text) {
     catch {
         return fail();
     }
-    if (!plain(value) ||
+    if (!isRecord(value) ||
         value.schema !== SCHEMA ||
-        !plain(value.project) ||
+        !isRecord(value.project) ||
         !safeString(value.project.path, 4096) ||
         !path.isAbsolute(value.project.path) ||
         !Number.isSafeInteger(value.project.dev) ||
@@ -123,7 +123,7 @@ function parseJournal(text) {
     const leaseIds = new Set();
     const resources = new Set();
     for (const item of value.leases) {
-        if (!plain(item) ||
+        if (!isRecord(item) ||
             typeof item.participantId !== "string" ||
             !LOCAL_ID.test(item.participantId) ||
             participants.has(item.participantId) ||

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/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.
  */

package/dist/comms/sandbox-catch-script.js

@@ -2,17 +2,17 @@
 // directory) and runs with python3. sandbox-catch.ts deploys and drains it; this module holds only
 // its source, so the Python can be read on its own.
 /**
- * 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.
  */

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

@@ -11,8 +11,8 @@ export declare const DEFAULT_SANDBOX_CATCH_PORT = 8025;
 export interface DeployCommsCatchOptions {
     /** Fixed loopback port the catch listens on (default 8025). Must be free inside the sandbox. */
     port?: number;
-    /** Optional SECOND fixed port for a READ-ONLY inbox listener bound to 0.0.0.0, so a persona in a
-     *  DIFFERENT sandbox can reach the inbox surface via getHost (the shared-world route). Omit on the
+    /** Optional second fixed port for a read-only inbox listener bound to 0.0.0.0, so a persona in a
+     *  different sandbox can reach the inbox surface via getHost (the shared-world route). Omit on the
      *  CUA same-sandbox route (loopback is enough). Must differ from `port` and be free in the sandbox. */
     inboxPort?: number;
     /** In-sandbox working dir for the script + NDJSON (default /tmp/humanish-comms). */
@@ -30,20 +30,20 @@ export interface DeployCommsCatchOptions {
 }
 export interface DeployedCommsCatch {
     port: number;
-    /** Inject THIS as the app's email-API base URL (e.g. RESEND_API_URL) — the sandbox's own loopback. */
+    /** Inject this as the app's email-API base URL (e.g. RESEND_API_URL): the sandbox's own loopback. */
     baseUrl: string;
     deliveriesPath: string;
-    /** In-sandbox dir the HOST renders the persona-facing inbox-surface files into (via writeInboxSurface);
+    /** In-sandbox dir the host renders the persona-facing inbox-surface files into (via writeInboxSurface);
      *  the catch serves them at /inbox and /api/inbox. */
     surfaceDir: string;
-    /** The 0.0.0.0 read-only inbox port, when one was requested — getHost-expose THIS to give a
+    /** The 0.0.0.0 read-only inbox port, when one was requested; getHost-expose this to give a
      *  different-sandbox persona a reachable inbox URL. Absent on the loopback-only (CUA) route. */
     inboxPort?: number;
     /** The loopback SMTP port, when one was requested. Point the app's SMTP host/port env at
-     *  127.0.0.1 and THIS. */
+     *  127.0.0.1 and this port. */
     smtpPort?: number;
-    /** Whether the catch's /health returned OUR service marker within the readiness budget. Callers MUST
-     *  treat `ready === false` as fatal (do not inject baseUrl into a dead catch — the app's sends would
+    /** Whether the catch's /health returned humanish's service marker within the readiness budget. Callers must
+     *  treat `ready === false` as fatal (do not inject baseUrl into a dead catch: the app's sends would
      *  silently fail with nothing captured). */
     ready: boolean;
 }
@@ -54,8 +54,8 @@ export interface RawCapturedSend {
     t: number;
 }
 /**
- * Write + launch the in-sandbox catch (detached), then probe it ready. Call AFTER the subject sandbox
- * is created and BEFORE the subject app's serve.start, so the base URL resolves at the app's boot.
+ * Write + launch the in-sandbox catch (detached), then probe it ready. Call after the subject sandbox
+ * is created and before the subject app's serve.start, so the base URL resolves at the app's boot.
  */
 export declare function deployCommsCatch(shell: Shell, options?: DeployCommsCatchOptions): Promise<DeployedCommsCatch>;
 /**
@@ -67,26 +67,25 @@ export declare function drainCommsCatch(shell: Shell, deployed: Pick<DeployedCom
     cursor: number;
 }>;
 /**
- * Parse an append-only deliveries NDJSON blob into raw sends. Split out of drainCommsCatch (#380) so
- * the SAME parsing serves a sandbox we own (read over the E2B command channel) and a catch running on
+ * Parse an append-only deliveries NDJSON blob into raw sends. Split out of drainCommsCatch so
+ * the same parsing serves a sandbox we own (read over the E2B command channel) and a catch running on
  * a plane we do not own (read from the local filesystem by `humanish comms catch`).
  *
- * A file that does not end in a newline may have a PARTIAL last line — a reader racing an append of a
+ * A file that does not end in a newline may have a partial last line when a reader races an append of a
  * large body. Dropping it is never lossy: the script only ever emits valid JSON lines, so an incomplete
  * line re-reads complete on the next pass.
  */
 export declare function parseDeliveriesNdjson(text: string): RawCapturedSend[];
 /**
- * The distinct `to` addresses the captured mail was actually sent to, parsed with the SAME profiles
+ * The distinct `to` addresses the captured mail was actually sent to, parsed with the same profiles
  * that route it. A lab run knows its recipients from the declared roster; a standalone catch does not,
- * so it discovers them from the mail itself — otherwise an operator who forgot to name an address gets
- * a technically-healthy catch rendering an empty inbox forever, which is the false-green class #380 is
- * about.
+ * so it discovers them from the mail itself. Otherwise an operator who forgot to name an address gets
+ * a technically-healthy catch rendering an empty inbox forever: a false green.
  */
 export declare function capturedRecipientAddresses(sends: readonly RawCapturedSend[], profiles?: EmailSendProfile[]): string[];
 /**
- * Route raw sends into a FRESH FakeInbox and return the deduped, delivery-ordered messages. Split out
- * of refreshInboxSurface (#380) so the rendering pipeline is shared by every transport; the freshness
+ * Route raw sends into a fresh FakeInbox and return the deduped, delivery-ordered messages. Split out
+ * of refreshInboxSurface so the rendering pipeline is shared by every transport; the freshness
  * is what makes a full rebuild idempotent (a send is never routed twice, so no duplicate emails).
  */
 export declare function inboxMessagesFrom(sends: readonly RawCapturedSend[], recipients: readonly InboxSurfaceRecipient[]): Promise<CommsMessage[]>;
@@ -98,7 +97,7 @@ export declare function inboxMessagesFrom(sends: readonly RawCapturedSend[], rec
 export declare function routeCapturedSends(sends: RawCapturedSend[], channel: CommsChannel, profiles?: EmailSendProfile[]): Promise<number>;
 /** Outcome of a whole-run comms collect. `artifact` is present only when captured mail matched a
  *  provisioned inbox; `captured > 0 && artifact === undefined` means the app sent mail to an address
- *  no declared recipient covers (captured but unevidenced) — the caller should surface that, not drop
+ *  no declared recipient covers (captured but unevidenced); the caller should surface that, not drop
  *  it silently. */
 export interface CommsThreadCollection {
     artifact?: CommsThreadArtifact;
@@ -110,8 +109,8 @@ export interface CommsThreadCollection {
 /**
  * End of a run's comms funnel: drain everything the in-sandbox catch captured, route it into the
  * host `channel`, poll the provisioned `inboxes`, and build the digest-only thread artifact. The
- * `artifact` is omitted when nothing was captured OR nothing matched a provisioned inbox (an empty
- * file would be a false claim of a delivered thread) — but `captured`/`matched` are always reported so
+ * `artifact` is omitted when nothing was captured or nothing matched a provisioned inbox (an empty
+ * file would be a false claim of a delivered thread), but `captured`/`matched` are always reported so
  * the caller can warn on captured-but-unevidenced mail rather than lose it silently. Composes the
  * tested drain/route/build pieces so the CUA and shared-world routes collect evidence identically. The
  * full NDJSON is drained from cursor 0 (a whole-run collect), so it is idempotent to call once at
@@ -126,9 +125,9 @@ export declare function collectCommsThread(args: {
     profiles?: EmailSendProfile[];
     requestTimeoutMs?: number;
 }): Promise<CommsThreadCollection>;
-/** An adopter-hosted catch: humanish never provisioned it, so it is addressed over HTTP (#328). */
+/** An adopter-hosted catch: humanish never provisioned it, so it is addressed over HTTP. */
 export interface ExternalCommsCatch {
-    /** Base URL of the catch the ADOPTER runs (its POST capture endpoint and GET /deliveries). */
+    /** Base URL of the catch the adopter runs (its POST capture endpoint and GET /deliveries). */
     catchBaseUrl: string;
     /** Base URL the persona opens to read mail. Defaults to catchBaseUrl (same server serves /inbox). */
     inboxBaseUrl?: string;
@@ -138,8 +137,8 @@ export interface ExternalCommsCatch {
 /** The URL a persona is told to open to read its mail on an adopter-hosted plane. */
 export declare function externalInboxUrl(external: ExternalCommsCatch): string;
 /**
- * Probe an adopter-hosted catch the way the in-sandbox one is probed: assert OUR service marker in
- * /health, not merely any 2xx — an adopter's reverse proxy or a captive portal will happily return
+ * Probe an adopter-hosted catch the way the in-sandbox one is probed: assert humanish's service marker in
+ * /health, not merely any 2xx: an adopter's reverse proxy or a captive portal will happily return
  * 200 for anything, and a comms lab whose catch is not actually there collects nothing while
  * looking fine. Fail-closed callers treat `false` as a hard stop before spending on a run.
  */
@@ -161,8 +160,8 @@ export declare function drainExternalCommsCatch(external: ExternalCommsCatch, cu
 }>;
 /**
  * The adopter-hosted analogue of collectCommsThread: drain over HTTP, route into the host inbox bus,
- * and build the SAME digest-only humanish.comms-thread.v1 artifact. Evidence shape does not depend
- * on who hosted the catch — only the transport does.
+ * and build the same digest-only humanish.comms-thread.v1 artifact. Evidence shape does not depend
+ * on who hosted the catch; only the transport does.
  */
 export declare function collectExternalCommsThread(args: {
     external: ExternalCommsCatch;
@@ -173,10 +172,10 @@ export declare function collectExternalCommsThread(args: {
     fetchFn?: typeof fetch;
 }): Promise<CommsThreadCollection>;
 /**
- * Render the persona-facing inbox surface (host-side, typed — see capture-surface.ts) and write the files
- * into the sandbox's served dir, so the catch serves a LIVE inbox the persona opens and clicks. Creates
+ * Render the persona-facing inbox surface (host-side, typed; see capture-surface.ts) and write the files
+ * into the sandbox's served dir, so the catch serves a live inbox the persona opens and clicks. Creates
  * the nested route dirs first; overwrites idempotently, so call it whenever the message set changes
- * (e.g. after a mid-run drain). Returns the number of files written. Raw content is written INTO the
+ * (e.g. after a mid-run drain). Returns the number of files written. Raw content is written into the
  * sandbox only (runtime-only, served to the in-sandbox browser); nothing here persists to the bundle.
  */
 export declare function writeInboxSurface(shell: Shell, surfaceDir: string, messages: CommsMessage[], options?: InboxRenderOptions & {
@@ -189,17 +188,17 @@ export interface InboxSurfaceRecipient {
     address: string;
 }
 /**
- * One mid-run inbox-surface refresh cycle: FULL rebuild from the append-only NDJSON (drain from cursor 0)
- * into a FRESH FakeInbox each call, provisioning the declared `recipients`, then (re)render the surface
+ * One mid-run inbox-surface refresh cycle: full rebuild from the append-only NDJSON (drain from cursor 0)
+ * into a fresh FakeInbox each call, provisioning the declared `recipients`, then (re)render the surface
  * so the persona sees new mail while the session is live. Returns the total captured-send `count` + whether
  * it rendered.
  *
- * The full rebuild is deliberate — it is IDEMPOTENT and RETRY-SAFE: a transient writeInboxSurface failure
- * PROPAGATES (the caller retries next tick without advancing its `sinceCount`), and because each rebuild
+ * The full rebuild is deliberate because it is idempotent and retry-safe: a transient writeInboxSurface failure
+ * propagates (the caller retries next tick without advancing its `sinceCount`), and because each rebuild
  * starts from a clean channel, a send is never routed twice, so the persona never sees duplicate emails.
- * Pass `sinceCount` (the last SUCCESSFULLY-rendered send count) to skip the (N-file) render when nothing
+ * Pass `sinceCount` (the last successfully-rendered send count) to skip the (N-file) render when nothing
  * new has arrived. This is independent of the teardown collectCommsThread drain (its own fresh channel,
- * also cursor 0) — no evidence is lost or altered. The NDJSON is small for a run, so re-reading it is cheap.
+ * also cursor 0), so no evidence is lost or altered. The NDJSON is small for a run, so re-reading it is cheap.
  */
 export declare function refreshInboxSurface(args: {
     shell: Shell;

package/dist/comms/sandbox-catch.js

@@ -1,10 +1,10 @@
-// Deploy the vendor-neutral email catch INSIDE the subject E2B sandbox and bridge captured sends back
-// to the host bus (#297 config-block core). The host `startEmailCatchServer` binds the HOST's loopback,
-// which a sandboxed app cannot reach — `127.0.0.1:PORT` from the app is the SANDBOX's loopback. So the
+// Deploy the vendor-neutral email catch inside the subject E2B sandbox and bridge captured sends back
+// to the host bus. The host `startEmailCatchServer` binds the host's loopback,
+// which a sandboxed app cannot reach: `127.0.0.1:PORT` from the app is the sandbox's loopback. So the
 // listener must live in the sandbox: we write a tiny self-contained capture server (no deps, no host
 // import) into the sandbox, launch it detached (the same substrate that serves the subject app), and
 // each poll `cat` its append-only NDJSON of captured sends back to the host, where the real profiles
-// parse them and route into the CommsChannel. A FIXED loopback port is chosen up front so the app's
+// parse them and route into the CommsChannel. A fixed loopback port is chosen up front so the app's
 // injected base-URL env (`http://127.0.0.1:<port>`) is known before the sandbox is created.
 import { FakeInbox } from "./fake-inbox.js";
 import { buildCommsThreadArtifact } from "./thread-evidence.js";
@@ -18,7 +18,7 @@ import { runOrThrow, shellQuote } from "../substrates/shell.js";
  *  unlikely to collide with a subject app; override via config if it does. */
 export const DEFAULT_SANDBOX_CATCH_PORT = 8025;
 const DEFAULT_CATCH_DIR = "/tmp/humanish-comms";
-/** Readiness probe that asserts OUR service marker in the /health body (not merely any 2xx) — so a
+/** Readiness probe that asserts humanish's service marker in the /health body (a bare 2xx is not enough), so a
  *  process squatting on the fixed port cannot produce a false "ready" while the app's sends bypass us. */
 async function catchHealthy(shell, port, options) {
     const now = options.now ?? Date.now;
@@ -38,8 +38,8 @@ async function catchHealthy(shell, port, options) {
     }
 }
 /**
- * Write + launch the in-sandbox catch (detached), then probe it ready. Call AFTER the subject sandbox
- * is created and BEFORE the subject app's serve.start, so the base URL resolves at the app's boot.
+ * Write + launch the in-sandbox catch (detached), then probe it ready. Call after the subject sandbox
+ * is created and before the subject app's serve.start, so the base URL resolves at the app's boot.
  */
 export async function deployCommsCatch(shell, options = {}) {
     // Validate the port to an integer before it reaches the shell command (defense-in-depth: a future
@@ -93,8 +93,8 @@ export async function deployCommsCatch(shell, options = {}) {
         ...options.timers,
     };
     const ready = await catchHealthy(shell, port, probe);
-    // Confirm the read-only inbox listener bound too (loopback-reachable at its own port), when requested —
-    // else a getHost-exposed inbox would 502. Fail closed by folding it into `ready`.
+    // Confirm the read-only inbox listener bound too (loopback-reachable at its own port), when requested.
+    // Without it a getHost-exposed inbox would 502. Fail closed by folding it into `ready`.
     const inboxReady = inboxPort === undefined ? true : await catchHealthy(shell, inboxPort, probe);
     return {
         port,
@@ -114,8 +114,8 @@ export async function drainCommsCatch(shell, deployed, cursor = 0, requestTimeou
     const result = await runOrThrow(shell, `cat ${shellQuote(deployed.deliveriesPath)} 2>/dev/null || true`, { requestTimeoutMs });
     const stdout = result.stdout;
     let lines = stdout.split("\n").filter((line) => line.trim().length > 0);
-    // If the file doesn't end in a newline, the last line may be a PARTIAL append (the host `cat` raced
-    // an in-sandbox append of a large body). Drop it and don't advance the cursor past it — it re-reads
+    // If the file doesn't end in a newline, the last line may be a partial append (the host `cat` raced
+    // an in-sandbox append of a large body). Drop it and don't advance the cursor past it; it re-reads
     // complete on the next poll, so a captured send is never lost to the race (the script only ever emits
     // valid JSON, so an incomplete line is the only cause of a parse miss).
     if (!stdout.endsWith("\n") && lines.length > 0)
@@ -139,11 +139,11 @@ export async function drainCommsCatch(shell, deployed, cursor = 0, requestTimeou
     return { sends, cursor: lines.length };
 }
 /**
- * Parse an append-only deliveries NDJSON blob into raw sends. Split out of drainCommsCatch (#380) so
- * the SAME parsing serves a sandbox we own (read over the E2B command channel) and a catch running on
+ * Parse an append-only deliveries NDJSON blob into raw sends. Split out of drainCommsCatch so
+ * the same parsing serves a sandbox we own (read over the E2B command channel) and a catch running on
  * a plane we do not own (read from the local filesystem by `humanish comms catch`).
  *
- * A file that does not end in a newline may have a PARTIAL last line — a reader racing an append of a
+ * A file that does not end in a newline may have a partial last line when a reader races an append of a
  * large body. Dropping it is never lossy: the script only ever emits valid JSON lines, so an incomplete
  * line re-reads complete on the next pass.
  */
@@ -170,11 +170,10 @@ export function parseDeliveriesNdjson(text) {
     return sends;
 }
 /**
- * The distinct `to` addresses the captured mail was actually sent to, parsed with the SAME profiles
+ * The distinct `to` addresses the captured mail was actually sent to, parsed with the same profiles
  * that route it. A lab run knows its recipients from the declared roster; a standalone catch does not,
- * so it discovers them from the mail itself — otherwise an operator who forgot to name an address gets
- * a technically-healthy catch rendering an empty inbox forever, which is the false-green class #380 is
- * about.
+ * so it discovers them from the mail itself. Otherwise an operator who forgot to name an address gets
+ * a technically-healthy catch rendering an empty inbox forever: a false green.
  */
 export function capturedRecipientAddresses(sends, profiles = DEFAULT_EMAIL_PROFILES) {
     const addresses = new Set();
@@ -199,8 +198,8 @@ export function capturedRecipientAddresses(sends, profiles = DEFAULT_EMAIL_PROFI
     return [...addresses];
 }
 /**
- * Route raw sends into a FRESH FakeInbox and return the deduped, delivery-ordered messages. Split out
- * of refreshInboxSurface (#380) so the rendering pipeline is shared by every transport; the freshness
+ * Route raw sends into a fresh FakeInbox and return the deduped, delivery-ordered messages. Split out
+ * of refreshInboxSurface so the rendering pipeline is shared by every transport; the freshness
  * is what makes a full rebuild idempotent (a send is never routed twice, so no duplicate emails).
  */
 export async function inboxMessagesFrom(sends, recipients) {
@@ -256,8 +255,8 @@ export async function routeCapturedSends(sends, channel, profiles = DEFAULT_EMAI
 /**
  * End of a run's comms funnel: drain everything the in-sandbox catch captured, route it into the
  * host `channel`, poll the provisioned `inboxes`, and build the digest-only thread artifact. The
- * `artifact` is omitted when nothing was captured OR nothing matched a provisioned inbox (an empty
- * file would be a false claim of a delivered thread) — but `captured`/`matched` are always reported so
+ * `artifact` is omitted when nothing was captured or nothing matched a provisioned inbox (an empty
+ * file would be a false claim of a delivered thread), but `captured`/`matched` are always reported so
  * the caller can warn on captured-but-unevidenced mail rather than lose it silently. Composes the
  * tested drain/route/build pieces so the CUA and shared-world routes collect evidence identically. The
  * full NDJSON is drained from cursor 0 (a whole-run collect), so it is idempotent to call once at
@@ -297,8 +296,8 @@ export function externalInboxUrl(external) {
     return `${baseOf(external.inboxBaseUrl ?? external.catchBaseUrl)}/inbox`;
 }
 /**
- * Probe an adopter-hosted catch the way the in-sandbox one is probed: assert OUR service marker in
- * /health, not merely any 2xx — an adopter's reverse proxy or a captive portal will happily return
+ * Probe an adopter-hosted catch the way the in-sandbox one is probed: assert humanish's service marker in
+ * /health, not merely any 2xx: an adopter's reverse proxy or a captive portal will happily return
  * 200 for anything, and a comms lab whose catch is not actually there collects nothing while
  * looking fine. Fail-closed callers treat `false` as a hard stop before spending on a run.
  */
@@ -365,8 +364,8 @@ export async function drainExternalCommsCatch(external, cursor = 0, options = {}
 }
 /**
  * The adopter-hosted analogue of collectCommsThread: drain over HTTP, route into the host inbox bus,
- * and build the SAME digest-only humanish.comms-thread.v1 artifact. Evidence shape does not depend
- * on who hosted the catch — only the transport does.
+ * and build the same digest-only humanish.comms-thread.v1 artifact. Evidence shape does not depend
+ * on who hosted the catch; only the transport does.
  */
 export async function collectExternalCommsThread(args) {
     const drainOptions = {
@@ -397,10 +396,10 @@ export async function collectExternalCommsThread(args) {
     };
 }
 /**
- * Render the persona-facing inbox surface (host-side, typed — see capture-surface.ts) and write the files
- * into the sandbox's served dir, so the catch serves a LIVE inbox the persona opens and clicks. Creates
+ * Render the persona-facing inbox surface (host-side, typed; see capture-surface.ts) and write the files
+ * into the sandbox's served dir, so the catch serves a live inbox the persona opens and clicks. Creates
  * the nested route dirs first; overwrites idempotently, so call it whenever the message set changes
- * (e.g. after a mid-run drain). Returns the number of files written. Raw content is written INTO the
+ * (e.g. after a mid-run drain). Returns the number of files written. Raw content is written into the
  * sandbox only (runtime-only, served to the in-sandbox browser); nothing here persists to the bundle.
  */
 export async function writeInboxSurface(shell, surfaceDir, messages, options = {}) {
@@ -421,17 +420,17 @@ export async function writeInboxSurface(shell, surfaceDir, messages, options = {
     return files.length;
 }
 /**
- * One mid-run inbox-surface refresh cycle: FULL rebuild from the append-only NDJSON (drain from cursor 0)
- * into a FRESH FakeInbox each call, provisioning the declared `recipients`, then (re)render the surface
+ * One mid-run inbox-surface refresh cycle: full rebuild from the append-only NDJSON (drain from cursor 0)
+ * into a fresh FakeInbox each call, provisioning the declared `recipients`, then (re)render the surface
  * so the persona sees new mail while the session is live. Returns the total captured-send `count` + whether
  * it rendered.
  *
- * The full rebuild is deliberate — it is IDEMPOTENT and RETRY-SAFE: a transient writeInboxSurface failure
- * PROPAGATES (the caller retries next tick without advancing its `sinceCount`), and because each rebuild
+ * The full rebuild is deliberate because it is idempotent and retry-safe: a transient writeInboxSurface failure
+ * propagates (the caller retries next tick without advancing its `sinceCount`), and because each rebuild
  * starts from a clean channel, a send is never routed twice, so the persona never sees duplicate emails.
- * Pass `sinceCount` (the last SUCCESSFULLY-rendered send count) to skip the (N-file) render when nothing
+ * Pass `sinceCount` (the last successfully-rendered send count) to skip the (N-file) render when nothing
  * new has arrived. This is independent of the teardown collectCommsThread drain (its own fresh channel,
- * also cursor 0) — no evidence is lost or altered. The NDJSON is small for a run, so re-reading it is cheap.
+ * also cursor 0), so no evidence is lost or altered. The NDJSON is small for a run, so re-reading it is cheap.
  */
 export async function refreshInboxSurface(args) {
     const { sends } = await drainCommsCatch(args.shell, args.deployed, 0, args.requestTimeoutMs);

package/dist/comms/setup.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, open, unlink } from "node:fs/promises";
 import path from "node:path";
-import { parse, stringify } from "yaml";
+import { parse, parseDocument } from "yaml";
 import { COMMS_CONFIG_PATH, readCommsConnections } from "./connections.js";
 import { discoverProviderKeys, listUserKeys, probeKeySources, } from "../keys/key-resolution.js";
 import { COMMS_PROVIDERS, commsProviderLabel, DEFAULT_COMMS_PROVIDER, } from "./providers.js";
@@ -11,6 +11,9 @@ import { RECEIVING_SCOPE_UNSUPPORTED } from "./receiving-types.js";
 import { parseLabConfig } from "../lab/config.js";
 import { resolveLabManifest } from "../lab/discover.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { otherStudyFiles } from "../study/files.js";
+import { convertStudyText, isStudyV3 } from "../study/convert.js";
+import { isNodeError } from "../run/type-guards.js";
 export async function checkCommsConnection(args) {
     const base = {
         schema: "humanish.comms-check.v1",
@@ -122,7 +125,8 @@ export async function configureCommsLab(args) {
         const bytes = await readContainedRegularFile(root, rel);
         if (!bytes || bytes.length > 1024 * 1024)
             return { ...base, message: "The lab is missing or too large." };
-        const raw = parse(bytes.toString("utf8"));
+        const text = bytes.toString("utf8");
+        const raw = parse(text);
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
             return { ...base, message: "The lab must be a mapping." };
         const lab = raw;
@@ -132,8 +136,20 @@ export async function configureCommsLab(args) {
                 ...base,
                 message: "This lab uses local capture. Preserve it or make a separate lab before selecting real email.",
             };
-        lab.comms = { ...existing, email: { ...existing?.email, connection: args.connection } };
-        const validated = parseLabConfig(lab);
+        // The copy is a v3 study. A v2 source is converted first, so the copy keeps its comments.
+        let studyText = text;
+        if (!isStudyV3(raw)) {
+            const converted = convertStudyText(text, args.cwd);
+            if (!converted.ok)
+                return {
+                    ...base,
+                    message: `This lab could not be converted to a v3 study: ${converted.reason}`,
+                };
+            studyText = converted.conversion.text;
+        }
+        const study = parseDocument(studyText);
+        study.setIn(["comms", "email", "connection"], args.connection);
+        const validated = parseLabConfig(study.toJS());
         if (!validated.ok)
             return {
                 ...base,
@@ -145,12 +161,30 @@ export async function configureCommsLab(args) {
             .replace(/-receiving$/, "") + "-receiving.yaml";
         if (!/^[A-Za-z0-9_][A-Za-z0-9._-]{0,110}\.yaml$/.test(filename))
             return { ...base, message: "Use a simple lab filename before configuring email." };
-        const destination = `.humanish/local/labs/${filename}`;
-        if (rel === destination)
+        const destination = `.humanish/local/studies/${filename}`;
+        if (path.basename(rel) === filename)
             return {
                 ...base,
                 message: "This is already the local receiving copy. Select its original lab to configure a separate copy, or edit this manifest directly.",
             };
+        // A second file with this name in another study directory would make discovery refuse both.
+        const stem = filename.replace(/\.yaml$/, "");
+        const others = await otherStudyFiles(stem, 
+        // Any directory entry counts, a dangling symbolic link included: discovery would see it too.
+        async (candidate) => {
+            try {
+                await lstat(path.join(root.requestedPath, candidate));
+                return true;
+            }
+            catch (error) {
+                return !(isNodeError(error) && error.code === "ENOENT");
+            }
+        }, destination);
+        if (others.length > 0)
+            return {
+                ...base,
+                message: `${others.join(", ")} already uses the name ${stem}. Rename or remove it before configuring email, so \`run ${stem}\` reads one file.`,
+            };
         let prior;
         try {
             prior = await readContainedRegularFile(root, destination);
@@ -158,7 +192,7 @@ export async function configureCommsLab(args) {
         catch {
             return { ...base, message: "The local destination could not be read safely." };
         }
-        const content = stringify(lab);
+        const content = String(study);
         const token = createHash("sha256")
             .update(bytes)
             .update("\0")
@@ -183,7 +217,7 @@ export async function configureCommsLab(args) {
                 ...base,
                 message: "The lab or destination changed since preview. Preview again before saving.",
             };
-        const directory = await prepareManagedHumanishOutputDirectory(args.cwd, "local", "labs");
+        const directory = await prepareManagedHumanishOutputDirectory(args.cwd, "local", "studies");
         const lockPath = path.join(directory.physicalPath, ".comms-configure.lock");
         const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
         const identity = await lock.stat();

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

@@ -11,7 +11,7 @@ interface CommsThreadEntry {
     subjectDigest?: string;
     /** sha256-16 of each actionable link (high-entropy → non-reversible). */
     linkDigests: string[];
-    /** COUNT ONLY — a short OTP's digest is reversible, so the code itself never lands here. */
+    /** Count only: a short OTP's digest is reversible, so the code itself never lands here. */
     codeCount: number;
     sentAt: number;
     deliveredAt: number;

package/dist/comms/thread-evidence.js

@@ -1,14 +1,14 @@
-// Digest-only evidence for a captured comms thread (#297). Proves "the verification mail arrived and
-// the persona could act on it" WITHOUT persisting raw PHI. Written as an adapter-artifact
+// Digest-only evidence for a captured comms thread. Proves "the verification mail arrived and
+// the persona could act on it" without persisting raw PHI. Written as an adapter-artifact
 // (humanish.comms-thread.v1), so it inherits the bundle's existence-verify + public-safety scan.
 //
 // Digest discipline (deliberate, see below): addresses + links are digested (high entropy → the digest
-// is not reversible). The subject is DIGESTED too, not stored as text — redactText only scrubs
-// secret-SHAPED tokens/paths, not free-form PII (the #108 gap), so a subject like "results for <name>"
+// is not reversible). The subject is digested too instead of stored as text, because redactText only scrubs
+// secret-shaped tokens/paths, not free-form PII, so a subject like "results for <name>"
 // would pass through verbatim; a sha256-16 keeps a PII subject non-reversible while still letting you
-// correlate identical subjects. OTP CODES are a COUNT ONLY, never digested — a sha256 of a 6-digit code
+// correlate identical subjects. OTP codes are a count only, never digested: a sha256 of a 6-digit code
 // has ~10^6 preimages and is trivially brute-forced back to the code, so a "code digest" would leak it.
-// Net: NO raw address/subject/link/OTP text ever lands in the artifact. Same caution as the lobby code.
+// Net: no raw address/subject/link/OTP text ever lands in the artifact. Same caution as the lobby code.
 import { digestText } from "../evidence/redaction.js";
 const COMMS_THREAD_SCHEMA = "humanish.comms-thread.v1";
 /** Project polled inbox messages into the digest-only thread artifact. Pure; the caller writes it into