humanish 0.37.0 → 0.39.0

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

@@ -0,0 +1,50 @@
+/** The CLI writer surface this command needs (structurally compatible with program.ts CliIo). */
+interface CatchHostIo {
+    writeOut(text: string): void;
+    writeErr(text: string): void;
+    setExitCode(code: number): void;
+}
+export interface CommsCatchHostOptions {
+    port: number;
+    dir: string;
+    /** Bearer token required on GET /deliveries. Strongly recommended when the host is reachable. */
+    token?: string;
+    /** SECOND port for the READ-ONLY inbox listener bound to 0.0.0.0, so a persona on another machine
+     *  (or in a per-lane desktop) can reach the inbox. Omit to stay loopback-only. */
+    inboxPort?: number;
+    /** Restrict the rendered inbox to these addresses. Omit to render whatever the app actually mailed
+     *  — a standalone catch has no lab roster to read recipients from, and an operator who forgets to
+     *  name one should not get a healthy catch that renders an empty inbox forever (#380). */
+    recipients?: string[];
+    /** Inbox re-render cadence in ms (test seam). */
+    renderIntervalMs?: number;
+}
+/**
+ * Render the persona-facing inbox surface from the catch's own deliveries file into `surfaceDir`.
+ *
+ * This is the half that was missing on an adopter-hosted plane (#380). The catch serves /inbox and
+ * /api/inbox as STATIC FILES; in-sandbox, humanish-as-host renders those files on a cadence. On a
+ * plane humanish does not provision there is no such host, so nothing wrote them and every persona
+ * that reached /inbox got `message not found` against a catch whose /health was green — the funnel
+ * dead-ended at a technically-healthy service.
+ *
+ * Rebuilding from scratch each pass is deliberate and matches refreshInboxSurface: a fresh channel per
+ * pass means a send is never routed twice, so the persona never sees duplicates, and a failed write
+ * simply retries next tick.
+ */
+export declare function renderInboxSurfaceLocally(args: {
+    deliveriesPath: string;
+    surfaceDir: string;
+    recipients?: string[] | undefined;
+}): Promise<{
+    sends: number;
+    messages: number;
+    files: number;
+}>;
+/**
+ * Write the catch script and run it in the foreground. Resolves when the child exits; the caller's
+ * Ctrl-C reaches the child through the shared process group, so the normal way to stop it is the
+ * normal way to stop any foreground server.
+ */
+export declare function runCommsCatchHost(options: CommsCatchHostOptions, io: CatchHostIo): Promise<void>;
+export {};

package/dist/comms-catch-host.js

@@ -0,0 +1,147 @@
+// `humanish comms catch` (#328): run the email catch on the OPERATOR's own host.
+//
+// Why this exists. The in-sandbox catch only works when humanish provisions the subject itself —
+// it clones the app into a sandbox, injects the email-API base URL at boot, and hosts the catch
+// alongside it. An adopter whose study runs against their OWN deployed environment (an app-url or
+// operator-provisioned plane) hands humanish a URL instead, so humanish never boots the app and
+// has nowhere to put a catch. Before this, a `comms:` block on that route was warned inert and the
+// personas simply stalled at the verification screen.
+//
+// The fix is to let the adopter host the same catch and declare it (`comms.email.external`).
+// Shipping it as a COMMAND rather than a spec matters: the adopter runs the identical
+// implementation humanish deploys in-sandbox, so the capture shape, the inbox surface, and the
+// drain contract cannot drift between the two planes. Point the app's email-API base URL at this
+// server and point the lab's `catchBaseUrl` at it too.
+//
+// Runtime: the catch is a python3 stdlib server with no dependencies (that was the 0.29.0 lesson —
+// a co-located catcher must use a runtime the environment guarantees). This command writes the
+// same script and runs it in the foreground until interrupted.
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { SANDBOX_CATCH_SCRIPT, capturedRecipientAddresses, inboxMessagesFrom, parseDeliveriesNdjson } from "./comms-sandbox-catch.js";
+import { buildInboxSurface } from "./comms-inbox.js";
+/** How often the host re-renders the inbox surface from the deliveries file. */
+const DEFAULT_RENDER_INTERVAL_MS = 3_000;
+/**
+ * Render the persona-facing inbox surface from the catch's own deliveries file into `surfaceDir`.
+ *
+ * This is the half that was missing on an adopter-hosted plane (#380). The catch serves /inbox and
+ * /api/inbox as STATIC FILES; in-sandbox, humanish-as-host renders those files on a cadence. On a
+ * plane humanish does not provision there is no such host, so nothing wrote them and every persona
+ * that reached /inbox got `message not found` against a catch whose /health was green — the funnel
+ * dead-ended at a technically-healthy service.
+ *
+ * Rebuilding from scratch each pass is deliberate and matches refreshInboxSurface: a fresh channel per
+ * pass means a send is never routed twice, so the persona never sees duplicates, and a failed write
+ * simply retries next tick.
+ */
+export async function renderInboxSurfaceLocally(args) {
+    let text = "";
+    try {
+        text = await readFile(args.deliveriesPath, "utf8");
+    }
+    catch {
+        text = ""; // no mail captured yet — still render, so /inbox answers "No messages yet."
+    }
+    const sends = parseDeliveriesNdjson(text);
+    const addresses = args.recipients && args.recipients.length > 0 ? args.recipients : capturedRecipientAddresses(sends);
+    const recipients = addresses.map((address, index) => ({
+        lane: `catch-${String(index + 1).padStart(2, "0")}`,
+        address
+    }));
+    const messages = await inboxMessagesFrom(sends, recipients);
+    const files = buildInboxSurface(messages);
+    const dirs = new Set([args.surfaceDir]);
+    for (const file of files) {
+        const slash = file.path.lastIndexOf("/");
+        if (slash > 0)
+            dirs.add(path.join(args.surfaceDir, file.path.slice(0, slash)));
+    }
+    for (const dir of dirs)
+        await mkdir(dir, { recursive: true });
+    for (const file of files)
+        await writeFile(path.join(args.surfaceDir, file.path), file.body, "utf8");
+    return { sends: sends.length, messages: messages.length, files: files.length };
+}
+/**
+ * Write the catch script and run it in the foreground. Resolves when the child exits; the caller's
+ * Ctrl-C reaches the child through the shared process group, so the normal way to stop it is the
+ * normal way to stop any foreground server.
+ */
+export async function runCommsCatchHost(options, io) {
+    const dir = path.resolve(options.dir);
+    const scriptPath = path.join(dir, "catch.py");
+    const deliveriesPath = path.join(dir, "deliveries.ndjson");
+    const surfaceDir = path.join(dir, "surface");
+    await mkdir(surfaceDir, { recursive: true });
+    await writeFile(scriptPath, SANDBOX_CATCH_SCRIPT, "utf8");
+    // Render the EMPTY inbox before the server is announced, so /inbox resolves to the "No messages
+    // yet." page from the first request instead of a bare `message not found` (#380) — a persona reads
+    // that 404 as a broken product and reports a blocker that is really just an empty mailbox.
+    await renderInboxSurfaceLocally({
+        deliveriesPath,
+        surfaceDir,
+        ...(options.recipients === undefined ? {} : { recipients: options.recipients })
+    });
+    const inboxPort = options.inboxPort;
+    const args = [
+        scriptPath,
+        String(options.port),
+        deliveriesPath,
+        surfaceDir,
+        String(inboxPort ?? 0),
+        options.token ?? ""
+    ];
+    io.writeOut([
+        `humanish comms catch listening on http://127.0.0.1:${options.port}`,
+        ...(inboxPort === undefined
+            ? []
+            : [`  read-only inbox listener on http://0.0.0.0:${inboxPort} (GET only; expose THIS to personas)`]),
+        `  POST /emails        <- point your app's email-API base URL here`,
+        `  GET  /inbox         <- the persona opens this${inboxPort === undefined ? " (loopback only without --inbox-port)" : ""}`,
+        `  GET  /deliveries    <- humanish drains this${options.token ? " (bearer token required)" : ""}`,
+        `  GET  /health        <- readiness marker humanish probes before a run`,
+        ``,
+        `Declare it in the lab:`,
+        `  comms:`,
+        `    email:`,
+        `      external:`,
+        `        catchBaseUrl: http://<this-host>:${options.port}`,
+        ...(inboxPort === undefined ? [] : [`        inboxBaseUrl: http://<this-host>:${inboxPort}`]),
+        ...(options.token ? [`        authTokenEnv: HUMANISH_COMMS_TOKEN   # value read at runtime, never persisted`] : []),
+        ``,
+        `Captured mail is written to ${deliveriesPath}. Raw bodies stay on THIS host: the run bundle`,
+        `only ever receives digests (from/to/subject/link) and an OTP count.`,
+        ``
+    ].join("\n") + "\n");
+    await new Promise((resolve) => {
+        const child = spawn("python3", args, { stdio: ["ignore", "inherit", "inherit"] });
+        // Keep the inbox current while the catch runs. Failures are swallowed on purpose: a transient
+        // render error must never take down a server that is still capturing mail correctly, and the
+        // next tick rebuilds from scratch anyway.
+        const renderTimer = setInterval(() => {
+            void renderInboxSurfaceLocally({
+                deliveriesPath,
+                surfaceDir,
+                ...(options.recipients === undefined ? {} : { recipients: options.recipients })
+            }).catch(() => { });
+        }, options.renderIntervalMs ?? DEFAULT_RENDER_INTERVAL_MS);
+        renderTimer.unref?.();
+        const stopRendering = () => clearInterval(renderTimer);
+        child.on("error", (error) => {
+            stopRendering();
+            io.writeErr(`comms catch failed to start (python3 is required): ${error.message}\n`);
+            io.setExitCode(2);
+            resolve();
+        });
+        child.on("exit", (code) => {
+            stopRendering();
+            if (code !== 0 && code !== null) {
+                io.setExitCode(2);
+            }
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=comms-catch-host.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comms-catch-host.js","sourceRoot":"","sources":["../src/comms-catch-host.ts"],"names":[],"mappings":"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"}

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

@@ -23,7 +23,7 @@ export declare const DEFAULT_SANDBOX_CATCH_PORT = 8025;
  * 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.
  */
-export declare const SANDBOX_CATCH_SCRIPT = "import json\nimport os\nimport random\nimport sys\nimport threading\nimport time\nfrom http.server import BaseHTTPRequestHandler, ThreadingHTTPServer\nfrom urllib.parse import unquote\n\nPORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8025\nOUT_FILE = sys.argv[2] if len(sys.argv) > 2 else \"/tmp/humanish-comms/deliveries.ndjson\"\nSERVED_DIR = sys.argv[3] if len(sys.argv) > 3 else (os.path.dirname(OUT_FILE) + \"/surface\")\nINBOX_PORT = int(sys.argv[4]) if len(sys.argv) > 4 else 0\ntry:\n    os.makedirs(os.path.dirname(OUT_FILE), exist_ok=True)\nexcept Exception:\n    pass\nMAX_BODY = 5 * 1024 * 1024\nCSP = \"default-src 'self'; script-src 'none'; object-src 'none'; base-uri 'none'; frame-src 'none'; img-src * data:; style-src 'unsafe-inline'; font-src * data:\"\n\n\ndef message_id():\n    return \"humanish-catch-\" + format(int(time.time() * 1000), \"x\") + format(random.randrange(16 ** 8), \"08x\")\n\n\nclass BaseHandler(BaseHTTPRequestHandler):\n    def log_message(self, *args):\n        return\n\n    def _json(self, status, obj, extra_headers=None):\n        payload = json.dumps(obj).encode(\"utf-8\")\n        self.send_response(status)\n        self.send_header(\"content-type\", \"application/json; charset=utf-8\")\n        for key, value in (extra_headers or {}).items():\n            self.send_header(key, value)\n        self.end_headers()\n        self.wfile.write(payload)\n\n    def do_GET(self):\n        path = self.path.split(\"?\")[0]\n        if path == \"/\" or path == \"/health\":\n            self._json(200, {\"ok\": True, \"service\": \"humanish-comms-catch\"})\n            return\n        if path == \"/inbox\" or path.startswith(\"/inbox/\") or path == \"/api/inbox\" or path.startswith(\"/api/inbox/\"):\n            rel = unquote(path)\n            if \"..\" in rel or chr(0) in rel:\n                self.send_response(400)\n                self.end_headers()\n                return\n            data = None\n            for candidate in (SERVED_DIR + rel, SERVED_DIR + rel + \"/index\"):\n                try:\n                    with open(candidate, \"rb\") as handle:\n                        data = handle.read()\n                    break\n                except Exception:\n                    data = None\n            if data is None:\n                self.send_response(404)\n                self.send_header(\"content-type\", \"text/html; charset=utf-8\")\n                self.end_headers()\n                self.wfile.write(b\"<p>message not found</p>\")\n                return\n            is_api = rel.startswith(\"/api/\")\n            self.send_response(200)\n            self.send_header(\"content-type\", \"application/json; charset=utf-8\" if is_api else \"text/html; charset=utf-8\")\n            if not is_api:\n                self.send_header(\"content-security-policy\", CSP)\n            self.end_headers()\n            self.wfile.write(data)\n            return\n        self._json(404, {\"error\": \"not found\"})\n\n\nclass CaptureHandler(BaseHandler):\n    def do_POST(self):\n        path = self.path.split(\"?\")[0]\n        try:\n            length = int(self.headers.get(\"content-length\") or 0)\n        except Exception:\n            length = 0\n        if length > MAX_BODY:\n            self.send_response(413)\n            self.end_headers()\n            return\n        body = self.rfile.read(length).decode(\"utf-8\", \"replace\") if length > 0 else \"\"\n        try:\n            with open(OUT_FILE, \"a\", encoding=\"utf-8\") as handle:\n                print(json.dumps({\"t\": int(time.time() * 1000), \"path\": path, \"body\": body}), file=handle)\n        except Exception:\n            pass\n        mid = message_id()\n        if path == \"/v3/mail/send\":\n            self.send_response(202)\n            self.send_header(\"x-message-id\", mid)\n            self.end_headers()\n        elif path.endswith(\"/batch\"):\n            self._json(200, {\"data\": [{\"id\": mid}]})\n        else:\n            self._json(200, {\"id\": mid})\n\n\nclass ReadOnlyHandler(BaseHandler):\n    def do_POST(self):\n        self.send_response(405)\n        self.end_headers()\n\n\n# Optional read-only inbox listener on 0.0.0.0 (getHost-reachable from a DIFFERENT sandbox on the\n# shared-world route). Serves GET /inbox + /api/inbox + /health only; POST capture stays on the\n# 127.0.0.1 listener so nothing on the internet can inject a fake captured send. Started only when a\n# distinct inbox port is provided (the CUA same-sandbox route omits it and stays loopback-only).\nif INBOX_PORT and INBOX_PORT != PORT:\n    threading.Thread(target=lambda: ThreadingHTTPServer((\"0.0.0.0\", INBOX_PORT), ReadOnlyHandler).serve_forever(), daemon=True).start()\n\nThreadingHTTPServer((\"127.0.0.1\", PORT), CaptureHandler).serve_forever()\n";
+export declare const SANDBOX_CATCH_SCRIPT = "import json\nimport os\nimport random\nimport sys\nimport threading\nimport time\nfrom http.server import BaseHTTPRequestHandler, ThreadingHTTPServer\nfrom urllib.parse import unquote\n\nPORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8025\nOUT_FILE = sys.argv[2] if len(sys.argv) > 2 else \"/tmp/humanish-comms/deliveries.ndjson\"\nSERVED_DIR = sys.argv[3] if len(sys.argv) > 3 else (os.path.dirname(OUT_FILE) + \"/surface\")\nINBOX_PORT = int(sys.argv[4]) if len(sys.argv) > 4 else 0\n# Optional shared token guarding GET /deliveries (the drain read). Empty = unguarded, which is the\n# in-sandbox default: the capture listener binds loopback there, so nothing external can reach it.\n# An ADOPTER-HOSTED catch is reachable over the network, so it should pass one.\nDELIVERIES_TOKEN = sys.argv[5] if len(sys.argv) > 5 else \"\"\ntry:\n    os.makedirs(os.path.dirname(OUT_FILE), exist_ok=True)\nexcept Exception:\n    pass\nMAX_BODY = 5 * 1024 * 1024\nCSP = \"default-src 'self'; script-src 'none'; object-src 'none'; base-uri 'none'; frame-src 'none'; img-src * data:; style-src 'unsafe-inline'; font-src * data:\"\n\n\ndef message_id():\n    return \"humanish-catch-\" + format(int(time.time() * 1000), \"x\") + format(random.randrange(16 ** 8), \"08x\")\n\n\nclass BaseHandler(BaseHTTPRequestHandler):\n    def log_message(self, *args):\n        return\n\n    def _json(self, status, obj, extra_headers=None):\n        payload = json.dumps(obj).encode(\"utf-8\")\n        self.send_response(status)\n        self.send_header(\"content-type\", \"application/json; charset=utf-8\")\n        for key, value in (extra_headers or {}).items():\n            self.send_header(key, value)\n        self.end_headers()\n        self.wfile.write(payload)\n\n    def do_GET(self):\n        path = self.path.split(\"?\")[0]\n        if path == \"/health\":\n            self._json(200, {\"ok\": True, \"service\": \"humanish-comms-catch\"})\n            return\n        if path == \"/\":\n            # A persona that trims the /inbox path lands here. It used to get the health JSON and read\n            # it as \"wrong place / broken\", so send it where it meant to go. /health keeps the machine\n            # marker: both readiness probes assert on /health specifically, never on /.\n            self.send_response(200)\n            self.send_header(\"content-type\", \"text/html; charset=utf-8\")\n            self.send_header(\"content-security-policy\", CSP)\n            self.end_headers()\n            self.wfile.write(b\"<!doctype html><title>Mailbox</title><p><a href='/inbox'>Open the inbox</a></p>\")\n            return\n        if path == \"/deliveries\":\n            # The drain read. In-sandbox humanish reads the NDJSON file directly; an adopter-hosted\n            # catch is on another machine, so the same bytes are served over HTTP. Capture bodies\n            # can contain a verification link, so this is the one route worth guarding.\n            if DELIVERIES_TOKEN:\n                supplied = self.headers.get(\"authorization\", \"\")\n                if supplied != (\"Bearer \" + DELIVERIES_TOKEN):\n                    self._json(401, {\"error\": \"unauthorized\"})\n                    return\n            try:\n                with open(OUT_FILE, \"rb\") as handle:\n                    body = handle.read()\n            except Exception:\n                body = b\"\"\n            self.send_response(200)\n            self.send_header(\"content-type\", \"application/x-ndjson; charset=utf-8\")\n            self.send_header(\"cache-control\", \"no-store\")\n            self.end_headers()\n            self.wfile.write(body)\n            return\n        if path == \"/inbox\" or path.startswith(\"/inbox/\") or path == \"/api/inbox\" or path.startswith(\"/api/inbox/\"):\n            rel = unquote(path)\n            if \"..\" in rel or chr(0) in rel:\n                self.send_response(400)\n                self.end_headers()\n                return\n            data = None\n            for candidate in (SERVED_DIR + rel, SERVED_DIR + rel + \"/index\"):\n                try:\n                    with open(candidate, \"rb\") as handle:\n                        data = handle.read()\n                    break\n                except Exception:\n                    data = None\n            if data is None:\n                # A JSON route answers in JSON; only the HTML route answers in HTML.\n                if rel.startswith(\"/api/\"):\n                    self._json(404, {\"error\": \"message not found\"})\n                    return\n                self.send_response(404)\n                self.send_header(\"content-type\", \"text/html; charset=utf-8\")\n                self.send_header(\"content-security-policy\", CSP)\n                self.end_headers()\n                self.wfile.write(b\"<!doctype html><title>Mailbox</title><p>message not found</p><p><a href='/inbox'>Back to the inbox</a></p>\")\n                return\n            is_api = rel.startswith(\"/api/\")\n            self.send_response(200)\n            self.send_header(\"content-type\", \"application/json; charset=utf-8\" if is_api else \"text/html; charset=utf-8\")\n            if not is_api:\n                self.send_header(\"content-security-policy\", CSP)\n            self.end_headers()\n            self.wfile.write(data)\n            return\n        self._json(404, {\"error\": \"not found\"})\n\n\nclass CaptureHandler(BaseHandler):\n    def do_POST(self):\n        path = self.path.split(\"?\")[0]\n        try:\n            length = int(self.headers.get(\"content-length\") or 0)\n        except Exception:\n            length = 0\n        if length > MAX_BODY:\n            self.send_response(413)\n            self.end_headers()\n            return\n        body = self.rfile.read(length).decode(\"utf-8\", \"replace\") if length > 0 else \"\"\n        try:\n            with open(OUT_FILE, \"a\", encoding=\"utf-8\") as handle:\n                print(json.dumps({\"t\": int(time.time() * 1000), \"path\": path, \"body\": body}), file=handle)\n        except Exception:\n            pass\n        mid = message_id()\n        if path == \"/v3/mail/send\":\n            self.send_response(202)\n            self.send_header(\"x-message-id\", mid)\n            self.end_headers()\n        elif path.endswith(\"/batch\"):\n            self._json(200, {\"data\": [{\"id\": mid}]})\n        else:\n            self._json(200, {\"id\": mid})\n\n\nclass ReadOnlyHandler(BaseHandler):\n    def do_POST(self):\n        self.send_response(405)\n        self.end_headers()\n\n\n# Optional read-only inbox listener on 0.0.0.0 (getHost-reachable from a DIFFERENT sandbox on the\n# shared-world route). Serves GET /inbox + /api/inbox + /health only; POST capture stays on the\n# 127.0.0.1 listener so nothing on the internet can inject a fake captured send. Started only when a\n# distinct inbox port is provided (the CUA same-sandbox route omits it and stays loopback-only).\nif INBOX_PORT and INBOX_PORT != PORT:\n    threading.Thread(target=lambda: ThreadingHTTPServer((\"0.0.0.0\", INBOX_PORT), ReadOnlyHandler).serve_forever(), daemon=True).start()\n\nThreadingHTTPServer((\"127.0.0.1\", PORT), CaptureHandler).serve_forever()\n";
 export interface DeployCommsCatchOptions {
     /** Fixed loopback port the catch listens on (default 8025). Must be free inside the sandbox. */
     port?: number;
@@ -75,6 +75,30 @@ export declare function drainCommsCatch(desktop: E2BDesktopSandbox, deployed: Pi
     sends: RawCapturedSend[];
     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
+ * 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
+ * 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.
+ */
+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
+ * 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[]>;
 /**
  * Parse drained raw sends with the host profiles and route them into the CommsChannel (the host-side
  * FakeInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
@@ -111,6 +135,52 @@ 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). */
+export interface ExternalCommsCatch {
+    /** 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;
+    /** Bearer token for the drain read, when the adopter guarded it. Value is used, never persisted. */
+    authToken?: string;
+}
+/** 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
+ * looking fine. Fail-closed callers treat `false` as a hard stop before spending on a run.
+ */
+export declare function externalCatchHealthy(external: ExternalCommsCatch, options?: {
+    timeoutMs?: number;
+    fetchFn?: typeof fetch;
+}): Promise<boolean>;
+/**
+ * Drain an adopter-hosted catch over HTTP. Same NDJSON contract and same partial-line discipline as
+ * the in-sandbox `cat` drain: a body that does not end in a newline may have a torn final append, so
+ * that line is dropped rather than parsed into a half-message.
+ */
+export declare function drainExternalCommsCatch(external: ExternalCommsCatch, cursor?: number, options?: {
+    timeoutMs?: number;
+    fetchFn?: typeof fetch;
+}): Promise<{
+    sends: RawCapturedSend[];
+    cursor: number;
+}>;
+/**
+ * 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.
+ */
+export declare function collectExternalCommsThread(args: {
+    external: ExternalCommsCatch;
+    channel: CommsChannel;
+    inboxes: CommsAddress[];
+    profiles?: EmailSendProfile[];
+    timeoutMs?: number;
+    fetchFn?: typeof fetch;
+}): Promise<CommsThreadCollection>;
 /**
  * Render the persona-facing inbox surface (host-side, typed — see comms-inbox.ts) and write the files
  * into the sandbox's served dir, so the catch serves a LIVE inbox the persona opens and clicks. Creates

package/dist/comms-sandbox-catch.js

@@ -48,6 +48,10 @@ PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8025
 OUT_FILE = sys.argv[2] if len(sys.argv) > 2 else "/tmp/humanish-comms/deliveries.ndjson"
 SERVED_DIR = sys.argv[3] if len(sys.argv) > 3 else (os.path.dirname(OUT_FILE) + "/surface")
 INBOX_PORT = int(sys.argv[4]) if len(sys.argv) > 4 else 0
+# Optional shared token guarding GET /deliveries (the drain read). Empty = unguarded, which is the
+# in-sandbox default: the capture listener binds loopback there, so nothing external can reach it.
+# An ADOPTER-HOSTED catch is reachable over the network, so it should pass one.
+DELIVERIES_TOKEN = sys.argv[5] if len(sys.argv) > 5 else ""
 try:
     os.makedirs(os.path.dirname(OUT_FILE), exist_ok=True)
 except Exception:
@@ -75,9 +79,39 @@ class BaseHandler(BaseHTTPRequestHandler):
 
     def do_GET(self):
         path = self.path.split("?")[0]
-        if path == "/" or path == "/health":
+        if path == "/health":
             self._json(200, {"ok": True, "service": "humanish-comms-catch"})
             return
+        if path == "/":
+            # A persona that trims the /inbox path lands here. It used to get the health JSON and read
+            # it as "wrong place / broken", so send it where it meant to go. /health keeps the machine
+            # marker: both readiness probes assert on /health specifically, never on /.
+            self.send_response(200)
+            self.send_header("content-type", "text/html; charset=utf-8")
+            self.send_header("content-security-policy", CSP)
+            self.end_headers()
+            self.wfile.write(b"<!doctype html><title>Mailbox</title><p><a href='/inbox'>Open the inbox</a></p>")
+            return
+        if path == "/deliveries":
+            # The drain read. In-sandbox humanish reads the NDJSON file directly; an adopter-hosted
+            # catch is on another machine, so the same bytes are served over HTTP. Capture bodies
+            # can contain a verification link, so this is the one route worth guarding.
+            if DELIVERIES_TOKEN:
+                supplied = self.headers.get("authorization", "")
+                if supplied != ("Bearer " + DELIVERIES_TOKEN):
+                    self._json(401, {"error": "unauthorized"})
+                    return
+            try:
+                with open(OUT_FILE, "rb") as handle:
+                    body = handle.read()
+            except Exception:
+                body = b""
+            self.send_response(200)
+            self.send_header("content-type", "application/x-ndjson; charset=utf-8")
+            self.send_header("cache-control", "no-store")
+            self.end_headers()
+            self.wfile.write(body)
+            return
         if path == "/inbox" or path.startswith("/inbox/") or path == "/api/inbox" or path.startswith("/api/inbox/"):
             rel = unquote(path)
             if ".." in rel or chr(0) in rel:
@@ -93,10 +127,15 @@ class BaseHandler(BaseHTTPRequestHandler):
                 except Exception:
                     data = None
             if data is None:
+                # A JSON route answers in JSON; only the HTML route answers in HTML.
+                if rel.startswith("/api/"):
+                    self._json(404, {"error": "message not found"})
+                    return
                 self.send_response(404)
                 self.send_header("content-type", "text/html; charset=utf-8")
+                self.send_header("content-security-policy", CSP)
                 self.end_headers()
-                self.wfile.write(b"<p>message not found</p>")
+                self.wfile.write(b"<!doctype html><title>Mailbox</title><p>message not found</p><p><a href='/inbox'>Back to the inbox</a></p>")
                 return
             is_api = rel.startswith("/api/")
             self.send_response(200)
@@ -239,6 +278,86 @@ export async function drainCommsCatch(desktop, deployed, cursor = 0, requestTime
     }
     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
+ * 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
+ * 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 function parseDeliveriesNdjson(text) {
+    let lines = text.split("\n").filter((line) => line.trim().length > 0);
+    if (!text.endsWith("\n") && lines.length > 0)
+        lines = lines.slice(0, -1);
+    const sends = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.path === "string" && typeof parsed.body === "string") {
+                sends.push({ path: parsed.path, body: parsed.body, t: typeof parsed.t === "number" ? parsed.t : 0 });
+            }
+        }
+        catch {
+            // skip a malformed line
+        }
+    }
+    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.
+ */
+export function capturedRecipientAddresses(sends, profiles = DEFAULT_EMAIL_PROFILES) {
+    const addresses = new Set();
+    for (const send of sends) {
+        let parsed;
+        try {
+            parsed = JSON.parse(send.body.length > 0 ? send.body : "{}");
+        }
+        catch {
+            continue;
+        }
+        const profile = profiles.find((candidate) => candidate.sendPaths.includes(send.path)) ?? profiles[0];
+        if (profile === undefined)
+            continue;
+        for (const normalized of profile.parse(send.path, parsed)) {
+            for (const address of normalized.to) {
+                if (address.trim().length > 0)
+                    addresses.add(address);
+            }
+        }
+    }
+    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
+ * is what makes a full rebuild idempotent (a send is never routed twice, so no duplicate emails).
+ */
+export async function inboxMessagesFrom(sends, recipients) {
+    const channel = new FakeInbox();
+    const inboxes = [];
+    for (const recipient of recipients)
+        inboxes.push(await channel.provisionAddress(recipient.lane, recipient.address));
+    await routeCapturedSends([...sends], channel);
+    const seen = new Set();
+    const messages = [];
+    for (const inbox of inboxes) {
+        for (const message of await channel.poll(inbox, 0)) {
+            if (seen.has(message.id))
+                continue;
+            seen.add(message.id);
+            messages.push(message);
+        }
+    }
+    messages.sort((a, b) => a.deliveredAt - b.deliveredAt || a.id.localeCompare(b.id));
+    return messages;
+}
 /**
  * Parse drained raw sends with the host profiles and route them into the CommsChannel (the host-side
  * FakeInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
@@ -300,6 +419,93 @@ export async function collectCommsThread(args) {
     messages.sort((a, b) => a.deliveredAt - b.deliveredAt || a.id.localeCompare(b.id));
     return { artifact: buildCommsThreadArtifact(messages), captured: sends.length, matched: messages.length };
 }
+/** Trim one trailing slash so `${base}/deliveries` never becomes a double slash. */
+function baseOf(url) {
+    return url.replace(/\/+$/, "");
+}
+/** The URL a persona is told to open to read its mail on an adopter-hosted plane. */
+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
+ * looking fine. Fail-closed callers treat `false` as a hard stop before spending on a run.
+ */
+export async function externalCatchHealthy(external, options = {}) {
+    const fetchFn = options.fetchFn ?? fetch;
+    try {
+        const response = await fetchFn(`${baseOf(external.catchBaseUrl)}/health`, {
+            signal: AbortSignal.timeout(options.timeoutMs ?? 15_000)
+        });
+        if (!response.ok)
+            return false;
+        const body = await response.text();
+        return body.includes("humanish-comms-catch");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Drain an adopter-hosted catch over HTTP. Same NDJSON contract and same partial-line discipline as
+ * the in-sandbox `cat` drain: a body that does not end in a newline may have a torn final append, so
+ * that line is dropped rather than parsed into a half-message.
+ */
+export async function drainExternalCommsCatch(external, cursor = 0, options = {}) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const response = await fetchFn(`${baseOf(external.catchBaseUrl)}/deliveries`, {
+        signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
+        ...(external.authToken ? { headers: { authorization: `Bearer ${external.authToken}` } } : {})
+    });
+    if (!response.ok) {
+        throw new Error(`comms catch GET /deliveries returned ${response.status}`);
+    }
+    const body = await response.text();
+    let lines = body.split("\n").filter((line) => line.trim().length > 0);
+    if (!body.endsWith("\n") && lines.length > 0)
+        lines = lines.slice(0, -1);
+    const sends = [];
+    for (const line of lines.slice(cursor)) {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.path === "string" && typeof parsed.body === "string") {
+                sends.push({ path: parsed.path, body: parsed.body, t: typeof parsed.t === "number" ? parsed.t : 0 });
+            }
+        }
+        catch {
+            // skip a malformed line
+        }
+    }
+    return { sends, cursor: lines.length };
+}
+/**
+ * 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.
+ */
+export async function collectExternalCommsThread(args) {
+    const drainOptions = { ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }), ...(args.fetchFn ? { fetchFn: args.fetchFn } : {}) };
+    const { sends } = await drainExternalCommsCatch(args.external, 0, drainOptions);
+    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)) {
+            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 };
+}
 /**
  * Render the persona-facing inbox surface (host-side, typed — see comms-inbox.ts) and write the files
  * into the sandbox's served dir, so the catch serves a LIVE inbox the persona opens and clicks. Creates
@@ -341,24 +547,9 @@ export async function refreshInboxSurface(args) {
         return { count: 0, rendered: false };
     if (args.sinceCount !== undefined && sends.length <= args.sinceCount)
         return { count: sends.length, rendered: false };
-    const channel = new FakeInbox();
-    const inboxes = [];
-    for (const recipient of args.recipients)
-        inboxes.push(await channel.provisionAddress(recipient.lane, recipient.address));
-    await routeCapturedSends(sends, channel);
-    const seen = new Set();
-    const messages = [];
-    for (const inbox of inboxes) {
-        for (const message of await channel.poll(inbox, 0)) {
-            if (seen.has(message.id))
-                continue;
-            seen.add(message.id);
-            messages.push(message);
-        }
-    }
+    const messages = await inboxMessagesFrom(sends, args.recipients);
     if (messages.length === 0)
         return { count: sends.length, rendered: false };
-    messages.sort((a, b) => a.deliveredAt - b.deliveredAt || a.id.localeCompare(b.id));
     await writeInboxSurface(args.desktop, args.deployed.surfaceDir, messages, {
         ...(args.originMap === undefined ? {} : { originMap: args.originMap }),
         ...(args.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: args.requestTimeoutMs })