humanish 0.107.0 → 0.109.0

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
- * 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.
+ * The distinct `to` addresses the captured mail was actually sent to, parsed with the same profiles
+ * that route it. A 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: 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,9 +137,9 @@ 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
- * 200 for anything, and a comms lab whose catch is not actually there collects nothing while
+ * 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 study 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.
  */
 export declare function externalCatchHealthy(external: ExternalCommsCatch, options?: {
@@ -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
- * 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.
+ * The distinct `to` addresses the captured mail was actually sent to, parsed with the same profiles
+ * that route it. A 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: 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,9 +296,9 @@ 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
- * 200 for anything, and a comms lab whose catch is not actually there collects nothing while
+ * 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 study 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.
  */
 export async function externalCatchHealthy(external, options = {}) {
@@ -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.d.ts

@@ -55,9 +55,9 @@ export interface CommsConfigureResult {
     connection?: string;
 }
 /** Save a local copy, never rewrite a committed manifest or silently shadow it by handle. */
-export declare function configureCommsLab(args: {
+export declare function configureCommsStudy(args: {
     cwd: string;
-    lab: string;
+    study: string;
     connection: string;
     apply?: boolean;
     planToken?: string;

package/dist/comms/setup.js

@@ -2,15 +2,17 @@ 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";
 import { createReceivingAdapter } from "./receiving-runtime.js";
 import { RECEIVING_SCOPE_UNSUPPORTED } from "./receiving-types.js";
-import { parseLabConfig } from "../lab/config.js";
-import { resolveLabManifest } from "../lab/discover.js";
+import { parseStudy } from "../study/config.js";
+import { resolveStudyManifest } from "../study/discover.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { otherStudyFiles } from "../study/files.js";
+import { isNodeError } from "../run/type-guards.js";
 export async function checkCommsConnection(args) {
     const base = {
         schema: "humanish.comms-check.v1",
@@ -106,50 +108,79 @@ export async function receivingRequiredKey(cwd, connectionName) {
     }
 }
 /** Save a local copy, never rewrite a committed manifest or silently shadow it by handle. */
-export async function configureCommsLab(args) {
+export async function configureCommsStudy(args) {
     const base = { schema: "humanish.comms-configure.v1", ok: false, applied: false };
     try {
         const connection = (await readCommsConnections(args.cwd)).connections[args.connection];
         if (!connection)
             return { ...base, message: "Save the selected connection first." };
-        const source = await resolveLabManifest(args.cwd, args.lab);
-        if (!source.ok)
-            return { ...base, message: "The selected lab could not be read safely." };
+        const source = await resolveStudyManifest(args.cwd, args.study);
+        if (!source.ok) {
+            // A v2 source or a labs/ file gets discovery's refusal, which names the fix.
+            const named = source.error.code === "HUMANISH_STUDY_V2_UNSUPPORTED" ||
+                source.error.code === "HUMANISH_STUDY_RETIRED_DIRECTORY";
+            return {
+                ...base,
+                message: named ? source.error.message : "The selected study could not be read safely.",
+            };
+        }
         const root = await prepareSelectedOutputDirectory(args.cwd, args.cwd);
         const rel = path
             .relative(root.requestedPath, path.resolve(args.cwd, source.path))
             .replace(/\\/g, "/");
         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"));
+            return { ...base, message: "The study file is missing or too large." };
+        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;
-        const existing = lab.comms;
+            return { ...base, message: "The study file must be a mapping." };
+        const studyRecord = raw;
+        const existing = studyRecord.comms;
         if (existing?.email && existing.email.connection === undefined)
             return {
                 ...base,
-                message: "This lab uses local capture. Preserve it or make a separate lab before selecting real email.",
+                message: "This study uses local capture. Preserve it or make a separate study before selecting real email.",
             };
-        lab.comms = { ...existing, email: { ...existing?.email, connection: args.connection } };
-        const validated = parseLabConfig(lab);
+        // Discovery resolved the source, so it is a v3 study, and the copy keeps its comments.
+        const study = parseDocument(text);
+        study.setIn(["comms", "email", "connection"], args.connection);
+        const validated = parseStudy(study.toJS());
         if (!validated.ok)
             return {
                 ...base,
-                message: "This lab does not support real email receiving. Use a hosted computer-use app-url, clone or local-tree route; shared-world must be concurrent.",
+                message: "This study does not support real email receiving. Use a hosted computer-use app-url, clone or local-tree route; shared-world must be concurrent.",
             };
         const filename = path
             .basename(source.path)
             .replace(/\.ya?ml$/, "")
             .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)
+            return { ...base, message: "Use a simple study filename before configuring email." };
+        const destination = `.humanish/local/studies/${filename}`;
+        if (path.basename(rel) === filename)
+            return {
+                ...base,
+                message: "This is already the local receiving copy. Select its original study to configure a separate copy, or edit this study file directly.",
+            };
+        // A second file with this name in another study directory would shadow it, or take the name
+        // migrate needs to move a labs/ file.
+        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: "This is already the local receiving copy. Select its original lab to configure a separate copy, or edit this manifest directly.",
+                message: `${others.join(", ")} already uses the name ${stem}. Rename or remove it before configuring email, so \`run ${stem}\` reads one file.`,
             };
         let prior;
         try {
@@ -158,7 +189,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")
@@ -181,9 +212,9 @@ export async function configureCommsLab(args) {
         if (args.planToken !== undefined && args.planToken !== token)
             return {
                 ...base,
-                message: "The lab or destination changed since preview. Preview again before saving.",
+                message: "The study 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();
@@ -205,13 +236,13 @@ export async function configureCommsLab(args) {
         return {
             ...plan,
             applied: true,
-            message: `Saved ${destination}. Start that exact lab path; the original manifest was preserved.`,
+            message: `Saved ${destination}. Start that exact study path; the original file was preserved.`,
         };
     }
     catch {
         return {
             ...base,
-            message: "Could not configure this lab safely. Check configuration, paths and permissions; no provider resources were created.",
+            message: "Could not configure this study safely. Check configuration, paths and permissions; no provider resources were created.",
         };
     }
 }

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[]>;