humanish 0.106.1 → 0.108.0

package/dist/routes/shared-world/{seats.js → participant-specs.js}

@@ -1,5 +1,6 @@
 // Builds each participant's actor spec and mission, resolves its entry URL, derives the session
 // and sandbox time budgets, and records a follower that never received the host's lobby code.
+import { defaultSubjectPhaseSink } from "../../subject/steps.js";
 import { pricedModel } from "../../lab/plan-base.js";
 import { scrubPersonaBrief } from "../../lab/persona.js";
 import { resolveParticipant } from "../../run/participant.js";
@@ -11,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, not flat. 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;
@@ -28,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;
@@ -74,11 +77,12 @@ function buildActorSpec(participant, personas) {
         traceArtifactPath: `actors/${run.streamId}.json`,
     };
 }
-/** Thread the host-yielded lobby CODE into a follower's mission at runtime (external-public route).
- *  The CODE flows into the follower's join instruction; it is persisted only as the composed prompt
- *  the model reads (never a raw bundle field), and the lab scrubs the CODE from all narration. The
+/** Thread the host-yielded lobby code into a follower's mission at runtime (external-public route).
+ *  The code flows into the follower's join instruction; it is persisted only as the composed prompt
+ *  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).`,
@@ -89,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: [],
@@ -103,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({
@@ -116,53 +121,41 @@ export function startParticipantFlush(ctx, live, bundle) {
     });
 }
 /**
- * The caller's desktop hooks, plus the runtime stream URLs each seat reports to the live Observer.
- * The Observer learns of a stream before the caller's stream hook 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 runtimeStreamHooks(hooks, live) {
-    return {
-        ...(hooks.loadDesktopModule ? { loadDesktopModule: hooks.loadDesktopModule } : {}),
-        ...(hooks.detachedTimers ? { detachedTimers: hooks.detachedTimers } : {}),
-        ...(hooks.env ? { env: hooks.env } : {}),
-        ...(hooks.prepareDesktop
-            ? {
-                prepareDesktop: (desktop, participant) => hooks.prepareDesktop(desktop, participant),
-            }
-            : {}),
-        onRuntimeStreamReady: (stream) => {
-            live.streamUrls.push({ streamId: stream.streamId, url: stream.url });
-            if (live.observer) {
-                attachObserverRuntimeStreamUrls(live.observer, live.streamUrls);
-            }
-            return hooks.onRuntimeStreamReady?.(stream);
-        },
-        onRuntimeStreamEnded: (stream) => {
-            // Mark, never remove (#357): the tile falls back to recorded evidence and says why.
-            for (const entry of live.streamUrls) {
-                if (entry.streamId === stream.streamId)
+function participantStreams(onStream, live) {
+    return (event) => {
+        if (event.type === "ready")
+            live.streamUrls.push({ streamId: event.streamId, url: event.url });
+        // 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)
                     entry.ended = true;
-            }
-            if (live.observer) {
-                attachObserverRuntimeStreamUrls(live.observer, live.streamUrls);
-            }
-            return hooks.onRuntimeStreamEnded?.(stream);
-        },
+        if (live.observer)
+            attachObserverRuntimeStreamUrls(live.observer, live.streamUrls);
+        return onStream?.(event);
     };
 }
 /**
- * The runner deps both planes give every participant. cloneRoute=false + subjectEnvNames=[] keep subject
- * creds out of every actor sandbox (FIX-10). `scrubKnownValues` is the plane's scrub: the
- * external-public plane also scrubs the latched lobby code.
+ * The runner deps both planes give every participant. The `shared-app` subject keeps three things
+ * out of every actor sandbox: the subject env names' values, the GitHub token, and clone
+ * or local-tree provisioning. The committed subject.envValues still reach it, non-secret by parse.
+ * `scrubKnownValues` is the plane's scrub: the external-public plane also scrubs the latched lobby
+ * code.
  */
 export function participantRunDeps(ctx, live, scrubKnownValues) {
-    const { config, descriptor, env, receiving, runBudget } = ctx;
+    const { config, env, receiving, runBudget } = ctx;
     return {
         onTrace: (participantId, items, usage, metadata) => live.flush?.flush(participantId, items, usage, metadata),
-        config,
-        descriptor,
-        cloneRoute: false,
-        subjectEnvNames: [],
-        hasGithubToken: false,
+        residual: ctx.plan.residual,
+        labId: ctx.plan.labId,
+        caps: ctx.plan.caps,
+        subject: {
+            kind: "shared-app",
+            ...(config.subject.serve?.url === undefined ? {} : { serveUrl: config.subject.serve.url }),
+        },
         env,
         openaiApiKey: ctx.openaiApiKey,
         e2bApiKey: ctx.e2bApiKey,
@@ -175,27 +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,
-        hooks: runtimeStreamHooks(ctx.hooks, live),
+        // 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 participant visits the shared app and provisions no subject, so it reports no phase of its
+        // own.
+        reportSubjectPhase: defaultSubjectPhaseSink,
         ...(runBudget === undefined ? {} : { runBudget }),
-        // Concurrent lanes are independent evidence seats: a requested-vs-verified screen
-        // mismatch is recorded as separate facts + a warning instead of failing the lane's
-        // device claim closed, so one seat's window-manager drift cannot abort the whole
-        // live multi-actor world (the single-lane/fan-out routes keep fail-closed).
+        // 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 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.d.ts

@@ -1,7 +1,6 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { RoutePlanResult, RouteRefusal, SharedWorldPlan } from "../../lab/plan-types.js";
 import type { LabConfig, LabSubjectState } from "../../lab/types.js";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { ConcurrentSharedWorldLabErrorCode } from "./types.js";
 /** The error a shared-world lab returns before a run starts. */
 export interface SharedWorldRefusal extends RouteRefusal<"shared-world", ConcurrentSharedWorldLabErrorCode> {
@@ -17,11 +16,8 @@ export declare function sharedWorldDescriptorOf(actorType: string): CuaActorDesc
  */
 export declare function planSharedWorldLab(config: LabConfig, input: {
     readonly dryRun: boolean;
-    readonly lab?: RunLabProvenance;
-    /** A caller's session runner cannot enforce maxOutputTokens. */
-    readonly hooks?: {
-        readonly runSession?: unknown;
-    };
+    /** Whether deps.runSession is set: a caller's session runner cannot enforce maxOutputTokens. */
+    readonly hasRunSession?: boolean;
 }): SharedWorldPlanResult;
 /** The provisioned plane's declared subject state. The external-public plane declares none. */
 export declare function planeStateOf(plan: SharedWorldPlan): LabSubjectState | undefined;

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
@@ -55,13 +55,13 @@ export function planSharedWorldLab(config, input) {
             : concurrentSharedWorldValidationReason(config));
     if (invalidReason)
         return refuse(invalid, invalidReason, actor);
-    if (config.actors[0]?.maxOutputTokens !== undefined && input.hooks?.runSession)
+    if (config.actors[0]?.maxOutputTokens !== undefined && input.hasRunSession === true)
         return refuse(invalid, "maxOutputTokens cannot be enforced by a custom runSession.", actor);
     const caps = config.execution?.caps;
     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)
@@ -88,7 +88,6 @@ export function planSharedWorldLab(config, input) {
         throw new Error("a shared-world participant has no caller brain");
     const base = planBase(config, {
         dryRun: input.dryRun,
-        ...(input.lab === undefined ? {} : { lab: input.lab }),
         analysis,
     });
     return {
@@ -114,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" }]
                         : []),

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

@@ -2,18 +2,18 @@ import type { RunSubjectProvenance } from "../../run/bundle.js";
 import type { LocalTreeArchive } from "../../subject/local-tree-archive.js";
 /** Extract the in-sandbox port from the (loopback) serve.url so getHost can expose it. */
 export declare function servePort(serveUrl: string): number;
-/** A getHost URL must be TOKENLESS (no userinfo, no query — no authKey; invariant 1). */
+/** A getHost URL must be tokenless (no userinfo and no query, so no authKey reaches evidence). */
 export declare function isTokenlessHost(value: string): boolean;
-/** sha256-16 of a URL's ORIGIN — the publish-safe host identity persisted in the bundle (the raw
+/** sha256-16 of a URL's origin: the publish-safe host identity persisted in the bundle (the raw
  *  getHost URL embeds the live sandbox id + matches the e2b-URL redaction, so it never lands raw). */
 export declare function hostOriginDigest(url: string): string;
 /** A public-safe, human-readable route label for the bundle (host redacted to a placeholder; the
  *  entry path kept). Never contains the raw getHost URL. */
 export declare function publicSafeRouteLabel(entry: string | undefined): string;
 /**
- * Build the ONE subject sandbox's provenance (invariant 5): clone (repo + optional commit) or
+ * Build the one subject sandbox's provenance: clone (repo + optional commit) or
  * local-tree (archiveSha256 + optional commit/dirty from the once-per-run host-packed archive -
- * archiveSha256 IS the pin; there is only ONE archive, so no per-lane unanimity math applies,
+ * archiveSha256 is the pin; there is only one archive, so no per-participant unanimity math applies,
  * unlike the cua fan-out route). Used for both the in-progress and final bundle: the archive
  * never changes mid-run (packed before any sandbox exists).
  */

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

@@ -8,7 +8,7 @@ export function servePort(serveUrl) {
         return Number(url.port);
     return url.protocol === "https:" ? 443 : 80;
 }
-/** A getHost URL must be TOKENLESS (no userinfo, no query — no authKey; invariant 1). */
+/** A getHost URL must be tokenless (no userinfo and no query, so no authKey reaches evidence). */
 export function isTokenlessHost(value) {
     try {
         const url = new URL(value);
@@ -18,7 +18,7 @@ export function isTokenlessHost(value) {
         return false;
     }
 }
-/** sha256-16 of a URL's ORIGIN — the publish-safe host identity persisted in the bundle (the raw
+/** sha256-16 of a URL's origin: the publish-safe host identity persisted in the bundle (the raw
  *  getHost URL embeds the live sandbox id + matches the e2b-URL redaction, so it never lands raw). */
 export function hostOriginDigest(url) {
     try {
@@ -34,9 +34,9 @@ export function publicSafeRouteLabel(entry) {
     return `[provisioned-subject]${entry ?? "/"}`;
 }
 /**
- * Build the ONE subject sandbox's provenance (invariant 5): clone (repo + optional commit) or
+ * Build the one subject sandbox's provenance: clone (repo + optional commit) or
  * local-tree (archiveSha256 + optional commit/dirty from the once-per-run host-packed archive -
- * archiveSha256 IS the pin; there is only ONE archive, so no per-lane unanimity math applies,
+ * archiveSha256 is the pin; there is only one archive, so no per-participant unanimity math applies,
  * unlike the cua fan-out route). Used for both the in-progress and final bundle: the archive
  * never changes mid-run (packed before any sandbox exists).
  */

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

@@ -3,7 +3,7 @@ import type { RunSubjectStateStepRecord } from "../../run/bundle.js";
 import type { SharedWorldStateSnapshot } from "../../run/shared-world-evidence.js";
 import type { LocalTreeArchive } from "../../subject/local-tree-archive.js";
 import type { DetachedTimers } from "../../substrates/detached.js";
-import type { SharedWorldLabHooks } from "./types.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
 import { type ActorRunResult, type SubjectDesktopUsage, type LiveParticipants, type PlaneContext } from "./types.js";
 /** What the provisioned plane needs besides the shared plane context. */
 export interface ProvisionedPlaneSetup {
@@ -35,6 +35,7 @@ export interface ProvisionedPlaneOutcome {
     subjectCommit: string | undefined;
     subjectSandboxId: string | undefined;
     subjectKilled: boolean;
+    subjectReleaseWarning: string | undefined;
     subjectDesktop: SubjectDesktopUsage | undefined;
     getHostUrl: string | undefined;
     /** Set when the teardown drain wrote a comms thread. */
@@ -47,7 +48,7 @@ export declare function runProvisionedPlane(ctx: PlaneContext, live: LivePartici
  */
 export declare function packSubjectTree(cwd: string, config: {
     readonly subject: Pick<LabConfig["subject"], "localTree">;
-}, hooks: SharedWorldLabHooks, scrubKnownValues: (text: string) => string): Promise<{
+}, deps: LabDeps, scrubKnownValues: (text: string) => string): Promise<{
     ok: true;
     archive: LocalTreeArchive;
     buffer: ArrayBuffer;