humanish 0.107.0 → 0.108.0

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;

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

@@ -1,10 +1,10 @@
-// The external-public plane's host-first handoff. The host seat opens a lobby; each follower waits
+// The external-public plane's host-first handoff. The host opens a lobby; each follower waits
 // for the host's lobby code, read from the host's URL, narration or screen, and then joins with it.
 // A follower fails closed without opening if the host never yields a code within the deadline.
 //
-// Temporary shim (tracked by #296): this CDP URL-relay handoff reads the host's /lobby/CODE off its
+// Temporary shim: this CDP URL-relay handoff reads the host's /lobby/CODE off its
 // own browser and threads it into the follower missions.
-// It is to be augmented/replaced by the actor message bus (fake SMS/email invite) in #297: the
+// It is to be augmented/replaced by the actor message bus (fake SMS/email invite): the
 // human-realistic version is the host sending the invite link and followers receiving and tapping
 // it, rather than the orchestrator relaying the code out-of-band.
 import { commandDigestOf } from "../../subject/state.js";
@@ -15,23 +15,24 @@ import { runCuaParticipant } from "../computer-use/participant-execution.js";
 import { extractLobbyCode, extractLobbyCodeFromNarration } from "./lobby-code.js";
 import { hostOriginDigest } from "./provenance.js";
 import { makeBlockedFollowerOutcome, withLobbyCodeMission, } from "./participant-specs.js";
-// The floor for the host-first handoff barrier deadline (ms). The host seat must surface a
+// The floor for the host-first handoff barrier deadline (ms). The host must surface a
 // shared-session (/lobby/CODE) URL within the deadline or the run fails closed and no follower
-// opens. The effective deadline scales with the per-seat run budget (execution.timeoutMs): a fixed
-// 2 min is too tight for a real create-a-lobby flow on a mobile-layout seat once you subtract the
-// seat's own desktop provisioning — the host reaches /lobby/CODE, but after the followers already
-// gave up. So use max(floor, 40% of the budget), capped at the budget. The latch resolves the
-// instant the host actually reaches /lobby, so a generous ceiling only affects the fail-closed case.
+// opens. The effective deadline scales with the per-participant run budget (execution.timeoutMs): a
+// fixed 2 min is too tight for a real create-a-lobby flow on a mobile-layout participant once you
+// subtract the participant's own desktop provisioning: the host reaches /lobby/CODE, but after the
+// followers already gave up. So use max(floor, 40% of the budget), capped at the budget. The latch
+// resolves the instant the host actually reaches /lobby, so a generous ceiling only affects the
+// fail-closed case.
 const DEFAULT_HANDOFF_DEADLINE_MS = 120_000;
 const HANDOFF_DEADLINE_BUDGET_FRACTION = 0.4;
-// Per-seat runaway backstop for the vision-off-frame lobby-code read (used by the host to latch the
-// handoff code, and by each follower to independently observe its own code for the convergence proof):
-// at most this many single-frame reads before the seat is assumed to be somewhere without a code. Each
-// reader stops the instant it has what it needs, so in practice only a handful fire (a seat reaches its
-// /lobby within a few turns). NOTE: these reads are out-of-band OpenAI calls (external-public route
-// only) and are left out of execution.caps.maxUsd, so this hard cap is what bounds their spend
-// (each read is one cheap single-frame OCR call). If this route ever runs under a strict
-// budget, fold the estimate in.
+// Per-participant runaway backstop for the vision-off-frame lobby-code read (used by the host to
+// latch the handoff code, and by each follower to independently observe its own code for the
+// convergence proof): at most this many single-frame reads before the participant is assumed to be
+// somewhere without a code. Each reader stops the instant it has what it needs, so in practice only
+// a handful fire (a participant reaches its /lobby within a few turns). NOTE: these reads are
+// out-of-band OpenAI calls (external-public route only) and are left out of execution.caps.maxUsd,
+// so this hard cap is what bounds their spend (each read is one cheap single-frame OCR call). If
+// this route ever runs under a strict budget, fold the estimate in.
 const MAX_LOBBY_CODE_VISION_READS = 30;
 // Idle/no-progress backstop for the host participant specifically (default is 6/8). The host legitimately sits
 // on an unchanging waiting-room screen while followers provision and join; it must not give up first.
@@ -66,21 +67,23 @@ class HandoffTimeoutError extends Error {
     }
 }
 /**
- * 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 class LobbyHandoff {
     // Per-participant runtime-only observed state (never persisted raw): the last observed URL and the last
-    // observed /lobby/CODE per seat, fed by onObservedUrl. The URL is digested to its origin for each seat's
-    // routeHostDigest (no code leaks); the codes drive the cross-seat lobby-convergence digest.
+    // observed /lobby/CODE per participant, fed by onObservedUrl. The URL is digested to its origin
+    // for each participant's routeHostDigest (no code leaks); the codes drive the cross-participant
+    // lobby-convergence digest.
     observedFinalUrls;
     observedLobbyCodes;
     latchedLobbyCode;
     /** A follower gave up because the deadline passed. */
     timedOut = false;
-    /** Why the host seat ended without producing a lobby code. */
+    /** Why the host ended without producing a lobby code. */
     hostFailure;
     deadlineMs;
     lobbyCodeLatch = deferred();
@@ -133,11 +136,12 @@ export class LobbyHandoff {
         this.stopDeadline();
         this.lobbyCodeLatch.resolve(code);
     }
-    // Build an onScreenshot handler that vision-reads the lobby code off this seat's own frame (the
-    // CDP-independent observation). `done()` short-circuits once this seat has what it needs (the host
-    // once latched; a follower once it has recorded its own observed code), `onCode` records/latches the
-    // result. One read in flight at a time, bounded by MAX_LOBBY_CODE_VISION_READS so a seat that never
-    // reaches a lobby can't rack up unbounded calls (fire-and-forget; the loop never awaits it).
+    // Build an onScreenshot handler that vision-reads the lobby code off this participant's own frame
+    // (the CDP-independent observation). `done()` short-circuits once this participant has what it
+    // needs (the host once latched; a follower once it has recorded its own observed code), `onCode`
+    // records/latches the result. One read in flight at a time, bounded by
+    // MAX_LOBBY_CODE_VISION_READS so a participant that never reaches a lobby can't rack up unbounded
+    // calls (fire-and-forget; the loop never awaits it).
     makeLobbyCodeVisionReader(done, onCode) {
         let inFlight = false;
         let reads = 0;
@@ -184,32 +188,34 @@ export class LobbyHandoff {
             this.lobbyCodeLatch.reject(new Error(this.hostFailure));
         }
     }
-    /** The digest-only convergence proofs over what the seats observed. */
+    /** The digest-only convergence proofs over what the participants observed. */
     convergence(declaredOriginDigest) {
-        // Observed-origin convergence proof (blocker 2): the convergence claim is about what the seats
-        // observed. Digest each observing seat's origin and require one shared origin; that agreement is
-        // the convergence proof and becomes plane.publicOriginDigest. A normal
-        // cross-origin redirect (declared apex -> observed www) is therefore tolerated: the seats still
-        // converge on one observed origin. Leave it undefined (verify fails closed) only if the seats did
-        // not converge on a single observed origin (or none observed one).
+        // Observed-origin convergence proof: the convergence claim is about what the participants
+        // observed. Digest each observing participant's origin and require one shared origin; that
+        // agreement is the convergence proof and becomes plane.publicOriginDigest. A normal
+        // cross-origin redirect (declared apex -> observed www) is therefore tolerated: the
+        // participants still converge on one observed origin. Leave it undefined (verify fails closed)
+        // only if the participants did not converge on a single observed origin (or none observed one).
         const observedOriginDigests = this.observedFinalUrls
             .filter((url) => typeof url === "string" && url.length > 0)
             .map((url) => hostOriginDigest(url));
         const distinctObservedOrigins = new Set(observedOriginDigests);
         const publicOriginDigest = distinctObservedOrigins.size === 1
             ? [...distinctObservedOrigins][0]
-            : // Nothing observed (e.g. a handoff-timeout run where no seat ever navigated): fall back to the
-                // declared origin so a failed run's bundle stays structurally valid (every seat's route then
-                // digests to the declared origin too). The run still fails closed for its own reason
-                // (`HANDOFF_TIMEOUT`, no lobby convergence, no overlap-on-pass). Real divergence (≥2 distinct observed
-                // origins) leaves it undefined so verify fails closed on the non-convergence.
+            : // Nothing observed (e.g. a handoff-timeout run where no participant ever navigated): fall
+                // back to the declared origin so a failed run's bundle stays structurally valid (every
+                // participant's route then digests to the declared origin too). The run still fails
+                // closed for its own reason (`HANDOFF_TIMEOUT`, no lobby convergence, no
+                // overlap-on-pass). Real divergence (≥2 distinct observed origins) leaves it undefined so
+                // verify fails closed on the non-convergence.
                 distinctObservedOrigins.size === 0
                     ? declaredOriginDigest
                     : undefined;
-        // Lobby-convergence proof: a digest of the shared /lobby/CODE path iff every seat converged on the
-        // same code (a follower stuck on "/" yields no code, so no false convergence). Digest-only.
-        // observedLobbyCodes may be a sparse array (a seat that never observed a code leaves a hole), and
-        // Array.prototype.every skips holes, so count the defined codes explicitly instead of every().
+        // Lobby-convergence proof: a digest of the shared /lobby/CODE path iff every participant
+        // converged on the same code (a follower stuck on "/" yields no code, so no false convergence).
+        // Digest-only. observedLobbyCodes may be a sparse array (a participant that never observed a
+        // code leaves a hole), and Array.prototype.every skips holes, so count the defined codes
+        // explicitly instead of every().
         const definedCodes = this.observedLobbyCodes.filter((code) => code !== undefined);
         const distinctCodes = new Set(definedCodes);
         const lobbyConvergenceDigest = distinctCodes.size === 1 && definedCodes.length === this.observedLobbyCodes.length
@@ -218,7 +224,7 @@ export class LobbyHandoff {
         return { publicOriginDigest, lobbyConvergenceDigest };
     }
 }
-// Adopter-hosted inbox (#387): the persona is told its address and inbox URL on this plane.
+// Adopter-hosted inbox: the persona is told its address and inbox URL on this plane.
 function withParticipantInbox(spec, inbox) {
     return inbox && participantHasInboxRecipient(inbox.email, spec.planned.id)
         ? withInboxMission(spec, inbox.inboxUrl, inboxRecipientFor(inbox.email, spec.planned.id)?.address)
@@ -235,11 +241,11 @@ function withParticipantInbox(spec, inbox) {
 // (host + up to concurrency-1 followers), preserving the spend cap.
 export async function runHost(handoff, deps, spec, participantIndex) {
     const onObservedUrl = handoff.makeObservedUrl(participantIndex, true);
-    // CDP-INDEPENDENT handoff paths (the E2B-desktop CDP url-read the onObservedUrl path relies on is
+    // CDP-independent handoff paths (the E2B-desktop CDP url-read the onObservedUrl path relies on is
     // unreliable in practice). Two backups, both resolving the same latch; whichever sees the code first
     // wins, all digest-only:
     //   (1) onMessage: scan the host's own narration if it happens to state the lobby URL; and
-    //   (2) onScreenshot — vision-read the code straight off the host's waiting-room frame. This is the
+    //   (2) onScreenshot: vision-read the code straight off the host's waiting-room frame. This is the
     //       robust one: the code is rendered on screen even when CDP fails and when the host never
     //       narrates it, and the host is never asked to announce anything, so it keeps
     //       running (create -> wait for players -> Start -> play) instead of ending on a stray message.
@@ -256,7 +262,8 @@ export async function runHost(handoff, deps, spec, participantIndex) {
     // followers provision their own desktops and walk the Join flow (easily 15-30 turns of an
     // unchanging "waiting for players" screen). At the default idle backstop (6) the host would give up
     // before anyone arrives, orphaning the lobby (exactly the earlier failure). Raise the host's idle /
-    // no-progress tolerance so it waits patiently; the per-seat timeout still bounds a truly stuck host.
+    // no-progress tolerance so it waits patiently; the per-participant timeout still bounds a truly
+    // stuck host.
     const hostSpec = {
         ...withParticipantInbox(spec, deps.inbox),
         backstop: {
@@ -310,9 +317,10 @@ export async function runFollower(handoff, deps, spec, participantIndex) {
             route: deps.publicAppUrl,
         };
     }
-    // Followers also idle-wait — in the waiting room until the host starts, and between rounds. Raise
+    // Followers also idle-wait: in the waiting room until the host starts, and between rounds. Raise
     // their idle backstop too (less than the host's: they wait less), so a follower that joins ahead of
-    // the other does not give up before the game begins. Per-seat timeout still bounds a stuck follower.
+    // the other does not give up before the game begins. Per-participant timeout still bounds a stuck
+    // follower.
     const followerSpec = {
         ...withLobbyCodeMission(withParticipantInbox(spec, deps.inbox), code),
         backstop: {
@@ -321,12 +329,12 @@ export async function runFollower(handoff, deps, spec, participantIndex) {
         },
     };
     // Independently observe this follower's own lobby code by vision-reading its waiting-room frame,
-    // and record it for the cross-seat convergence proof. This latches nothing (followers gate on the
-    // host's code). It fills this seat's observedLobbyCodes slot from a
-    // reliable signal instead of the flaky CDP url-read, so lobbyConvergenceDigest can prove all seats
-    // reached the same /lobby/CODE. If a follower somehow joined another lobby, it reads a different
-    // code and convergence correctly fails (no false proof); if it never reads one, the seat stays a
-    // hole and convergence is honestly "not observed" for that seat.
+    // and record it for the cross-participant convergence proof. This latches nothing (followers gate
+    // on the host's code). It fills this participant's observedLobbyCodes slot from a
+    // reliable signal instead of the flaky CDP url-read, so lobbyConvergenceDigest can prove all
+    // participants reached the same /lobby/CODE. If a follower somehow joined another lobby, it reads
+    // a different code and convergence correctly fails (no false proof); if it never reads one, the
+    // participant stays a hole and convergence is recorded as "not observed" for that participant.
     const onScreenshot = handoff.makeLobbyCodeVisionReader(() => handoff.observedLobbyCodes[participantIndex] !== undefined, (observed) => {
         handoff.observedLobbyCodes[participantIndex] = observed;
     });

package/dist/routes/shared-world/lobby-code.d.ts

@@ -1,12 +1,12 @@
 /** Extract the shared-session code from a (runtime-only) observed URL, or undefined. Exported for the
- *  handoff regex table test — pure, no side effects, never persists its input. */
+ *  handoff regex table test. Pure, no side effects, never persists its input. */
 export declare function extractLobbyCode(url: string | undefined): string | undefined;
 export declare function extractLobbyCodeFromNarration(text: string | undefined): string | undefined;
 /** Pull the assistant's plain text out of an OpenAI Responses API body (`output_text` convenience
  *  field, else the concatenated `output[].content[].text`). Tolerant of shape drift; pure. */
 export declare function extractResponsesOutputText(parsed: unknown): string | undefined;
 /** Parse a vision reply into a lobby code. Precision-first: accept only when the whole reply is the
- *  six-character code, or when it echoes an explicit /lobby/CODE — never a bare 6-letter token buried in
+ *  six-character code, or when it echoes an explicit /lobby/CODE; never a bare 6-letter token buried in
  *  prose (e.g. "I see a home `SCREEN`"), because a wrong latch fails the entire run, whereas a miss just
  *  retries on the next frame while the host keeps waiting. `NONE` (the instructed "no code" reply) is
  *  rejected. Pure. */

package/dist/routes/shared-world/lobby-code.js

@@ -1,15 +1,15 @@
-// Reads a lobby code (the /lobby/CODE path segment) from a URL, from a seat's narration or, through
-// a vision model call, from a seat's screenshot. The external-public plane uses it to hand the
-// host's lobby to the followers.
+// Reads a lobby code (the /lobby/CODE path segment) from a URL, from a participant's narration or,
+// through a vision model call, from a participant's screenshot. The external-public plane uses it
+// to hand the host's lobby to the followers.
 import { OPENAI_RESPONSES_URL } from "../../actors/openai-endpoint.js";
 /**
  * The lobby-trivia (and general "/lobby/CODE") shared-session URL matcher. A code is exactly 6 chars of
- * the [A-Z2-9] class; a locale prefix (/en/lobby/…) and a query/hash suffix are tolerated. RUNTIME-ONLY
+ * the [A-Z2-9] class; a locale prefix (/en/lobby/…) and a query/hash suffix are tolerated. Runtime-only
  * input (a live location.href); only the extracted code is used, and it lands only as a digest.
  */
 const LOBBY_CODE_PATTERN = /\/lobby\/([A-Z2-9]{6})(?:$|[/?#])/;
 /** Extract the shared-session code from a (runtime-only) observed URL, or undefined. Exported for the
- *  handoff regex table test — pure, no side effects, never persists its input. */
+ *  handoff regex table test. Pure, no side effects, never persists its input. */
 export function extractLobbyCode(url) {
     if (typeof url !== "string")
         return undefined;
@@ -19,8 +19,8 @@ export function extractLobbyCode(url) {
 /**
  * Extract a lobby code from free-form actor narration (the host's reasoning/message where it states
  * the lobby URL it sees), where the /lobby/CODE is followed by arbitrary prose (a space, backtick,
- * newline) rather than end-of-string or /?# — so the strict LOBBY_CODE_PATTERN would miss it. Uses a
- * negative-lookahead boundary (exactly 6 code chars). This is the CDP-INDEPENDENT handoff path: the
+ * newline) rather than end-of-string or /?#, so the strict LOBBY_CODE_PATTERN would miss it. Uses a
+ * negative-lookahead boundary (exactly 6 code chars). This is the CDP-independent handoff path: the
  * host reads the code on screen and states it, and this reads it from the model's own text. Pure;
  * input is runtime-only; only the code is used (as a digest).
  */
@@ -68,7 +68,7 @@ export function extractResponsesOutputText(parsed) {
     return parts.length > 0 ? parts.join("\n") : undefined;
 }
 /** Parse a vision reply into a lobby code. Precision-first: accept only when the whole reply is the
- *  six-character code, or when it echoes an explicit /lobby/CODE — never a bare 6-letter token buried in
+ *  six-character code, or when it echoes an explicit /lobby/CODE; never a bare 6-letter token buried in
  *  prose (e.g. "I see a home `SCREEN`"), because a wrong latch fails the entire run, whereas a miss just
  *  retries on the next frame while the host keeps waiting. `NONE` (the instructed "no code" reply) is
  *  rejected. Pure. */
@@ -89,7 +89,7 @@ const LOBBY_CODE_VISION_PROMPT = "This is a screenshot of a the example multipla
     "exactly those 6 characters in uppercase and NOTHING else (no words, no punctuation). If no lobby " +
     "code is visible on this screen (e.g. it is the home screen or a game round), reply exactly NONE.";
 // A single-frame OCR-style read. gpt-5.5 (the computer-use default) is used deliberately: it reliably reads the
-// 6-char code off a dense MOBILE-viewport waiting room — a smaller/cheaper model (gpt-4.1-mini) was
+// 6-char code off a dense mobile-viewport waiting room. A smaller/cheaper model (gpt-4.1-mini) was
 // tried and could not read it. reasoning.effort stays "low" (minimal) and the output budget is small
 // but comfortably clear of the "incomplete on reasoning overflow" edge. Kept on the same account/key
 // as the actor; the same full-fidelity frame is already sent to this API by the computer-use provider, so this

package/dist/routes/shared-world/participant-specs.d.ts

@@ -4,8 +4,8 @@ import type { RunBundle } from "../../run/bundle.js";
 import type { CuaParticipantDeps, DesktopParticipantRun, ParticipantRunOutcome } from "../computer-use/types.js";
 import type { LiveParticipants, PlaneContext } from "./types.js";
 export declare function defaultSessionTimeoutMs(plan: SharedWorldPlan): number;
-/** Resolve an actor's seat URL against the harness-minted getHost base (entry is a same-origin
- *  relative path, validated at parse against serve.url). */
+/** Resolve an actor's participant URL against the harness-minted getHost base (entry is a
+ *  same-origin relative path, validated at parse against serve.url). */
 export declare function resolveActorEntryUrl(baseUrl: string, entry: string | undefined): string;
 export declare function participantTaxonomyLabel(labels: Participant["labels"]): string;
 /** Thread the host-yielded lobby code into a follower's mission at runtime (external-public route).
@@ -19,9 +19,10 @@ export declare function makeBlockedFollowerOutcome(spec: DesktopParticipantRun,
 /** The computer-use runner deps every participant shares, on either plane. */
 export type ParticipantRunDeps = Omit<CuaParticipantDeps, "signalProvisioned" | "appUrl" | "onObservedUrl">;
 /**
- * A live run publishes an in-progress bundle before its seats start, whether or not an Observer
- * is attached, and the seats' live traces rewrite it as they go, as on the computer-use route. A
- * run killed mid-way leaves that evidence on disk. The flush starts with the first snapshot.
+ * A live run publishes an in-progress bundle before its participants start, whether or not an
+ * Observer is attached, and the participants' live traces rewrite it as they go, as on the
+ * computer-use route. A run killed mid-way leaves that evidence on disk. The flush starts with the
+ * first snapshot.
  */
 export declare function startParticipantFlush(ctx: PlaneContext, live: LiveParticipants, bundle: RunBundle): void;
 /**
@@ -34,7 +35,7 @@ export declare function startParticipantFlush(ctx: PlaneContext, live: LiveParti
 export declare function participantRunDeps(ctx: PlaneContext, live: LiveParticipants, scrubKnownValues: (text: string) => string): ParticipantRunDeps;
 /**
  * Each participant's actor spec, with committed personas compiled in so each prompt carries real
- * behavioral directives (#381). Evidence copies of the assignment, instructions and persona are
+ * behavioral directives. Evidence copies of the assignment, instructions and persona are
  * scrubbed of the run's known secret values.
  */
 export declare function buildParticipantSpecs(participants: readonly SharedWorldParticipant[], cwd: string, scrubKnownValues: (text: string) => string): Promise<DesktopParticipantRun[]>;

package/dist/routes/shared-world/participant-specs.js

@@ -12,13 +12,14 @@ import { participantAssignment } from "../../lab/participant-assignment.js";
 import { redactText } from "../../evidence/redaction.js";
 import { MAX_SANDBOX_MS, SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS, } from "../../substrates/e2b/lifetime.js";
 import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
-// The default per-seat session budget is derived from the route. On a provisioned route the binding
-// constraint is the subject sandbox (it must outlive every seat: timeoutMs + provisioning +
-// seeding + teardown buffer, and E2B refuses a sandbox over one hour), so the derivation hands
-// each seat the most that cap allows — capped at 15 minutes, floored at the historical 300s so a
-// seed-heavy lab never gets less room than it always had. App-url seats have no subject sandbox
-// and default to 30 minutes (seat sandbox: 30m + 10m buffer stays well under the hour). An
-// explicit execution.timeoutMs is never adjusted. The handoff latch scales off this (40%).
+// The default per-participant session budget is derived from the route. On a provisioned route the
+// binding constraint is the subject sandbox (it must outlive every participant: timeoutMs +
+// provisioning + seeding + teardown buffer, and E2B refuses a sandbox over one hour), so the
+// derivation hands each participant the most that cap allows, capped at 15 minutes, floored at the
+// historical 300s so a seed-heavy study never gets less room than it always had. App-url
+// participants have no subject sandbox and default to 30 minutes (participant sandbox: 30m + 10m
+// buffer stays well under the hour). An explicit execution.timeoutMs is never adjusted. The handoff
+// latch scales off this (40%).
 const MAX_DERIVED_SESSION_MS = 15 * 60_000;
 const MIN_DERIVED_SESSION_MS = 300_000;
 const DEFAULT_APP_URL_SESSION_MS = 30 * 60_000;
@@ -29,9 +30,10 @@ export function defaultSessionTimeoutMs(plan) {
     const room = MAX_SANDBOX_MS - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
     return Math.max(MIN_DERIVED_SESSION_MS, Math.min(MAX_DERIVED_SESSION_MS, room));
 }
+// prose-check: model prompt (the participant model reads this, not a person)
 const DEFAULT_MISSION = "You are one of MANY users hitting a shared web application at the same time. The browser is already open at the app. Accomplish your role's task, then stop.";
-/** Resolve an actor's seat URL against the harness-minted getHost base (entry is a same-origin
- *  relative path, validated at parse against serve.url). */
+/** Resolve an actor's participant URL against the harness-minted getHost base (entry is a
+ *  same-origin relative path, validated at parse against serve.url). */
 export function resolveActorEntryUrl(baseUrl, entry) {
     if (!entry)
         return baseUrl;
@@ -80,6 +82,7 @@ function buildActorSpec(participant, personas) {
  *  the model reads (never a raw bundle field), and the lab scrubs the code from all narration. The
  *  follower joins through the real UI (a direct /lobby/CODE visit does not auto-join a non-member). */
 export function withLobbyCodeMission(spec, code) {
+    // prose-check: model prompt (the participant model reads this, not a person)
     return {
         ...spec,
         instructions: `${spec.instructions}\n\nThe multiplayer lobby code is ${code}. On the home screen choose Join, enter this lobby code, enter your name, and submit to join the shared game (do not open a lobby URL directly — go through the Join flow).`,
@@ -90,7 +93,7 @@ export function withLobbyCodeMission(spec, code) {
 export function makeBlockedFollowerOutcome(spec, reason, timedOut) {
     return {
         spec,
-        sessionError: `handoff barrier: ${reason}; this follower failed closed WITHOUT opening (no wasted turns).`,
+        sessionError: `handoff barrier: ${reason}; this follower stopped before opening the app, so no turns were spent.`,
         killed: false,
         streamUrlPresent: false,
         screenshots: [],
@@ -104,9 +107,10 @@ export function makeBlockedFollowerOutcome(spec, reason, timedOut) {
     };
 }
 /**
- * A live run publishes an in-progress bundle before its seats start, whether or not an Observer
- * is attached, and the seats' live traces rewrite it as they go, as on the computer-use route. A
- * run killed mid-way leaves that evidence on disk. The flush starts with the first snapshot.
+ * A live run publishes an in-progress bundle before its participants start, whether or not an
+ * Observer is attached, and the participants' live traces rewrite it as they go, as on the
+ * computer-use route. A run killed mid-way leaves that evidence on disk. The flush starts with the
+ * first snapshot.
  */
 export function startParticipantFlush(ctx, live, bundle) {
     live.flush = startLiveTraceFlush({
@@ -117,14 +121,14 @@ export function startParticipantFlush(ctx, live, bundle) {
     });
 }
 /**
- * The runtime stream URLs each seat reports to the live Observer. The Observer learns of a stream
- * before the caller's onStream runs.
+ * The runtime stream URLs each participant reports to the live Observer. The Observer learns of a
+ * stream before the caller's onStream runs.
  */
 function participantStreams(onStream, live) {
     return (event) => {
         if (event.type === "ready")
             live.streamUrls.push({ streamId: event.streamId, url: event.url });
-        // Mark, never remove (#357): the tile falls back to recorded evidence and says why.
+        // Mark, never remove: the tile falls back to recorded evidence and says why.
         else
             for (const entry of live.streamUrls)
                 if (entry.streamId === event.streamId)
@@ -164,33 +168,36 @@ export function participantRunDeps(ctx, live, scrubKnownValues) {
         redactScreenshots: ctx.redactScreenshots,
         scrubKnownValues,
         runSession: ctx.runSession,
-        // A local-agent brain runs each seat on the operator's signed-in agent, as on computer use.
+        // A local-agent brain runs each participant on the operator's signed-in agent, as on computer
+        // use.
         brain: ctx.plan.brain,
         ...(receiving ? { receiving } : {}),
         now: ctx.now,
-        // The seat's desktop seams, and the caller's prepareDesktop with the seat as its target.
+        // The participant's desktop seams, and the caller's prepareDesktop with the participant as its
+        // target.
         ...(ctx.deps.desktopModule === undefined ? {} : { desktopModule: ctx.deps.desktopModule }),
         ...(ctx.deps.detachedTimers === undefined ? {} : { detachedTimers: ctx.deps.detachedTimers }),
         ...(ctx.input.prepareDesktop === undefined ? {} : { prepareDesktop: ctx.input.prepareDesktop }),
         onStream: participantStreams(ctx.input.onStream, live),
-        // A seat visits the shared app and provisions no subject, so it reports no phase of its own.
+        // A participant visits the shared app and provisions no subject, so it reports no phase of its
+        // own.
         reportSubjectPhase: defaultSubjectPhaseSink,
         ...(runBudget === undefined ? {} : { runBudget }),
-        // Concurrent participants are independent evidence seats: a requested-vs-verified screen
+        // Concurrent participants are independent evidence: a requested-vs-verified screen
         // mismatch is recorded as separate facts + a warning instead of failing the participant's
-        // device claim closed, so one seat's window-manager drift cannot abort the whole
+        // device claim closed, so one participant's window-manager drift cannot abort the whole
         // live multi-actor world (the single-participant/fan-out routes keep fail-closed).
         screenMismatchPolicy: "record-evidence",
     };
 }
 /**
  * Each participant's actor spec, with committed personas compiled in so each prompt carries real
- * behavioral directives (#381). Evidence copies of the assignment, instructions and persona are
+ * behavioral directives. Evidence copies of the assignment, instructions and persona are
  * scrubbed of the run's known secret values.
  */
 export async function buildParticipantSpecs(participants, cwd, scrubKnownValues) {
-    // Only the personas the participants use: an actors[0].persona that every seat overrides is
-    // never applied, so it is not read.
+    // Only the personas the participants use: an actors[0].persona that every participant overrides
+    // is never applied, so it is not read.
     const personaResolution = await resolveCommittedPersonasForCwd(cwd, participants.map((participant) => participant.personaId));
     const actorSpecs = participants.map((participant) => buildActorSpec(participant, personaResolution.personas));
     for (const spec of actorSpecs) {

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

@@ -10,7 +10,7 @@ import { sharedWorldParticipants } from "../../lab/plan-participants.js";
 import { PUBLIC_TARGET_OWNER_PATTERN } from "../../lab/parse/subject.js";
 import { REPO_SLUG_PATTERN } from "../../lab/parse/values.js";
 import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
-import { MODEL_RATES } from "../../run/pricing.js";
+import { MODEL_RATES, unpricedCapMessage } from "../../run/pricing.js";
 /** The registered descriptor for a planned actor; planSharedWorldLab checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -27,20 +27,20 @@ export function planSharedWorldLab(config, input) {
         ok: false,
         refusal: { route: "shared-world", code, message, ...(actor === undefined ? {} : { actor }) },
     });
-    const invalid = "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID";
+    const invalid = "HUMANISH_SHARED_WORLD_INVALID";
     const mediaReason = desktopMediaValidationReason(config, false);
     if (mediaReason)
         return refuse(invalid, mediaReason);
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
-        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+        return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
-        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
+        return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
     const actorType = config.actors[0]?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
-        return refuse("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
+        return refuse("HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
     const actor = descriptor.id;
     // An app-url subject is the external-public plane (a real operator-owned deployment used
     // directly, with no getHost, clone, subject sandbox or seed); every other subject is the
@@ -61,7 +61,7 @@ export function planSharedWorldLab(config, input) {
     if (!input.dryRun && (caps?.maxUsd !== undefined || caps?.maxTotalUsd !== undefined)) {
         const model = (config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
         if (!MODEL_RATES[model])
-            return refuse("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_UNPRICED_CAP", `The declared spend cap cannot be enforced for unpriced model "${model}".`, actor);
+            return refuse("HUMANISH_SHARED_WORLD_UNPRICED_CAP", unpricedCapMessage(model), actor);
     }
     const receivingReason = receivingEmailValidationReason(config);
     if (receivingReason)
@@ -113,7 +113,7 @@ export function planSharedWorldLab(config, input) {
                         externalCatch: plane.kind === "external-public",
                     }),
                     // The external-public plane reads the host's lobby code with the OpenAI API, whatever
-                    // brain drives the seats.
+                    // brain drives the participants.
                     ...(plane.kind === "external-public" && brain.kind !== "openai"
                         ? [{ kind: "key", name: "OPENAI_API_KEY" }]
                         : []),