humanish 0.23.0 → 0.25.0

package/dist/comms-email-catch.js

@@ -1,5 +1,5 @@
 // A VENDOR-NEUTRAL loopback catch server for email-send APIs (#297). An app hardwired to a hosted
-// email provider is redirected into the faux bus with ONE env var and no code change: point the app's
+// email provider is redirected into the fake bus with ONE env var and no code change: point the app's
 // API base URL at this server. The catch does not depend on, or name itself after, any one vendor —
 // it normalizes each provider's distinct wire shape (Resend's flat body, SendGrid's nested
 // personalizations, Postmark's TitleCase, a custom app's own JSON) to one shape via pluggable

package/dist/{comms-faux-inbox.d.ts → comms-fake-inbox.d.ts}

@@ -6,7 +6,7 @@ export declare function extractLinks(body: string): string[];
  *  "verification code 8A3F2K") are high-precision and preferred; if none are labeled, fall back to an
  *  isolated 4–8 digit run (a bare OTP). Pure; tokens are runtime-only literal-scrub targets. */
 export declare function extractOtpCodes(body: string): string[];
-export interface FauxInboxOptions {
+export interface FakeInboxOptions {
     /** "email" (default) or "sms" — the address shape + surface differ; machinery is identical. */
     channel?: CommsChannelKind;
     /** Email domain for minted addresses. Default example.test (an RFC 6761 reserved, unroutable test
@@ -15,18 +15,26 @@ export interface FauxInboxOptions {
     /** Injected clock (ms) for deterministic tests. Default Date.now. */
     now?: () => number;
 }
-/** The in-process faux adapter. Implements the same CommsChannel port a real provider adapter would. */
-export declare class FauxInbox implements CommsChannel {
+/** The in-process fake adapter. Implements the same CommsChannel port a real provider adapter would. */
+export declare class FakeInbox implements CommsChannel {
     readonly channel: CommsChannelKind;
-    readonly kind: "faux";
+    readonly kind: "fake";
     private readonly domain;
     private readonly clock;
     private readonly byActor;
     private readonly byValue;
     private readonly queues;
     private counter;
-    constructor(options?: FauxInboxOptions);
+    constructor(options?: FakeInboxOptions);
     provision(actorId: string): Promise<CommsAddress>;
+    /**
+     * Provision an inbox for `actorId` at an EXPLICIT address (a lab-declared recipient), so the
+     * app-under-test's send to that literal address resolves in `deliverRaw` (which drops recipients
+     * with no provisioned inbox). Same value-collision guard as `provision`; if `actorId` already held
+     * a different auto-generated address, the declared address supersedes it (the lab's declaration
+     * wins). Idempotent: re-declaring the same address returns the existing inbox without clearing it.
+     */
+    provisionAddress(actorId: string, value: string): Promise<CommsAddress>;
     private route;
     send(message: OutboundMessage): Promise<CommsMessage>;
     deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;

package/dist/{comms-faux-inbox.js → comms-fake-inbox.js}

@@ -1,4 +1,7 @@
-// The FAUX in-process email/SMS bus (#297 Stage 2). Deterministic, $0, offline, public-safe: a
+// The FAKE in-process email/SMS bus (#297 Stage 2). "Fake" in the precise test-double sense (Fowler):
+// a working, in-memory implementation of the CommsChannel port that takes a production shortcut — the
+// same slot as Kubernetes' `fake` clientset, distinct from a mock/stub. Deterministic, $0, offline,
+// public-safe: a
 // message an app-under-test "sends" (via an ingress like the vendor-neutral email catch) is routed to the
 // addressed actor inbox and read back through the same CommsChannel port a real provider adapter
 // would implement. Nothing leaves the process. See comms-types.ts for the port + public-safety notes.
@@ -73,10 +76,10 @@ function smsAddressFor(actorId) {
     const digits = digestText(actorId, 16).replace(/[a-f]/g, (c) => String(c.charCodeAt(0) % 10)).slice(0, 7);
     return `+1555${digits}`;
 }
-/** The in-process faux adapter. Implements the same CommsChannel port a real provider adapter would. */
-export class FauxInbox {
+/** The in-process fake adapter. Implements the same CommsChannel port a real provider adapter would. */
+export class FakeInbox {
     channel;
-    kind = "faux";
+    kind = "fake";
     domain;
     clock;
     byActor = new Map();
@@ -95,7 +98,7 @@ export class FauxInbox {
         const value = this.channel === "sms" ? smsAddressFor(actorId) : `${sanitizeLocalPart(actorId)}@${this.domain}`;
         // Address collision guard: two distinct actor ids can sanitize to the same local part. Reuse the
         // existing inbox rather than resetting its queue (which would drop already-delivered mail). Both
-        // actors then share it — a faux-world edge; declare distinct addresses to avoid it.
+        // actors then share it — a fake-world edge; declare distinct addresses to avoid it.
         const prior = this.byValue.get(value.toLowerCase());
         if (prior) {
             this.byActor.set(actorId, prior);
@@ -107,6 +110,27 @@ export class FauxInbox {
         this.queues.set(value.toLowerCase(), []);
         return address;
     }
+    /**
+     * Provision an inbox for `actorId` at an EXPLICIT address (a lab-declared recipient), so the
+     * app-under-test's send to that literal address resolves in `deliverRaw` (which drops recipients
+     * with no provisioned inbox). Same value-collision guard as `provision`; if `actorId` already held
+     * a different auto-generated address, the declared address supersedes it (the lab's declaration
+     * wins). Idempotent: re-declaring the same address returns the existing inbox without clearing it.
+     */
+    async provisionAddress(actorId, value) {
+        const normalized = value.trim();
+        const key = normalized.toLowerCase();
+        const prior = this.byValue.get(key);
+        if (prior) {
+            this.byActor.set(actorId, prior);
+            return prior;
+        }
+        const address = { channel: this.channel, actorId, value: normalized, digest: digestText(normalized, 16) };
+        this.byActor.set(actorId, address);
+        this.byValue.set(key, address);
+        this.queues.set(key, []);
+        return address;
+    }
     route(from, to, subject, body) {
         const at = this.clock();
         const message = {
@@ -154,4 +178,4 @@ export class FauxInbox {
         return [...this.byActor.values()];
     }
 }
-//# sourceMappingURL=comms-faux-inbox.js.map
+//# sourceMappingURL=comms-fake-inbox.js.map

package/dist/comms-fake-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-fake-inbox.js","sourceRoot":"","sources":["../src/comms-fake-inbox.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,sGAAsG;AACtG,oGAAoG;AACpG,iBAAiB;AACjB,0GAA0G;AAC1G,iGAAiG;AACjG,sGAAsG;AAEtG,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAU5C;qFACqF;AACrF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAG,CAAC,GAAW,EAAQ,EAAE;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACjD,IAAI,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAyB,CAAC;IAC9B,MAAM,IAAI,GAAG,+BAA+B,CAAC;IAC7C,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,4BAA4B,CAAC;IAC1C,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI;SACR,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC;SACzC,OAAO,CAAC,6BAA6B,EAAE,GAAG,CAAC;SAC3C,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;gGAEgG;AAChG,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC7D,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAG,CAAC,IAAc,EAAE,IAAY,EAAQ,EAAE;QAClD,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;IACH,CAAC,CAAC;IACF,oGAAoG;IACpG,0FAA0F;IAC1F,MAAM,SAAS,GAAG,qNAAqN,CAAC;IACxO,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI;QAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpD,+FAA+F;IAC/F,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,8CAA8C,CAAC;IAC9D,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI;QAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAe;IACxC,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC;AACjG,CAAC;AAED,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1G,OAAO,QAAQ,MAAM,EAAE,CAAC;AAC1B,CAAC;AAYD,wGAAwG;AACxG,MAAM,OAAO,SAAS;IACX,OAAO,CAAmB;IAC1B,IAAI,GAAG,MAAe,CAAC;IACf,MAAM,CAAS;IACf,KAAK,CAAe;IACpB,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC1C,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC1C,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;IACpD,OAAO,GAAG,CAAC,CAAC;IAEpB,YAAY,UAA4B,EAAE;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC;QAC1C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC;QAC/C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAAe;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC/G,iGAAiG;QACjG,iGAAiG;QACjG,oFAAoF;QACpF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACpD,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACjC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,OAAO,GAAiB,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;QACvG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;QACzC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,gBAAgB,CAAC,OAAe,EAAE,KAAa;QACnD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACjC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,OAAO,GAAiB,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,UAAU,EAAE,EAAE,CAAC,EAAE,CAAC;QACxH,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,KAAK,CAAC,IAAY,EAAE,EAAkB,EAAE,OAA2B,EAAE,IAAY;QACvF,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACxB,MAAM,OAAO,GAAiB;YAC5B,EAAE,EAAE,SAAS,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;YAC9D,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI;YACJ,EAAE;YACF,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;YAC7C,IAAI;YACJ,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC;YACzB,KAAK,EAAE,eAAe,CAAC,IAAI,CAAC;YAC5B,MAAM,EAAE,EAAE;YACV,WAAW,EAAE,EAAE;SAChB,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,EAAE,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;YACxD,IAAI,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAwB;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACnF,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAmB;QAClC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC;aAC1B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;aAChE,MAAM,CAAC,CAAC,OAAO,EAA2B,EAAE,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC;QACvE,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC,CAAC,uDAAuD;QACvF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAqB,EAAE,KAAK,GAAG,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QACjE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,GAAG,KAAK,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,gFAAgF;IAChF,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;CACF"}

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

@@ -1,4 +1,5 @@
-import type { CommsChannel } from "./comms-types.js";
+import type { CommsAddress, CommsChannel } from "./comms-types.js";
+import { type CommsThreadArtifact } from "./comms-evidence.js";
 import { type EmailSendProfile } from "./comms-email-catch.js";
 import { type DetachedTimers } from "./e2b-detached.js";
 import type { E2BDesktopSandbox } from "./e2b-desktop-launch.js";
@@ -57,7 +58,37 @@ export declare function drainCommsCatch(desktop: E2BDesktopSandbox, deployed: Pi
 }>;
 /**
  * Parse drained raw sends with the host profiles and route them into the CommsChannel (the host-side
- * FauxInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
+ * FakeInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
  * in-sandbox and in-process routes normalize identically.
  */
 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
+ *  it silently. */
+export interface CommsThreadCollection {
+    artifact?: CommsThreadArtifact;
+    /** Raw sends the in-sandbox catch captured this run (all POSTed paths). */
+    captured: number;
+    /** Distinct messages that matched a provisioned recipient inbox (drives whether an artifact exists). */
+    matched: number;
+}
+/**
+ * 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
+ * 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
+ * teardown.
+ */
+export declare function collectCommsThread(args: {
+    desktop: E2BDesktopSandbox;
+    deployed: Pick<DeployedCommsCatch, "deliveriesPath">;
+    channel: CommsChannel;
+    /** The inboxes provisioned for this run (declared recipients). Only mail to these is evidenced. */
+    inboxes: CommsAddress[];
+    profiles?: EmailSendProfile[];
+    requestTimeoutMs?: number;
+}): Promise<CommsThreadCollection>;

package/dist/comms-sandbox-catch.js

@@ -6,6 +6,7 @@
 // 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
 // injected base-URL env (`http://127.0.0.1:<port>`) is known before the sandbox is created.
+import { buildCommsThreadArtifact } from "./comms-evidence.js";
 import { DEFAULT_EMAIL_PROFILES } from "./comms-email-catch.js";
 import { startDetachedProcess } from "./e2b-detached.js";
 /** The default in-sandbox loopback port for the catch. Fixed (not ephemeral) so the injected base-URL
@@ -126,7 +127,7 @@ export async function drainCommsCatch(desktop, deployed, cursor = 0, requestTime
 }
 /**
  * Parse drained raw sends with the host profiles and route them into the CommsChannel (the host-side
- * FauxInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
+ * FakeInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
  * in-sandbox and in-process routes normalize identically.
  */
 export async function routeCapturedSends(sends, channel, profiles = DEFAULT_EMAIL_PROFILES) {
@@ -154,4 +155,35 @@ export async function routeCapturedSends(sends, channel, profiles = DEFAULT_EMAI
     }
     return delivered;
 }
+/**
+ * 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
+ * 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
+ * teardown.
+ */
+export async function collectCommsThread(args) {
+    const { sends } = await drainCommsCatch(args.desktop, args.deployed, 0, args.requestTimeoutMs);
+    if (sends.length === 0)
+        return { captured: 0, matched: 0 };
+    await routeCapturedSends(sends, args.channel, args.profiles);
+    const seen = new Set();
+    const messages = [];
+    for (const inbox of args.inboxes) {
+        for (const message of await args.channel.poll(inbox, 0)) {
+            // A single send addressed to several provisioned inboxes must appear once in the thread.
+            if (seen.has(message.id))
+                continue;
+            seen.add(message.id);
+            messages.push(message);
+        }
+    }
+    if (messages.length === 0)
+        return { captured: sends.length, matched: 0 };
+    messages.sort((a, b) => a.deliveredAt - b.deliveredAt || a.id.localeCompare(b.id));
+    return { artifact: buildCommsThreadArtifact(messages), captured: sends.length, matched: messages.length };
+}
 //# sourceMappingURL=comms-sandbox-catch.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"comms-sandbox-catch.js","sourceRoot":"","sources":["../src/comms-sandbox-catch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"comms-sandbox-catch.js","sourceRoot":"","sources":["../src/comms-sandbox-catch.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,wGAAwG;AACxG,uGAAuG;AACvG,qGAAqG;AACrG,qGAAqG;AACrG,qGAAqG;AACrG,oGAAoG;AACpG,4FAA4F;AAG5F,OAAO,EAAE,wBAAwB,EAA4B,MAAM,qBAAqB,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAyB,MAAM,wBAAwB,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAuB,MAAM,mBAAmB,CAAC;AAG9E;;8EAE8E;AAC9E,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAC/C,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEhD,iDAAiD;AACjD,SAAS,GAAG,CAAC,KAAa;IACxB,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,2CAA2C;IAC3C,sDAAsD;IACtD,sCAAsC;IACtC,+CAA+C;IAC/C,6EAA6E;IAC7E,oEAAoE;IACpE,8BAA8B;IAC9B,8BAA8B;IAC9B,gDAAgD;IAChD,qNAAqN;IACrN,uJAAuJ;IACvJ,oCAAoC;IACpC,6GAA6G;IAC7G,yBAAyB;IACzB,0DAA0D;IAC1D,sGAAsG;IACtG,sGAAsG;IACtG,8FAA8F;IAC9F,oJAAoJ;IACpJ,2GAA2G;IAC3G,OAAO;IACP,+EAA+E;IAC/E,+BAA+B;CAChC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AA0Bb;0GAC0G;AAC1G,KAAK,UAAU,YAAY,CACzB,OAA0B,EAC1B,IAAY,EACZ,OAAyE;IAEzE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACzG,MAAM,QAAQ,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAC3C,SAAS,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ;aAClC,GAAG,CAAC,yCAAyC,IAAI,6BAA6B,EAAE,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE,CAAC;aAC/H,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,sBAAsB,CAAC;YAAE,OAAO,IAAI,CAAC;QACxE,IAAI,GAAG,EAAE,IAAI,QAAQ;YAAE,OAAO,KAAK,CAAC;QACpC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AASD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAA0B,EAC1B,UAAmC,EAAE;IAErC,kGAAkG;IAClG,sGAAsG;IACtG,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,0BAA0B,CAAC,CAAC,CAAC;IAC5E,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,MAAM,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,iBAAiB,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,aAAa,CAAC;IAC3C,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,MAAM,CAAC;IAC5D,MAAM,UAAU,GAAG,GAAG,GAAG,YAAY,CAAC;IACtC,MAAM,cAAc,GAAG,GAAG,GAAG,oBAAoB,CAAC;IAElD,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,YAAY,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACzE,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC;IAC5D,MAAM,oBAAoB,CAAC,OAAO,EAAE;QAClC,IAAI;QACJ,OAAO,EAAE,QAAQ,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,IAAI,GAAG,CAAC,cAAc,CAAC,EAAE;QACjE,gBAAgB;KACjB,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE;QAC9C,SAAS,EAAE,OAAO,CAAC,cAAc,IAAI,MAAM;QAC3C,gBAAgB;QAChB,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;KAC1B,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,IAAI,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA0B,EAC1B,QAAoD,EACpD,MAAM,GAAG,CAAC,EACV,gBAAgB,GAAG,MAAM;IAEzB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,sBAAsB,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAC3H,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IACnC,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACxE,oGAAoG;IACpG,oGAAoG;IACpG,sGAAsG;IACtG,wEAAwE;IACxE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;YAC3D,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,MAAM,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACvG,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAwB,EACxB,OAAqB,EACrB,WAA+B,sBAAsB;IAErD,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;QACrG,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;YAC1D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;gBACxC,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,EAAE,EAAE,UAAU,CAAC,EAAE;gBACjB,GAAG,CAAC,UAAU,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC;gBAC5E,IAAI,EAAE,UAAU,CAAC,IAAI;aACtB,CAAC,CAAC;YACH,SAAS,IAAI,QAAQ,CAAC,MAAM,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAcD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAQxC;IACC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC/F,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC3D,MAAM,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjC,KAAK,MAAM,OAAO,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;YACxD,yFAAyF;YACzF,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAAE,SAAS;YACnC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACzE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnF,OAAO,EAAE,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC5G,CAAC"}

package/dist/comms-types.d.ts

@@ -18,7 +18,7 @@ export interface CommsMessage {
     /** Resolved recipient inboxes this message was delivered to. */
     to: CommsAddress[];
     subject?: string;
-    /** Runtime-only for real; local-only for faux (never a share path without redaction — #108). */
+    /** Runtime-only for real; local-only for fake (never a share path without redaction — #108). */
     body: string;
     /** Actionable links extracted from the body (magic-link / invite / reset). Runtime-only. */
     links: string[];
@@ -43,12 +43,12 @@ export interface InboundRaw {
     body: string;
 }
 /**
- * The port. Faux (in-process) + real-email + real-sms adapters implement it identically. Async so a
- * real (network) adapter fits without changing callers; the faux adapter just resolves immediately.
+ * The port. Fake (in-process) + real-email + real-sms adapters implement it identically. Async so a
+ * real (network) adapter fits without changing callers; the fake adapter just resolves immediately.
  */
 export interface CommsChannel {
     readonly channel: CommsChannelKind;
-    readonly kind: "faux" | "real";
+    readonly kind: "fake" | "real";
     /** Mint/allocate an inbox for an actor (address auto-generated). Idempotent per actor. */
     provision(actorId: string): Promise<CommsAddress>;
     /** Route a composed message from one actor to addressed inboxes. Returns the delivered record. */

package/dist/comms-types.js

@@ -1,6 +1,6 @@
 // The addressed message bus (#297) — the seam that makes "off-app" comms (email/SMS the persona
 // actually lives in) a first-class, persona-driven testable surface. A single port, addressed by
-// actor; faux (in-process) and real (provider-backed) adapters implement it identically, so the
+// actor; fake (in-process) and real (provider-backed) adapters implement it identically, so the
 // persona surface + evidence writer consume it without knowing which is behind it.
 //
 // PUBLIC-SAFETY: raw address values, message bodies, links, and codes are RUNTIME-ONLY. Only the

package/dist/concurrent-shared-world-lab.js

@@ -919,7 +919,7 @@ export async function runConcurrentSharedWorld(options) {
         //
         // TEMPORARY SHIM (tracked by #296): this CDP URL-relay handoff — reading the host's /lobby/CODE off
         // its own browser and threading it into the follower missions — is a temporary coordination shim.
-        // It is to be augmented/replaced by the actor message bus (faux SMS/email invite) in #297: the
+        // It is to be augmented/replaced by the actor message bus (fake SMS/email invite) in #297: the
         // human-realistic version is the HOST SENDING the invite link and followers RECEIVING and tapping
         // it, rather than the orchestrator relaying the code out-of-band.
         const lobbyCodeLatch = deferred();

package/dist/cua-actor-lab.d.ts

@@ -512,6 +512,10 @@ export interface LaneRunOutcome {
     harnessError: boolean;
     failureCode?: CuaActorLabErrorCode;
     entryKind?: "local-app";
+    /** Relative run-dir path of the digest-only comms-thread evidence artifact this lane wrote
+     *  (humanish.comms-thread.v1), when a comms lab captured mail into its in-sandbox catch. Registered
+     *  in the lane's stream artifacts. Absent when no comms lab ran or nothing was captured. */
+    commsArtifactPath?: string;
 }
 /** Build a lane's writeScreenshot closure: writes under screenshots/<screenshotDir>/ and records
  *  the relative path the trace references (screenshots/<name> at N=1; screenshots/<laneId>/<name>
@@ -733,6 +737,9 @@ export declare function buildCuaBundle(args: {
     isMobile?: boolean;
     runId: string;
     screenshots: string[];
+    /** Relative run-dir path of the digest-only comms-thread evidence artifact (humanish.comms-thread.v1),
+     *  when a comms lab captured mail; registered as a "log" stream artifact. */
+    commsArtifactPath?: string;
     /**
      * Capture-time screenshot policy ("blurred" when policies.redactScreenshots, else "raw").
      * When a session ran, its trace's `redaction.screenshots` is the evidence-of-record and

package/dist/cua-actor-lab.js

@@ -31,7 +31,8 @@ import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS, chromiumEvidenceProfilePreferencesJson
 import { DEFAULT_OPENAI_CU_MODEL } from "./openai-responses-cu.js";
 import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 import { probeUrl, readDetachedLog, runDetachedStep, startDetachedProcess } from "./e2b-detached.js";
-import { DEFAULT_SANDBOX_CATCH_PORT, deployCommsCatch } from "./comms-sandbox-catch.js";
+import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, deployCommsCatch } from "./comms-sandbox-catch.js";
+import { FakeInbox } from "./comms-fake-inbox.js";
 import { DEFAULT_DEVICE_PRESET, isDevicePresetName, resolveDevicePreset } from "./device-presets.js";
 import { cuaLaneValidationReason, isHttpUrl, isLoopbackUrl, MAX_CUA_LANES, subjectStateInvalidReason } from "./lab-config.js";
 import { mapWithConcurrency } from "./concurrency.js";
@@ -994,6 +995,10 @@ export async function runCuaLane(spec, deps) {
     // sandbox-create (below, so the app reads it at boot); the catch is started right after create.
     const commsEmail = (cloneRoute || localTreeRoute) ? config.comms?.email : undefined;
     const commsPort = commsEmail ? (commsEmail.port ?? DEFAULT_SANDBOX_CATCH_PORT) : undefined;
+    // Hoisted so the finally can drain the catch before teardown; `commsArtifactPath` is the written
+    // evidence path folded into the lane outcome.
+    let deployedComms;
+    let commsArtifactPath;
     const commsEnv = commsEmail && commsPort !== undefined
         ? { [commsEmail.injectEnv]: `http://127.0.0.1:${commsPort}` }
         : {};
@@ -1082,7 +1087,7 @@ export async function runCuaLane(spec, deps) {
         // into its env at create) resolves the moment it boots. A comms-declared lab that can't stand the
         // catch up is a setup failure (fail closed) rather than silently sending real mail.
         if (commsEmail && commsPort !== undefined) {
-            const deployedComms = await deployCommsCatch(desktop, { port: commsPort, requestTimeoutMs: deps.requestTimeoutMs });
+            deployedComms = await deployCommsCatch(desktop, { port: commsPort, requestTimeoutMs: deps.requestTimeoutMs });
             if (!deployedComms.ready) {
                 throw new Error(`comms email catch did not become ready on 127.0.0.1:${commsPort} in the subject sandbox`);
             }
@@ -1284,6 +1289,42 @@ export async function runCuaLane(spec, deps) {
                         : { warnings: [...(desktopGeometry.warnings ?? []), ...geometryWarnings] })
                 };
             }
+            // Off-app comms evidence (#297): before this lane's sandbox is torn down, drain everything the
+            // in-sandbox catch captured, route it into a host fake inbox addressed to the declared
+            // recipients, and write the digest-only thread artifact. Wrapped so a drain failure NEVER
+            // breaks teardown — the sandbox must still be killed either way. Runs only for a ready catch.
+            if (commsEmail && deployedComms?.ready) {
+                try {
+                    const commsChannel = new FakeInbox();
+                    const commsInboxes = [];
+                    for (const recipient of commsEmail.recipients ?? []) {
+                        if (recipient.address !== undefined) {
+                            commsInboxes.push(await commsChannel.provisionAddress(recipient.lane, recipient.address));
+                        }
+                    }
+                    const collected = await collectCommsThread({
+                        desktop,
+                        deployed: deployedComms,
+                        channel: commsChannel,
+                        inboxes: commsInboxes,
+                        requestTimeoutMs: deps.requestTimeoutMs
+                    });
+                    if (collected.artifact) {
+                        const path = deps.laneCount === 1 ? "comms/thread.json" : `comms/${spec.streamId}.thread.json`;
+                        await writeContainedOutputFile(deps.artifactRoot, path, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
+                        commsArtifactPath = path;
+                    }
+                    else if (collected.captured > 0) {
+                        // Captured mail that matched no declared recipient must not vanish silently (invariant 6:
+                        // honest signals): tell the operator to declare comms.email.recipients[].address to match
+                        // the address the app actually sends to (e.g. the one the persona surface will sign up with).
+                        warnings.push(`Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`);
+                    }
+                }
+                catch (error) {
+                    warnings.push(`Comms evidence collection failed (run continues; sandbox still torn down): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+                }
+            }
             const failed = sessionError !== undefined || session === undefined;
             // Each route's own keep flag gates its own lane only: a clone.keep can never leak into
             // a local-tree lane's teardown decision, and vice versa.
@@ -1363,7 +1404,8 @@ export async function runCuaLane(spec, deps) {
         noEngagement,
         selfReportedBlocker,
         harnessError,
-        ...(failureCode === undefined ? {} : { failureCode })
+        ...(failureCode === undefined ? {} : { failureCode }),
+        ...(commsArtifactPath === undefined ? {} : { commsArtifactPath })
     };
 }
 /** Run the single IN-PROCESS lane (a custom executor + provider; NO E2B). Always one lane. */
@@ -2252,6 +2294,7 @@ function buildSingleLaneBundle(args) {
         }),
         ...(args.localAppSubject || args.inProcessRoute ? { entryKind: "local-app" } : {}),
         ...(outcome?.session ? { traceArtifactPath: spec.traceArtifactPath } : {}),
+        ...(outcome?.commsArtifactPath === undefined ? {} : { commsArtifactPath: outcome.commsArtifactPath }),
         ...(desktopSpanToMinutes(outcome?.desktopDurationMs) === undefined
             ? {}
             : { desktopMinutes: desktopSpanToMinutes(outcome?.desktopDurationMs) }),
@@ -2768,6 +2811,9 @@ export function buildCuaBundle(args) {
             ...(args.traceArtifactPath
                 ? [{ label: "actor trace", path: args.traceArtifactPath, kind: "trace" }]
                 : []),
+            ...(args.commsArtifactPath
+                ? [{ label: "comms thread", path: args.commsArtifactPath, kind: "log" }]
+                : []),
             ...args.screenshots.map((screenshot, index) => ({
                 label: `screenshot ${String(index + 1).padStart(2, "0")} (${screenshotMode})`,
                 path: screenshot,
@@ -3115,6 +3161,9 @@ export function buildCuaFanoutBundle(args) {
                 ...(session
                     ? [{ label: `lane ${spec.laneId} actor trace`, path: spec.traceArtifactPath, kind: "trace" }]
                     : []),
+                ...(outcome?.commsArtifactPath
+                    ? [{ label: `lane ${spec.laneId} comms thread`, path: outcome.commsArtifactPath, kind: "log" }]
+                    : []),
                 ...screenshots.map((screenshot, screenshotIndex) => ({
                     label: `lane ${spec.laneId} screenshot ${String(screenshotIndex + 1).padStart(2, "0")} (${screenshotMode})`,
                     path: screenshot,