humanish 0.106.1 → 0.108.0

package/dist/routes/shared-world/comms.js

@@ -1,24 +1,25 @@
 // Off-app comms for the concurrent shared-world route: which email catch a plane gets (in the
-// subject sandbox, or adopter-hosted), and the drains that match captured mail to the seats'
+// subject sandbox, or adopter-hosted), and the drains that match captured mail to the participants'
 // declared inboxes and write the digest-only thread.
+import { catchTokenOf, catchTokenRefusal, collectExternalCommsEvidence, } from "../../comms/external-evidence.js";
 import { FakeInbox } from "../../comms/fake-inbox.js";
 import { prepareReceivingRun } from "../../comms/receiving-runtime.js";
-import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, collectExternalCommsThread, externalCatchHealthy, externalInboxUrl, } from "../../comms/sandbox-catch.js";
+import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, externalCatchHealthy, externalInboxUrl, } from "../../comms/sandbox-catch.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { writeContainedOutputFile } from "../../run/contained-output.js";
 import { addressedRecipients } from "../../lab/parse/comms.js";
-// Off-app comms (#297): on the provisioned-getHost plane the harness owns the ONE subject sandbox, so
-// it can redirect the app's email-API sends into an in-sandbox catch and evidence them. Gated ENTIRELY
-// on config.comms — no comms declared → zero change. The base-URL env is injected into the subject
+// Off-app comms: on the provisioned-getHost plane the harness owns the one subject sandbox, so
+// it can redirect the app's email-API sends into an in-sandbox catch and evidence them. Gated entirely
+// on config.comms: no comms declared → zero change. The base-URL env is injected into the subject
 // sandbox at create (fixed port known up front); the catch is deployed before serve; the drain + digest
-// evidence run at subject teardown, then register run-level in the bundle. NOT available on the
+// evidence run at subject teardown, then register run-level in the bundle. Unavailable on the
 // external-public plane (the app is an operator-owned deployment the harness never provisions).
 export function subjectCommsOf(config, planeClass) {
     const commsEmail = planeClass === "provisioned-getHost" && config.comms?.email?.kind === "fake"
         ? config.comms.email
         : undefined;
     const commsPort = commsEmail ? (commsEmail.port ?? DEFAULT_SANDBOX_CATCH_PORT) : undefined;
-    // injectEnv is absent on an adopter-hosted plane (#328): there is no subject env to inject
+    // injectEnv is absent on an adopter-hosted plane: there is no subject env to inject
     // because the operator points their own app at their own catch.
     const commsEnv = commsEmail?.injectEnv !== undefined && commsPort !== undefined
         ? { [commsEmail.injectEnv]: `http://127.0.0.1:${commsPort}` }
@@ -26,39 +27,47 @@ export function subjectCommsOf(config, planeClass) {
     return { email: commsEmail, port: commsPort, env: commsEnv };
 }
 /**
- * ADOPTER-HOSTED ingress (#328): on the external-public plane the harness provisions nothing, so
- * it cannot host a catch — but the OPERATOR can, and then humanish still does every other part of
+ * Adopter-hosted ingress: on the external-public plane the harness provisions nothing, so
+ * it cannot host a catch. The operator can, and then humanish still does every other part of
  * the funnel: it tells each persona its address and inbox URL, drains the declared catch over
  * HTTP at teardown, and writes the same digest-only evidence. Declaring `external` is what turns
  * the previously-inert block into a working one. Returns an error message when the declared catch
  * does not answer as a humanish catch.
  */
-export async function prepareExternalComms(config, planeClass, dryRun, warnings) {
+export async function prepareExternalComms(config, planeClass, dryRun, warnings, env) {
     const externalComms = planeClass === "external-public" ? config.comms?.email?.external : undefined;
     const externalCommsEmail = externalComms ? config.comms?.email : undefined;
     if (config.comms?.email?.kind === "fake" &&
         planeClass === "external-public" &&
         externalComms === undefined) {
-        warnings.push("comms.email is declared but this is the external-public plane (the shared plane is an operator-owned public deployment the harness does not provision) — the in-sandbox email catch cannot be deployed and no comms evidence is collected. Declare `comms.email.external` to host the catch yourself (#328).");
+        warnings.push("comms.email is declared, but this study drives a public deployment that humanish does not provision, so the email catch cannot run in a sandbox and no email evidence is collected. Run the catch yourself with `humanish comms catch` and declare `comms.email.external`.");
     }
     if (!externalComms || !externalCommsEmail)
         return { ok: true, wiring: undefined };
     const inboxUrl = externalInboxUrl(externalComms);
-    // Fail closed BEFORE any actor sandbox is created: a comms lab whose catch is unreachable
-    // collects nothing while every lane still spends. The probe asserts OUR service marker in
+    const tokenRefusal = catchTokenRefusal(catchTokenOf(externalComms, env));
+    if (tokenRefusal !== undefined)
+        return {
+            ok: false,
+            code: "HUMANISH_SHARED_WORLD_COMMS_TOKEN_INVALID",
+            message: tokenRefusal,
+        };
+    // Fail closed before any actor sandbox is created: a comms lab whose catch is unreachable
+    // collects nothing while every participant still spends. The probe asserts our service marker in
     // /health, so an adopter's proxy answering 200 for everything cannot pass for a catch.
     if (!dryRun && !(await externalCatchHealthy(externalComms))) {
         return {
             ok: false,
+            code: "HUMANISH_SHARED_WORLD_COMMS_CATCH_UNREACHABLE",
             message: `The external comms catch or inbox is unreachable or incompatible (GET /health must identify humanish-comms-catch and advertise recipient-inbox-v1). Update humanish on the catch host and restart it with \`humanish comms catch\` on that host, or drop comms.email to run without the inbox funnel.`,
         };
     }
     return { ok: true, wiring: { external: externalComms, email: externalCommsEmail, inboxUrl } };
 }
 /**
- * Off-app comms evidence (#297): drain everything the in-sandbox catch captured, route it into a
+ * Off-app comms evidence: drain everything the in-sandbox catch captured, route it into a
  * host fake inbox addressed to the declared recipients, and write the run-level digest-only thread
- * artifact — while the subject is STILL alive, before it is killed. Wrapped so a drain error
+ * artifact while the subject is still alive, before it is killed. Wrapped so a drain error
  * never blocks teardown (invariant: all sandboxes torn down by id in the plane's finally). Returns
  * the thread's path when one was written.
  */
@@ -82,11 +91,11 @@ export async function drainSubjectComms(ctx, commsEmail, subjectShell, deployedC
             return "comms/thread.json";
         }
         else if (collected.captured > 0) {
-            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.`);
+            warnings.push(`The email catch captured ${collected.captured} email send(s), but none matched a declared recipient inbox, so no email evidence was written. Set comms.email.recipients[].address to the address the app sends to.`);
         }
         else {
-            // Zero captures is the silent-broken shape (#351): the app never posted to the catch.
-            warnings.push(`Comms catch captured ZERO email sends — the app never delivered mail through the catch. Verify the app reads ${commsEmail.injectEnv} for its email API base URL (an SDK that ignores it sends real mail or throws) and that the flow reached an email step.`);
+            // Zero captures is the silent-broken shape: the app never posted to the catch.
+            warnings.push(`The email catch captured no email sends: the app never delivered mail through it. Verify the app reads ${commsEmail.injectEnv} for its email API base URL (an SDK that ignores it sends real mail or throws) and that the flow reached an email step.`);
         }
     }
     catch (error) {
@@ -95,43 +104,21 @@ export async function drainSubjectComms(ctx, commsEmail, subjectShell, deployedC
     return undefined;
 }
 /**
- * Adopter-hosted drain (#328/#387): same routing and digest-only artifact as the in-sandbox
- * catch — only the transport differs (HTTP GET /deliveries against the catch the operator
+ * Adopter-hosted drain: same routing and digest-only artifact as the in-sandbox
+ * catch. Only the transport differs (HTTP GET /deliveries against the catch the operator
  * runs). Called in the plane's finally so the evidence survives a failed run; a drain error never
  * masks the run's own outcome. Returns the thread's path when one was written.
  */
 export async function drainExternalComms(ctx, comms) {
-    const { env, runPaths, warnings } = ctx;
-    const externalComms = comms.external;
-    const externalCommsEmail = comms.email;
-    try {
-        const commsChannel = new FakeInbox();
-        const commsInboxes = [];
-        for (const recipient of addressedRecipients(externalCommsEmail)) {
-            commsInboxes.push(await commsChannel.provisionAddress(recipient.participantId, recipient.address));
-        }
-        const authToken = externalComms.authTokenEnv === undefined ? undefined : env[externalComms.authTokenEnv];
-        const collected = await collectExternalCommsThread({
-            external: { ...externalComms, ...(authToken === undefined ? {} : { authToken }) },
-            channel: commsChannel,
-            inboxes: commsInboxes,
-        });
-        if (collected.artifact) {
-            const path = "comms/thread.json";
-            await writeContainedOutputFile(runPaths, path, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
-            return path;
-        }
-        else if (collected.captured > 0) {
-            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.`);
-        }
-        else {
-            warnings.push(`Comms catch captured ZERO email sends — your app never delivered mail through the catch at ${externalComms.catchBaseUrl}. Verify the app's email-API base URL points at it and that the flow reached an email step.`);
-        }
-    }
-    catch (error) {
-        warnings.push(`Comms evidence collection failed against the adopter-hosted catch (run continues): ${redactText(toErrorMessage(error))}`);
-    }
-    return undefined;
+    const { path, warnings } = await collectExternalCommsEvidence({
+        external: comms.external,
+        email: comms.email,
+        env: ctx.env,
+        runPaths: ctx.runPaths,
+        knownSecretValues: ctx.knownSecretValues,
+    });
+    ctx.warnings.push(...warnings);
+    return path;
 }
 /** What receiving guards: the lab's email declaration and the subject env names and values. */
 export function receivingSourceOf(residual, env) {

package/dist/routes/shared-world/external-public.d.ts

@@ -11,11 +11,12 @@ export interface ExternalPublicPlaneOutcome {
     commsArtifactPath: string | undefined;
 }
 /**
- * The operator-DECLARED origin (from subject.appUrl) — recorded for evidence/reference ONLY. The
- * operator-OWNERSHIP claim rests on the subject.publicTarget.authorized attestation + this declared
- * appUrl, NOT on digest equality (blocker 2): a normal cross-origin redirect (apex->www, http->https;
- * lobby-trivia.example.test 307-redirects) makes the seats' OBSERVED origin differ from the declared one, which
- * is expected and MUST NOT fail the run. Persisted digest-only (never the raw origin).
+ * The operator-declared origin (from subject.appUrl), recorded for evidence and reference only. The
+ * operator-ownership claim rests on the subject.publicTarget.authorized attestation + this declared
+ * appUrl; digest equality plays no part: a normal cross-origin redirect (apex->www, http->https;
+ * lobby-trivia.example.test 307-redirects) makes the participants' observed origin differ from the
+ * declared one, which is expected and must not fail the run. Persisted digest-only (never the raw
+ * origin).
  */
 export declare function declaredOriginDigestOf(publicAppUrl: string): string | undefined;
 export declare function runExternalPublicPlane(ctx: PlaneContext, live: LiveParticipants, inbox: ExternalCommsWiring | undefined): Promise<ExternalPublicPlaneOutcome>;

package/dist/routes/shared-world/external-public.js

@@ -1,8 +1,9 @@
-// EXTERNAL-PUBLIC plane (#164 phase 2): NO subject sandbox, NO getHost, NO prober. The shared plane
-// is the operator-declared public deployment (publicAppUrl); each seat opens it directly and reaches
-// the shared session through the real UI. A host-first barrier extracts the /lobby/CODE from the host
-// seat's CDP-observed URL (onObservedUrl) and threads it into the follower missions; a follower fails
-// closed WITHOUT opening if the host never yields a code within the handoff deadline.
+// External-public plane: no subject sandbox, no getHost, no prober. The shared plane is the
+// operator-declared public deployment (publicAppUrl); each participant opens it directly and
+// reaches the shared session through the real UI. A host-first barrier extracts the /lobby/CODE
+// from the host's CDP-observed URL (onObservedUrl) and threads it into the follower missions; a
+// follower fails closed without opening if the host never yields a code within the handoff
+// deadline.
 import { liveObserverResult } from "../../observer/live.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { mapWithConcurrency } from "../../run/concurrency.js";
@@ -11,37 +12,39 @@ import { drainExternalComms } from "./comms.js";
 import { LobbyHandoff, runFollower, runHost } from "./handoff.js";
 import { readLobbyCodeFromFrame } from "./lobby-code.js";
 import { hostOriginDigest } from "./provenance.js";
-import { participantRunDeps, startParticipantFlush } from "./seats.js";
+import { participantRunDeps, startParticipantFlush } from "./participant-specs.js";
 /**
- * The operator-DECLARED origin (from subject.appUrl) — recorded for evidence/reference ONLY. The
- * operator-OWNERSHIP claim rests on the subject.publicTarget.authorized attestation + this declared
- * appUrl, NOT on digest equality (blocker 2): a normal cross-origin redirect (apex->www, http->https;
- * lobby-trivia.example.test 307-redirects) makes the seats' OBSERVED origin differ from the declared one, which
- * is expected and MUST NOT fail the run. Persisted digest-only (never the raw origin).
+ * The operator-declared origin (from subject.appUrl), recorded for evidence and reference only. The
+ * operator-ownership claim rests on the subject.publicTarget.authorized attestation + this declared
+ * appUrl; digest equality plays no part: a normal cross-origin redirect (apex->www, http->https;
+ * lobby-trivia.example.test 307-redirects) makes the participants' observed origin differ from the
+ * declared one, which is expected and must not fail the run. Persisted digest-only (never the raw
+ * origin).
  */
 export function declaredOriginDigestOf(publicAppUrl) {
     return publicAppUrl ? hostOriginDigest(publicAppUrl) : undefined;
 }
 export async function runExternalPublicPlane(ctx, live, inbox) {
-    const { plan, hooks, actorSpecs, concurrency, warnings } = ctx;
+    const { plan, deps: seams, actorSpecs, concurrency, warnings } = ctx;
     const participants = plan.plane.participants;
-    // publicAppUrl is the operator-declared shared plane; its ORIGIN is persisted digest-only
-    // (publicOriginDigest), never raw (the raw URL + the runtime observed lobby CODE never land —
-    // TENSION 3). The latch code is scrubbed from all narration.
+    // publicAppUrl is the operator-declared shared plane; its origin is persisted digest-only
+    // (publicOriginDigest), never raw (the raw URL and the runtime observed lobby code never land in
+    // the bundle). The latch code is scrubbed from all narration.
     const publicAppUrl = plan.plane.kind === "external-public" ? plan.plane.appUrl : "";
     const declaredOriginDigest = declaredOriginDigestOf(publicAppUrl);
     const handoff = new LobbyHandoff({
         participantCount: participants.length,
         timeoutMs: ctx.timeoutMs,
-        deadlineMs: hooks.handoffDeadlineMs,
+        deadlineMs: seams.handoffDeadlineMs,
         scrubKnownValues: ctx.scrubKnownValues,
-        // The per-seat vision lobby-code reader (default: the real single-frame OpenAI read). Injectable
-        // so the barrier's handoff + convergence proof are testable without a live vision call.
-        readLobbyCode: hooks.readLobbyCodeFromFrame ?? readLobbyCodeFromFrame,
+        // The per-participant vision lobby-code reader (default: the real single-frame OpenAI read).
+        // Injectable so the barrier's handoff + convergence proof are testable without a live vision
+        // call.
+        readLobbyCode: seams.readLobbyCodeFromFrame ?? readLobbyCodeFromFrame,
         openaiApiKey: ctx.openaiApiKey,
     });
     const deps = {
-        // Scrub the latched lobby CODE (known once the host resolves it) from ALL narration.
+        // Scrub the latched lobby code (known once the host resolves it) from all narration.
         runDeps: participantRunDeps(ctx, live, handoff.scrub),
         publicAppUrl,
         inbox,
@@ -51,11 +54,10 @@ export async function runExternalPublicPlane(ctx, live, inbox) {
     // provisioned path.
     const snapshotArgs = {
         plan,
+        run: ctx.run,
         descriptor: ctx.descriptor,
-        createdAt: ctx.createdAt,
         dryRun: false,
         inProgress: true,
-        runId: ctx.runId,
         source: ctx.source,
         actorSpecs,
         actorResults: [],
@@ -63,8 +65,9 @@ export async function runExternalPublicPlane(ctx, live, inbox) {
         subject: { source: "app-url", envNames: [], state: { provenance: "external-public" } },
         seedDigest: ctx.seedDigest,
         planeClass: "external-public",
-        // Pre-fan-out snapshot: no seat has observed an origin yet, so the OBSERVED publicOriginDigest
-        // is not available; surface the DECLARED origin for the live Observer's reference.
+        // Pre-fan-out snapshot: no participant has observed an origin yet, so the observed
+        // publicOriginDigest is not available; surface the declared origin for the live Observer's
+        // reference.
         ...(declaredOriginDigest === undefined ? {} : { declaredOriginDigest }),
     };
     const inProgressBundle = buildConcurrentSharedWorldBundle({
@@ -85,7 +88,7 @@ export async function runExternalPublicPlane(ctx, live, inbox) {
     let runError;
     let commsArtifactPath;
     // Split the roster into the designated host and the followers, preserving each follower's
-    // ORIGINAL plan index so results land back in plan order (validation guarantees EXACTLY ONE host).
+    // original plan index so results land back in plan order (validation allows exactly one host).
     const hostIndex = participants.findIndex((participant) => participant.host === true);
     const followerEntries = actorSpecs
         .map((spec, index) => ({ spec, index }))

package/dist/routes/shared-world/handoff.d.ts

@@ -1,7 +1,7 @@
 import type { DesktopParticipantRun, ParticipantRunOutcome } from "../computer-use/types.js";
-import { type ParticipantRunDeps } from "./seats.js";
+import { type ParticipantRunDeps } from "./participant-specs.js";
 import type { ActorRunResult, ExternalCommsWiring } from "./types.js";
-/** What the host and follower lanes need besides the handoff. */
+/** What the host and follower participants need besides the handoff. */
 export interface HandoffParticipantDeps {
     runDeps: ParticipantRunDeps;
     publicAppUrl: string;
@@ -9,10 +9,11 @@ export interface HandoffParticipantDeps {
     now: () => number;
 }
 /**
- * The handoff latch, its deadline and what each seat observed. The latched code and observed URLs
- * are runtime-only and land in persisted METADATA only as digests (origin + convergence). (The code
- * is a shareable game code, not a secret, and it still renders in the host's screenshots, which are
- * full-fidelity unless redactScreenshots is set — the digesting is about narration/URL metadata.)
+ * The handoff latch, its deadline and what each participant observed. The latched code and observed
+ * URLs are runtime-only and land in persisted metadata only as digests (origin + convergence). (The
+ * code is a shareable game code, not a secret, and it still renders in the host's screenshots,
+ * which are full-fidelity unless redactScreenshots is set. The digesting is about narration/URL
+ * metadata.)
  */
 export declare class LobbyHandoff {
     readonly observedFinalUrls: (string | undefined)[];
@@ -20,7 +21,7 @@ export declare class LobbyHandoff {
     latchedLobbyCode: string | undefined;
     /** A follower gave up because the deadline passed. */
     timedOut: boolean;
-    /** Why the host seat ended without producing a lobby code. */
+    /** Why the host ended without producing a lobby code. */
     hostFailure: string | undefined;
     readonly deadlineMs: number;
     private readonly lobbyCodeLatch;
@@ -38,7 +39,7 @@ export declare class LobbyHandoff {
         openaiApiKey: string;
     });
     /**
-     * Scrubs the latched lobby CODE from ANY persisted narration once the host resolves it (the
+     * Scrubs the latched lobby code from any persisted narration once the host resolves it (the
      * 6-char code has no detectable secret shape, so shape-only redaction cannot catch it).
      */
     readonly scrub: (text: string) => string;
@@ -52,7 +53,7 @@ export declare class LobbyHandoff {
     waitForHostCode(): Promise<string>;
     /** Releases waiting followers to fail closed when the host ended without a code. */
     releaseFollowersIfUnlatched(outcome: ParticipantRunOutcome | undefined): void;
-    /** The digest-only convergence proofs over what the seats observed. */
+    /** The digest-only convergence proofs over what the participants observed. */
     convergence(declaredOriginDigest: string | undefined): {
         publicOriginDigest: string | undefined;
         lobbyConvergenceDigest: string | undefined;