humanish 0.107.0 → 0.108.0

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

package/dist/comms/types.d.ts

@@ -9,7 +9,7 @@ export interface CommsAddress {
     participantId: string;
     /** Runtime-only raw address, e.g. user-07@example.test | +15550137. */
     value: string;
-    /** sha256-short(value) — the only form persisted (redaction.digestText). */
+    /** sha256-short(value): the only form persisted (redaction.digestText). */
     digest: string;
 }
 /** Runtime-only captured raster attachment. Bytes never enter digest-only evidence. */
@@ -22,12 +22,12 @@ export interface CommsInlineImage {
 export interface CommsMessage {
     id: string;
     channel: CommsChannelKind;
-    /** Raw sender — an app-under-test address, or another actor's address. Runtime-only. */
+    /** Raw sender: an app-under-test address, or another actor's address. Runtime-only. */
     from: string;
     /** Resolved recipient inboxes this message was delivered to. */
     to: CommsAddress[];
     subject?: string;
-    /** Runtime-only for real; local-only for fake (never a share path without redaction — #108). */
+    /** Runtime-only for real; local-only for fake (never a share path without redaction). */
     body: string;
     inlineImages?: CommsInlineImage[];
     /** Actionable links extracted from the body (magic-link / invite / reset). Runtime-only. */
@@ -37,7 +37,7 @@ export interface CommsMessage {
     sentAt: number;
     deliveredAt: number;
 }
-/** An actor sending OUT (a reply/compose); recipients are known CommsAddresses. */
+/** An actor sending out (a reply/compose); recipients are known CommsAddresses. */
 export interface OutboundMessage {
     from: CommsAddress;
     to: CommsAddress[];
@@ -45,7 +45,7 @@ export interface OutboundMessage {
     body: string;
     inlineImages?: CommsInlineImage[];
 }
-/** A raw inbound from an INGRESS (the vendor-neutral email catch, an SMTP sink, …): recipients are
+/** A raw inbound from an ingress (the vendor-neutral email catch, an SMTP sink, …): recipients are
  *  raw address strings the bus resolves against its provisioned inboxes. */
 export interface InboundRaw {
     from: string;
@@ -67,7 +67,7 @@ export interface CommsChannel {
     /** Route a composed message from one actor to addressed inboxes. Returns the delivered record. */
     send(message: OutboundMessage): Promise<CommsMessage>;
     /** Route a raw ingress delivery (app-under-test → recipient strings). Returns the messages that
-     *  matched a provisioned inbox (unmatched recipients are dropped — no inbox to deliver to). */
+     *  matched a provisioned inbox (unmatched recipients are dropped; no inbox to deliver to). */
     deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;
     /** New messages delivered to `address` since `since` (exclusive), oldest-first. Drives the surface. */
     poll(address: CommsAddress, since?: number): Promise<CommsMessage[]>;

package/dist/comms/types.js

@@ -1,8 +1,8 @@
-// The addressed message bus for captured mail (#297): the email or SMS a persona receives off the
+// The addressed message bus for captured mail: the email or SMS a persona receives off the
 // app, as a testable surface. One port, addressed by participant, so the inbox surface and the evidence
 // writer read messages without knowing how they were captured.
 //
-// PUBLIC-SAFETY: raw address values, message bodies, links, and codes are RUNTIME-ONLY. Only the
-// address DIGEST (sha256-short, via redaction.digestText) is ever meant to reach a persisted bundle;
+// Public safety: raw address values, message bodies, links, and codes are runtime-only. Only the
+// address digest (sha256-short, via redaction.digestText) is ever meant to reach a persisted bundle;
 // a verification link / OTP has "no secret shape" (like the lobby code) → literal-scrub + digest.
 export {};

package/dist/evidence/frame-signature.d.ts

@@ -1,6 +1,6 @@
 /**
  * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
- * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
+ * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, contrast-normalizes that grid, quantizes each
  * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
  * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
  * The hash cannot be reversed to the image, so exposing it in a trace is public-safe.

package/dist/evidence/frame-signature.js

@@ -6,7 +6,7 @@ const SIGNATURE_FALLBACK = "unreadable";
 const ANCHOR_LEVELS = 16;
 /**
  * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
- * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
+ * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, contrast-normalizes that grid, quantizes each
  * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
  * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
  * The hash cannot be reversed to the image, so exposing it in a trace is public-safe.
@@ -65,9 +65,9 @@ function quantizedGrid(data, srcW, srcH) {
         }
     }
     // Stretch this frame's own range across the full scale before quantizing. Without this a light UI
-    // occupies a sliver at the top of 0..255 and quantizes to a near-constant (#383).
+    // occupies a sliver at the top of 0..255 and quantizes to a near-constant.
     //
-    // The endpoints are TRIMMED rather than the raw min/max: a handful of extreme cells must not be
+    // The endpoints are trimmed rather than the raw min/max: a handful of extreme cells must not be
     // able to rescale the whole frame, or a blinking text cursor would rewrite every cell and read as
     // progress forever. Trimming K cells from each end clamps that away while still preserving real
     // structure, which occupies far more cells than K (a row of sidebar text covers dozens).
@@ -81,7 +81,7 @@ function quantizedGrid(data, srcW, srcH) {
 }
 /**
  * The frame's overall brightness, coarsely quantized. Normalization deliberately discards absolute
- * level, so this is prefixed back on for the two cases where absolute level IS the change: a uniform
+ * level, so this is prefixed back on for the two cases where absolute level is the change: a uniform
  * frame (an all-white blank vs an all-black screen normalize identically), and a whole-page dim such
  * as a modal overlay, which preserves relative structure while changing the whole frame. Quantized
  * coarsely so ordinary antialiasing noise cannot move it.

package/dist/evidence/redaction.d.ts

@@ -35,7 +35,7 @@ export interface RedactedScreenshot {
 export interface RedactScreenshotOptions {
     /**
      * Longest emitted edge in pixels. Clamped to [1, 128]: a caller may request a
-     * SMALLER (safer) thumbnail but never a larger one, so no call site can widen
+     * smaller (safer) thumbnail but never a larger one, so no call site can widen
      * the frame back into legibility. Default 96. Blur is not a caller knob: it is
      * an internal safety floor computed from the output size.
      */
@@ -52,7 +52,7 @@ export declare function digestText(text: string, length?: number): string;
 export declare function tailText(value: string, maxChars: number): string;
 /**
  * A redacted, ellipsis-prefixed tail of captured output for a (public-bound)
- * message field. Pattern-redacts the FULL text BEFORE truncating: slicing a tail
+ * message field. Pattern-redacts the full text before truncating: slicing a tail
  * first could cut through a secret's prefix (e.g. drop "sk-proj-") and defeat the
  * pattern matcher on the remainder. Callers should literal-scrub known
  * provisioned values first; this is the pattern pass. Empty output -> "(no output)".
@@ -103,7 +103,7 @@ export declare function scrubLiterals(values: readonly string[]): (text: string)
 /**
  * Coerce an unknown thrown value to its message string. Prefer this over the
  * inline `error instanceof Error ? error.message : String(error)` so error
- * stringification stays uniform. Note: this does NOT redact -- sites that emit
+ * stringification stays uniform. Note: this does not redact; sites that emit
  * to public-bound artifacts must run the result through `redactText` first.
  */
 export declare function toErrorMessage(error: unknown): string;