humanish 0.107.0 → 0.109.0

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

@@ -1,4 +1,4 @@
-// Builds the run bundle for a concurrent shared-world run: per-seat simulations, streams and
+// Builds the run bundle for a concurrent shared-world run: per-participant simulations, streams and
 // events, the sharedWorld evidence block and the review summary.
 import { receivingPublication } from "../../comms/receiving-runtime.js";
 import { redactText } from "../../evidence/redaction.js";
@@ -8,13 +8,14 @@ import { SHARED_WORLD_SCHEMA, concurrencyFacts, sharedWorldParticipantKeys, } fr
 import { commandDigestOf } from "../../subject/state.js";
 import { buildRunCostSummary, desktopSpanToMinutes } from "../../run/cost-summary.js";
 import { participantFactsOf } from "../computer-use/participant-facts.js";
-import { judgeSharedWorld, participantPassed, sharedWorldShortfall, } from "../../run/judge.js";
+import { judgeSharedWorld, participantPassed, sharedWorldShortfall, verdictText, } from "../../run/judge.js";
 import { combineCheckpointDigest } from "./checkpoints.js";
 import { hostOriginDigest } from "./provenance.js";
 import { participantEvent, participantIds } from "../../run/participant-records.js";
 import { sharedWorldParticipantRecords } from "./bundle-records.js";
 import { CONCURRENT_ATTRIBUTION_LIMITS, EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS, } from "./types.js";
-/** Max windows live at the same instant (sweep over start/end points). The honest simultaneity
+import { plural } from "../../run/text.js";
+/** Max windows live at the same instant (sweep over start/end points). The simultaneity
  *  count: the participant count says how many existed; this says how many ever ran at once. */
 export function maxSimultaneousWindows(windows) {
     const points = windows
@@ -34,10 +35,10 @@ export function maxSimultaneousWindows(windows) {
     return max;
 }
 /**
- * The judgment for a shared-world bundle's inputs: how each seat ended, plus what the run observed
- * about its world: overlap, a state change under overlap on the provisioned plane, and lobby
- * convergence on the external-public plane. The bundle's verdict and the lab result's ok both read
- * it.
+ * The judgment for a shared-world bundle's inputs: how each participant ended, plus what the run
+ * observed about its world: overlap, a state change under overlap on the provisioned plane, and
+ * lobby convergence on the external-public plane. The bundle's verdict and the study result's ok
+ * both read it.
  */
 export function judgeSharedWorldRun(args) {
     const external = (args.planeClass ?? "provisioned-getHost") === "external-public";
@@ -68,7 +69,7 @@ export function actorRunPassed(result) {
  *
  * None of those is adopter-scored proof that the mission text was completed. In particular, a
  * productive `budget_reached` session can coexist with lobby convergence without becoming a
- * `goal_satisfied` result (#364).
+ * `goal_satisfied` result.
  */
 function formatSharedWorldActorOutcomes(outcomes, expectedCount) {
     const passedSessions = outcomes.filter((outcome) => outcome.ok).length;
@@ -86,7 +87,7 @@ function formatSharedWorldActorOutcomes(outcomes, expectedCount) {
         .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
         .map(([reason, count]) => `${reason} ${count}/${expectedCount}`)
         .join(", ");
-    return `${passedSessions}/${expectedCount} actor session(s) passed credibility checks; mission endpoint: ${goalSatisfiedSessions}/${expectedCount} ended goal_satisfied; completion reasons: ${completionReasons}`;
+    return `${passedSessions}/${plural(expectedCount, "actor session")} passed credibility checks; mission endpoint: ${goalSatisfiedSessions}/${expectedCount} ended goal_satisfied; completion reasons: ${completionReasons}`;
 }
 /** The run's first two events: its creation and the shared plane's provenance. */
 function planeEvents(args, external) {
@@ -97,7 +98,7 @@ function planeEvents(args, external) {
         at: createdAt,
         level: "info",
         type: "concurrent-shared-world.run.created",
-        message: `Created CONCURRENT shared-world run for ${plan.labId} (actor ${descriptor.id}, ${actorSpecs.length} persona(s) vs ONE shared plane, max ${plan.concurrency} concurrent).`,
+        message: `Created a concurrent shared-world run for ${plan.studyId} (actor ${descriptor.id}, ${plural(actorSpecs.length, "persona")} on one shared app, at most ${plan.concurrency} at once).`,
     });
     // Human-readable plane label, byte-stable for the clone route. local-tree has no repo slug: it
     // labels the packed archive instead (archiveSha256 + dirty/clean when the packed root was a git
@@ -111,7 +112,7 @@ function planeEvents(args, external) {
     // External-public plane provenance differs: an operator-declared, operator-owned public
     // deployment humanish neither provisioned nor seeded, with no getHost, no clone and no synthetic
     // attestation (claiming synthetic on a real site is a lie). The origin persists digest-only.
-    // planSharedWorldLab refuses an external-public plane without a declared owner; the fallback
+    // planSharedWorldStudy refuses an external-public plane without a declared owner; the fallback
     // says so rather than naming one.
     const externalPlaneOwner = plan.plane.kind === "external-public" ? plan.plane.owner : "(undeclared)";
     events.push(participantEvent(actorSpecs[0] ?? participantIds(0), {
@@ -120,19 +121,21 @@ function planeEvents(args, external) {
         level: "info",
         type: "concurrent-shared-world.plane.provenance",
         message: external
-            ? `Shared plane: an EXTERNAL-PUBLIC deployment (operator-attested owner ${externalPlaneOwner}, authorized) used DIRECTLY as the shared plane, with NO getHost, clone, subject sandbox, or seed. The harness OBSERVES that each participant reached the operator-declared origin (publicOriginDigest); it did NOT mint or control the plane. Author-trust ownership attestation, NOT a synthetic-data claim.`
+            ? `Shared app: a public deployment the operator declares they own (${externalPlaneOwner}, authorized), used as it is, with no sandbox, clone or seed. humanish observed that each participant reached the declared origin (publicOriginDigest); it did not create or control the app. Ownership is the study's declaration, and the data is not claimed to be synthetic.`
             : dryRun
-                ? `Shared plane declared: ${dryRunPlaneLabel}, served + getHost-exposed in-sandbox (dry-run contract; nothing ${args.subject.source === "local-tree" ? "packed" : "cloned"}). Seed recipe ${args.seedDigest}; SYNTHETIC subject (author-attested); env names: ${args.subject.envNames?.join(", ") || "none"} (values never persisted).`
-                : `Shared plane: ${livePlaneLabel}, served + exposed at the harness-minted getHost URL; seed recipe ${args.seedDigest}; SYNTHETIC subject (author-attested); env names: ${args.subject.envNames?.join(", ") || "none"} (values never persisted).`,
+                ? `Shared app declared: ${dryRunPlaneLabel}, to be served in the sandbox at a public sandbox URL (dry run: nothing ${args.subject.source === "local-tree" ? "packed" : "cloned"}). Seed recipe ${args.seedDigest}; synthetic subject, as the study declares; env names: ${args.subject.envNames?.join(", ") || "none"} (values never stored).`
+                : `Shared app: ${livePlaneLabel}, served at a public sandbox URL humanish created; seed recipe ${args.seedDigest}; synthetic subject, as the study declares; env names: ${args.subject.envNames?.join(", ") || "none"} (values never stored).`,
     }));
     return events;
 }
-/** The sharedWorld block: seat windows, the state series, seat outcomes and the plane. */
+/** The sharedWorld block: participant windows, the state series, participant outcomes and the
+ *  plane. */
 function sharedWorldEvidence(args, external, inProgress, planeCommit) {
     const { plan, dryRun, actorSpecs, actorResults } = args;
     // Build the concurrent shared-world evidence block. routeHostDigest is sha256-16 of the origin each
-    // seat reached: on getHost the seat URL the actor drove (verify confirms == plane.hostDigest); on
-    // external-public the seat's CDP-OBSERVED URL origin (verify confirms == plane.publicOriginDigest).
+    // participant reached: on getHost the participant URL the actor drove (verify confirms ==
+    // plane.hostDigest); on external-public the participant's CDP-observed URL origin (verify
+    // confirms == plane.publicOriginDigest).
     const fallbackHostDigest = external
         ? (args.publicOriginDigest ?? commandDigestOf("[external-public-plane]"))
         : (args.hostDigest ?? commandDigestOf("[provisioned-subject]"));
@@ -189,7 +192,7 @@ function sharedWorldEvidence(args, external, inProgress, planeCommit) {
             seedDigest: args.seedDigest,
             envNames: [],
             // publicOriginDigest is the observed convergence origin; declaredOriginDigest records the
-            // operator-declared origin for reference (a redirect makes them differ — not a failure).
+            // operator-declared origin for reference (a redirect that makes them differ is no failure).
             ...(args.publicOriginDigest === undefined
                 ? {}
                 : { publicOriginDigest: args.publicOriginDigest }),
@@ -226,8 +229,8 @@ function sharedWorldEvidence(args, external, inProgress, planeCommit) {
     return { sharedWorld, windows, stateSeries, outcomes };
 }
 /**
- * A finished run's gaps: each seat that did not pass, or, when every seat passed, the world
- * shortfall that failed the run.
+ * A finished run's gaps: each participant that did not pass, or, when every participant passed, the
+ * world shortfall that failed the run.
  */
 function finishedGaps(actorResults, shortfall) {
     const participantGaps = actorResults
@@ -247,12 +250,12 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
     const deltas = (stateSeries ?? []).filter((snapshot, i) => i > 0 && snapshot.digest !== (stateSeries ?? [])[i - 1].digest).length;
     const stateSeriesLabel = external
         ? "stateSeries omitted (no authoritative shared-state proof on the external-public plane)"
-        : `stateSeries ${(stateSeries ?? []).length} snapshot(s), ${deltas} delta(s)`;
+        : `stateSeries ${plural((stateSeries ?? []).length, "snapshot")}, ${plural(deltas, "delta")}`;
     const convergenceLabel = external
-        ? `; lobby convergence ${args.lobbyConvergenceDigest ? "PROVEN (all participants reached one /lobby/CODE)" : "not observed"}`
+        ? `; lobby convergence ${args.lobbyConvergenceDigest ? "shown (all participants reached one /lobby/CODE)" : "not observed"}`
         : "";
     // The count that matters is how many participants were live at once, which can be fewer than exist:
-    // a 6-participant run capped at 3 must never read as 6-wide concurrency (#350, the field failure).
+    // a 6-participant run capped at 3 must never read as 6-wide concurrency.
     const capForReport = plan.concurrency;
     const maxLive = maxSimultaneousWindows(windows);
     events.push({
@@ -260,11 +263,11 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
         at: createdAt,
         level: "info",
         type: "concurrent-shared-world.concurrency",
-        message: `Concurrency: ${windows.length} participant(s)${dryRun ? " (dry-run contract; $0)" : `, up to ${maxLive} live at once (cap ${capForReport}), overlap ${overlaps ? "PROVEN" : "not observed"}`}; ${stateSeriesLabel}${convergenceLabel}. Attribution ceiling: ${sharedWorld.attributionLimits.join(", ")}. ${dryRun ? "This contract-only run proves no live concurrency, scale, or adoption." : "This run reports only its own observed overlap and state changes; it does not prove scale, repeatability, or adopter-harness replacement."}`,
+        message: `Concurrency: ${plural(windows.length, "participant")}${dryRun ? " (dry run; $0)" : `, up to ${maxLive} live at once (cap ${capForReport}), overlap ${overlaps ? "shown" : "not observed"}`}; ${stateSeriesLabel}${convergenceLabel}. Attribution ceiling: ${sharedWorld.attributionLimits.join(", ")}. ${dryRun ? "This dry run proves nothing about live concurrency, scale, or adoption." : "This run reports only its own observed overlap and state changes; it does not prove scale, repeatability, or adopter-harness replacement."}`,
     });
-    // The judge's verdict (judgeSharedWorld): every seat produced a terminal, engaged, passed session.
-    // Mission endpoint and completion reasons are reported separately below; `outcomes[].ok` is not
-    // renamed into mission success (#364).
+    // The judge's verdict (judgeSharedWorld): every participant produced a terminal, engaged, passed
+    // session. Mission endpoint and completion reasons are reported separately below; `outcomes[].ok`
+    // is not renamed into mission success.
     const verdict = args.judgment.verdict;
     const actorOutcomeSummary = formatSharedWorldActorOutcomes(outcomes, actorSpecs.length);
     const review = {
@@ -272,19 +275,19 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
         verdict,
         // Plane-class-aware: the external-public plane has no getHost/clone/seed and carries no
         // authoritative state series, so its summary must not claim a getHost-exposed plane (dry-run) nor
-        // report "state delta(s) under load" (live) — it reports lobby convergence instead.
+        // report "state delta(s) under load" (live). It reports lobby convergence instead.
         summary: dryRun
             ? external
-                ? `Dry-run concurrent shared-world contract: ${actorSpecs.length} persona(s) declared against ONE external-public shared plane (a real public deployment used directly; no getHost/clone/seed); no sandboxes launched, $0 spend.`
-                : `Dry-run concurrent shared-world contract: ${actorSpecs.length} persona(s) declared against ONE getHost-exposed plane (${descriptor.id}); no sandboxes launched, $0 spend.`
+                ? `Concurrent shared-world dry run: ${plural(actorSpecs.length, "persona")} declared against one public deployment, used as it is (no sandbox, clone or seed); no sandboxes launched, $0 spent.`
+                : `Concurrent shared-world dry run: ${plural(actorSpecs.length, "persona")} declared against one app served at a public sandbox URL (${descriptor.id}); no sandboxes launched, $0 spent.`
             : inProgress
-                ? `In-progress concurrent shared-world Observer snapshot: ${actorSpecs.length} persona(s) running against ONE shared plane; final verification is pending.`
+                ? `In-progress concurrent shared-world Observer snapshot: ${plural(actorSpecs.length, "persona")} running against one shared app; final verification is pending.`
                 : external
-                    ? `Concurrent shared-world (ONE external-public plane, ${actorSpecs.length} simultaneous personas): swarm ${verdict === "pass" ? "ran coherently" : "did not run coherently"}; ${actorOutcomeSummary}; overlap ${overlaps ? "proven" : "not observed"}; ${args.lobbyConvergenceDigest ? `${actorSpecs.length} participants converged on one lobby` : "lobby convergence not observed"}.`
-                    : `Concurrent shared-world (ONE plane, ${actorSpecs.length} simultaneous personas): swarm ${verdict === "pass" ? "ran coherently" : "did not run coherently"}; ${actorOutcomeSummary}; overlap ${overlaps ? "proven" : "not observed"}; ${deltas} state delta(s) under load.`,
+                    ? `Concurrent shared-world (one public deployment, ${actorSpecs.length} personas at once): swarm ${verdict === "pass" ? "ran coherently" : "did not run coherently"}; ${actorOutcomeSummary}; overlap ${overlaps ? "proven" : "not observed"}; ${args.lobbyConvergenceDigest ? `${actorSpecs.length} participants converged on one lobby` : "lobby convergence not observed"}.`
+                    : `Concurrent shared-world (one shared app, ${actorSpecs.length} personas at once): swarm ${verdict === "pass" ? "ran coherently" : "did not run coherently"}; ${actorOutcomeSummary}; overlap ${overlaps ? "proven" : "not observed"}; ${plural(deltas, "state delta")} under load.`,
         gaps: dryRun
             ? [
-                "This dry-run launched no concurrent shared-world session; it proves contract shape only, not live behavior, scale, or adopter-harness replacement.",
+                "This dry run launched no concurrent shared-world session; it checks the evidence shape only, not live behavior, scale, or adopter-harness replacement.",
             ]
             : inProgress
                 ? [
@@ -301,7 +304,7 @@ export function buildConcurrentSharedWorldBundle(args) {
     const external = (args.planeClass ?? "provisioned-getHost") === "external-public";
     const simulations = [];
     const streams = [];
-    // Public-safe label only — neither the raw getHost URL (provisioned) nor the raw public origin
+    // Public-safe label only: neither the raw getHost URL (provisioned) nor the raw public origin
     // (external-public) lands in the bundle. The plane identity is a digest (plane.hostDigest on
     // getHost; plane.publicOriginDigest on external-public).
     const appUrl = external ? "[external-public-plane]" : "[provisioned-subject]";
@@ -331,23 +334,23 @@ export function buildConcurrentSharedWorldBundle(args) {
         persona: {
             id: actorSpecs[0]?.persona.id ?? "concurrent-persona",
             name: `Concurrent shared-world swarm (${actorSpecs.length} personas)`,
-            source: `lab:${plan.labId}`,
+            source: `study:${plan.studyId}`,
             sourceDigest: actorSpecs[0]?.persona.promptDigest ?? args.seedDigest,
         },
         scenario: {
-            id: `concurrent-shared-world-${plan.labId}`,
-            title: plan.title ?? `Concurrent shared-world: ${plan.labId}`,
+            id: `concurrent-shared-world-${plan.studyId}`,
+            title: plan.title ?? `Concurrent shared-world: ${plan.studyId}`,
             goal: redactText(actorSpecs[0]?.evidenceInstructions ??
                 actorSpecs[0]?.instructions ??
                 "Concurrent shared-world interaction."),
-            source: `lab:${plan.labId}`,
+            source: `study:${plan.studyId}`,
             sourceDigest: actorSpecs[0]?.persona.promptDigest ?? args.seedDigest,
         },
         lifecycle: [
             {
                 at: createdAt,
                 event: "concurrent-shared-world.run.created",
-                message: `Created concurrent shared-world run with ONE shared plane and ${actorSpecs.length} simultaneous participants (actor ${descriptor.id}).`,
+                message: `Created a concurrent shared-world run with one shared app and ${actorSpecs.length} participants at once (actor ${descriptor.id}).`,
             },
         ],
         simulations,
@@ -357,11 +360,11 @@ export function buildConcurrentSharedWorldBundle(args) {
             status: "passed",
             notes: ranLive
                 ? anyRaw
-                    ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Some personas captured FULL-FIDELITY (raw) screenshots, retained for local use — NOT redacted for publishing; set policies.redactScreenshots: true to blur a share-as-is bundle. stateSeries persists digest-only."
+                    ? "Typed text is recorded as its length only, and reasoning and messages pass through text redaction. Some personas captured unblurred screenshots, kept for local use and not redacted for publishing. Set policies.redactScreenshots: true to blur screenshots in a bundle you plan to share. stateSeries stores digests only."
                     : "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are blurred at capture (policies.redactScreenshots: true) for a share-as-is bundle. stateSeries persists digest-only."
                 : inProgress
                     ? "In-progress live Observer snapshot: runtime stream auth URLs are process-local only and are not persisted. Final typed text, traces, and screenshots are pending. stateSeries persists digest-only."
-                    : "Dry-run concurrent shared-world contract bundle: no sandboxes launched and no screenshots captured. Typed text is recorded as length only and reasoning/messages pass through text redaction whenever a session runs. stateSeries persists digest-only.",
+                    : "Concurrent shared-world dry-run bundle: no sandboxes launched and no screenshots captured. Typed text is recorded as length only and reasoning/messages pass through text redaction whenever a session runs. stateSeries persists digest-only.",
         },
         artifacts: bundleArtifacts(),
         review,
@@ -429,7 +432,7 @@ export function renderConcurrentReviewMarkdown(bundle) {
         `- attribution class: ${bundle.attributionClass ?? "isolated"}`,
         `- topology: ${sw?.topology ?? "(none)"} / ${sw?.topologyMode ?? "(none)"}`,
         `- personas: ${sw?.roleCount ?? 0}`,
-        `- verdict: ${bundle.review.verdict}`,
+        `- verdict: ${verdictText(bundle.review.verdict, bundle.mode)}`,
         `- summary: ${bundle.review.summary}`,
         ...(plane ? [`- plane: ${plane.message}`] : []),
         ...(concurrency ? [`- concurrency: ${concurrency.message}`] : []),

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

@@ -1,6 +1,6 @@
 import type { Shell } from "../../substrates/shell.js";
 import { type DetachedTimers } from "../../substrates/detached.js";
-import { type LabSubjectState, type LabSubjectStateCheckpoint } from "../../lab/types.js";
+import { type StudySubjectState, type StudySubjectStateCheckpoint } from "../../study/types.js";
 import { type SharedWorldCheckpoint } from "../../run/shared-world-evidence.js";
 /** Combine a snapshot's per-probe digests into one sha256-16 (digest-only; no raw value). */
 export declare function combineCheckpointDigest(parts: string[]): string;
@@ -8,18 +8,18 @@ export declare function combineCheckpointDigest(parts: string[]): string;
  * Run one checkpoint snapshot live: each declared probe runs read-only via the detached
  * primitive; its stdout is literal-scrubbed (provisioned values + the probe's declared redact
  * literals, folded into `scrub`) then pattern-redacted, then digested. Only the combined digest
- * persists — never the raw value (the seed-step lockdown). Unique step names per snapshot prevent
+ * persists, never the raw value (the seed-step lockdown). Unique step names per snapshot prevent
  * stale-status reuse across snapshots.
  */
 export declare function runCheckpointSnapshot(args: {
     shell: Shell;
     snapshotIndex: number;
     name: string;
-    checkpoints: LabSubjectStateCheckpoint[];
+    checkpoints: StudySubjectStateCheckpoint[];
     prevDigest: string | undefined;
     scrub: (text: string) => string;
     requestTimeoutMs: number;
     timers: DetachedTimers;
 }): Promise<SharedWorldCheckpoint>;
 /** sha256-16 over the ordered seed-step command digests: the seeded-state recipe identity. */
-export declare function seedRecipeDigest(state: LabSubjectState | undefined): string;
+export declare function seedRecipeDigest(state: StudySubjectState | undefined): string;

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

@@ -1,7 +1,7 @@
 import { commandDigestOf } from "../../subject/state.js";
 import { SUBJECT_DIR } from "../../subject/steps.js";
 import { runDetachedStep } from "../../substrates/detached.js";
-import {} from "../../lab/types.js";
+import {} from "../../study/types.js";
 import { redactText } from "../../evidence/redaction.js";
 import {} from "../../run/shared-world-evidence.js";
 // Per-checkpoint probe budget (read-only aggregate probes are fast).
@@ -14,7 +14,7 @@ export function combineCheckpointDigest(parts) {
  * Run one checkpoint snapshot live: each declared probe runs read-only via the detached
  * primitive; its stdout is literal-scrubbed (provisioned values + the probe's declared redact
  * literals, folded into `scrub`) then pattern-redacted, then digested. Only the combined digest
- * persists — never the raw value (the seed-step lockdown). Unique step names per snapshot prevent
+ * persists, never the raw value (the seed-step lockdown). Unique step names per snapshot prevent
  * stale-status reuse across snapshots.
  */
 export async function runCheckpointSnapshot(args) {

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

@@ -1,53 +1,53 @@
 import { type ReceivingSource } from "../../comms/receiving-runtime.js";
-import type { SharedWorldPlan } from "../../lab/plan-types.js";
+import type { SharedWorldPlan } from "../../study/plan-types.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
 import { type DeployedCommsCatch } from "../../comms/sandbox-catch.js";
-import type { LabCommsEmail, LabConfig } from "../../lab/types.js";
+import type { StudyCommsEmail, StudyConfig } from "../../study/types.js";
 import type { Shell } from "../../substrates/shell.js";
 import type { ConcurrentSharedWorldPlaneClass, ExternalCommsWiring, PlaneContext } from "./types.js";
-/** The in-sandbox email catch a provisioned plane deploys, when the lab declares one. */
+/** The in-sandbox email catch a provisioned plane deploys, when the study declares one. */
 export interface SubjectComms {
-    email: LabCommsEmail | undefined;
+    email: StudyCommsEmail | undefined;
     port: number | undefined;
     /** The catch's base URL, injected into the subject sandbox's env at create. */
     env: Record<string, string>;
 }
-export declare function subjectCommsOf(config: Pick<LabConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass): SubjectComms;
+export declare function subjectCommsOf(config: Pick<StudyConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass): SubjectComms;
 /**
- * Adopter-hosted ingress (#328): on the external-public plane the harness provisions nothing, so
+ * 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 declare function prepareExternalComms(config: Pick<LabConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass, dryRun: boolean, warnings: string[], env: Record<string, string | undefined>): Promise<{
+export declare function prepareExternalComms(config: Pick<StudyConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass, dryRun: boolean, warnings: string[], env: Record<string, string | undefined>): Promise<{
     ok: true;
     wiring: ExternalCommsWiring | undefined;
 } | {
     ok: false;
-    code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_TOKEN_INVALID" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE";
+    code: "HUMANISH_SHARED_WORLD_COMMS_TOKEN_INVALID" | "HUMANISH_SHARED_WORLD_COMMS_CATCH_UNREACHABLE";
     message: string;
 }>;
 /**
- * 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
  * never blocks teardown (invariant: all sandboxes torn down by id in the plane's finally). Returns
  * the thread's path when one was written.
  */
-export declare function drainSubjectComms(ctx: PlaneContext, commsEmail: LabCommsEmail, subjectShell: Shell, deployedComms: DeployedCommsCatch): Promise<string | undefined>;
+export declare function drainSubjectComms(ctx: PlaneContext, commsEmail: StudyCommsEmail, subjectShell: Shell, deployedComms: DeployedCommsCatch): Promise<string | 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 declare function drainExternalComms(ctx: PlaneContext, comms: ExternalCommsWiring): Promise<string | undefined>;
-/** What receiving guards: the lab's email declaration and the subject env names and values. */
+/** What receiving guards: the study's email declaration and the subject env names and values. */
 export declare function receivingSourceOf(residual: SharedWorldPlan["residual"], env: readonly string[]): ReceivingSource;
 /**
- * Real email receiving, when the lab declares it on a live run. It registers the connection's
+ * Real email receiving, when the study declares it on a live run. It registers the connection's
  * secrets with the run's scrub before any desktop starts. Returns the message the run fails with
  * when setup fails.
  */

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

@@ -1,5 +1,5 @@
 // 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";
@@ -7,10 +7,11 @@ import { prepareReceivingRun } from "../../comms/receiving-runtime.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
+import { addressedRecipients } from "../../study/parse/comms.js";
+import { plural } from "../../run/text.js";
+// 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
+// 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. Unavailable on the
 // external-public plane (the app is an operator-owned deployment the harness never provisions).
@@ -19,7 +20,7 @@ export function subjectCommsOf(config, planeClass) {
         ? 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}` }
@@ -27,7 +28,7 @@ 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
+ * 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
@@ -40,7 +41,7 @@ export async function prepareExternalComms(config, planeClass, dryRun, warnings,
     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 };
@@ -49,23 +50,23 @@ export async function prepareExternalComms(config, planeClass, dryRun, warnings,
     if (tokenRefusal !== undefined)
         return {
             ok: false,
-            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_TOKEN_INVALID",
+            code: "HUMANISH_SHARED_WORLD_COMMS_TOKEN_INVALID",
             message: tokenRefusal,
         };
-    // Fail closed before any actor sandbox is created: a comms lab whose catch is unreachable
+    // Fail closed before any actor sandbox is created: a comms study 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_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE",
+            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
  * never blocks teardown (invariant: all sandboxes torn down by id in the plane's finally). Returns
@@ -91,11 +92,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 ${plural(collected.captured, "email send")}, 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) {
@@ -104,8 +105,8 @@ 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.
  */
@@ -120,7 +121,7 @@ export async function drainExternalComms(ctx, comms) {
     ctx.warnings.push(...warnings);
     return path;
 }
-/** What receiving guards: the lab's email declaration and the subject env names and values. */
+/** What receiving guards: the study's email declaration and the subject env names and values. */
 export function receivingSourceOf(residual, env) {
     const { comms } = residual;
     const { envValues } = residual.subject;
@@ -130,7 +131,7 @@ export function receivingSourceOf(residual, env) {
     };
 }
 /**
- * Real email receiving, when the lab declares it on a live run. It registers the connection's
+ * Real email receiving, when the study declares it on a live run. It registers the connection's
  * secrets with the run's scrub before any desktop starts. Returns the message the run fails with
  * when setup fails.
  */

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

@@ -13,9 +13,10 @@ export interface ExternalPublicPlaneOutcome {
 /**
  * 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 (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).
+ * 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";
@@ -15,9 +16,10 @@ import { participantRunDeps, startParticipantFlush } from "./participant-specs.j
 /**
  * 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 (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).
+ * 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;
@@ -35,8 +37,9 @@ export async function runExternalPublicPlane(ctx, live, inbox) {
         timeoutMs: ctx.timeoutMs,
         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.
+        // 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,
     });
@@ -62,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({

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

@@ -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;
@@ -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;