humanish 0.106.1 → 0.108.0

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

@@ -1,38 +1,39 @@
-// The CONCURRENT shared-world lab backend (#164 phase 2): N persona lanes drive ONE shared,
-// mutable service plane SIMULTANEOUSLY — the actual leverage of a sim. A recomposition of shipped
+// The concurrent shared-world lab route: N persona participants drive one shared,
+// mutable service plane at the same time. A recomposition of shipped
 // pieces + the getHost wrapper:
 //
-//   - ONE SUBJECT sandbox: provisionCloneSubject ONCE (clone+install+build+seed) + serve on
+//   - One subject sandbox: provisionCloneSubject once (clone+install+build+seed) + serve on
 //     0.0.0.0, exposed via getHost(port) → a tokenless reachable URL (the headless service host;
-//     no GUI seat).
-//   - N ACTOR desktop sandboxes: fan-out's runCuaParticipant machinery (per-lane device/persona, by-id
-//     teardown) bounded by execution.concurrency, each browser pointed at the getHost URL —
-//     driving the shared service AT THE SAME TIME. INDEPENDENT (FIX-11): no pipeline gate, no
-//     fail-fast — one actor's failure must not block the swarm or corrupt the "M of N" outcomes.
+//     no GUI participant).
+//   - N actor desktop sandboxes: fan-out's runCuaParticipant machinery (per-participant device/persona, by-id
+//     teardown) bounded by execution.concurrency, each browser pointed at the getHost URL and
+//     driving the shared service at the same time. Independent: no pipeline gate, no
+//     fail-fast: one actor's failure must not block the swarm or corrupt the "M of N" outcomes.
 //   - A background prober snapshots the subject DB checkpoint digests on a cadence → a stateSeries
 //     of the shared world evolving under load.
-//   - ALL N+1 sandboxes torn down BY exact id in a finally — NEVER Sandbox.list.
+//   - All N+1 sandboxes torn down by exact id in a finally, never through Sandbox.list.
 //
-// HONEST ATTRIBUTION (verify-enforced, doctrine-audit fixes incorporated): the bundle declares
-// attributionClass: shared-world + a CONCURRENT humanish.shared-world.v1 block (topologyMode
-// "concurrent"; laneWindows + stateSeries + outcomes; NO timeline) whose attributionLimits drop
+// Attribution (enforced by verify): the bundle declares
+// attributionClass: shared-world + a concurrent humanish.shared-world.v1 block (topologyMode
+// "concurrent"; laneWindows + stateSeries + outcomes; no timeline) whose attributionLimits drop
 // `sequential-only`/`no-concurrent-races` and add `concurrent`,
 // `best-effort-causal-attribution`, `non-deterministic-shared-state`,
 // `window-and-snapshot-granularity`, `contention-observed-not-proven-safe`,
-// `state-change-not-isolated-to-actors`. laneWindows + stateSeries are INDEPENDENT series with NO
-// per-delta→actor field — causation under concurrency is structurally inexpressible.
+// `state-change-not-isolated-to-actors`. laneWindows + stateSeries are independent series with no
+// per-delta→actor field, so causation under concurrency is structurally inexpressible.
 //
-// CAPABILITY vs PROOF (FIX-1): the deterministic $0 gate proves the PLUMBING + the honesty
-// contract — the real mapWithConcurrency produces genuinely overlapping laneWindows (a rendezvous
-// latch in the fake session forces two lane fns in-flight while the REAL orchestrator clock
+// Capability and proof: the deterministic $0 gate proves the plumbing + the claims-match-mechanism
+// contract: the real mapWithConcurrency produces genuinely overlapping laneWindows (a rendezvous
+// latch in the fake session forces two participant fns in-flight while the real orchestrator clock
 // measures the windows). Every generated bundle describes only its own observations; no one run
 // establishes scale, repeatability, or adopter-harness replacement.
 //
-// Synthetic-subject (FIX-3): a getHost URL is internet-reachable for the run, so this route is
-// synthetic-seeded-subjects ONLY. Verify fail-closes on subject.state.provenance != "seeded" and
+// Synthetic subject: a getHost URL is internet-reachable for the run, so this route is for
+// synthetic seeded subjects only. Verify fail-closes on subject.state.provenance != "seeded" and
 // requires the author attestation subject.exposure: synthetic. This is author-trust + a provenance
-// gate, NOT a no-real-data guarantee (humanish cannot tell synthetic from real data).
+// gate; humanish cannot tell synthetic from real data, so it makes no claim about real data.
 import path from "node:path";
+import { missingKeys, missingSubjectEnv } from "../../lab/requirements.js";
 import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { scrubLiterals } from "../../evidence/redaction.js";
@@ -46,15 +47,16 @@ import { localAgentRefusal } from "../../actors/local-agent/readiness.js";
 import { runProvisionedPlane } from "./provisioned.js";
 import { concurrentLabFailure, finishConcurrentRun } from "./result.js";
 import { prepareConcurrentRun } from "./setup.js";
-import { sharedWorldInputWithScorer } from "../../lab/route-inputs.js";
+import { browserRouteScorer } from "../../lab/adapter-scorer-loader.js";
+import { withLateScorer } from "../../lab/route-inputs.js";
 import {} from "./types.js";
 import { rosterOf } from "../../lab/parse/actors.js";
 /** The shared-world code for each local-agent refusal, kind for kind with computer-use. */
 const LOCAL_AGENT_REFUSAL_CODES = {
-    "agent-missing": "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_AGENT_MISSING",
-    "signin-required": "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_AGENT_SIGNIN_REQUIRED",
-    unsupported: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED",
-    "unpriced-cap": "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_UNPRICED_CAP",
+    "agent-missing": "HUMANISH_SHARED_WORLD_AGENT_MISSING",
+    "signin-required": "HUMANISH_SHARED_WORLD_AGENT_SIGNIN_REQUIRED",
+    unsupported: "HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED",
+    "unpriced-cap": "HUMANISH_SHARED_WORLD_UNPRICED_CAP",
 };
 /**
  * The library entry for a shared-world lab. It plans the config with planSharedWorldLab and runs
@@ -62,12 +64,11 @@ const LOCAL_AGENT_REFUSAL_CODES = {
  * run and its analysis.
  */
 export async function runConcurrentSharedWorld(options) {
-    const { config, dryRun, lab, ...input } = options;
+    const { config, dryRun, ...input } = options;
     // planSharedWorldLab makes every configuration refusal, in the order this route always has.
     const planned = planSharedWorldLab(config, {
         dryRun,
-        ...(lab === undefined ? {} : { lab }),
-        hooks: input.hooks ?? {},
+        hasRunSession: input.deps?.runSession !== undefined,
     });
     if (planned.ok)
         return runSharedWorldPlan(planned.plan, input, config);
@@ -82,15 +83,15 @@ export function sharedWorldLabRefusal(options, refusal) {
         labId: config.id,
         actor: config.actors[0]?.type ?? "",
         participantCount: declared.length,
-        // The parser fills concurrency for multi-seat labs, so this fallback serves only library
-        // callers: every declared seat runs at once unless the author declared a cap (#350).
+        // The parser fills concurrency for multi-participant studies, so this fallback serves only
+        // library callers: every declared participant runs at once unless the author declared a cap.
         concurrency: config.execution?.concurrency ?? Math.max(1, declared.length),
         dryRun,
         runId: options.runId,
     });
     // A refusal starts no run, so a declared or default analysis is recorded as skipped.
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    return completeAutomaticAnalysis(fail(refusal.code, refusal.message, refusal.actor), undefined, analysis.ok ? analysis.config : undefined, options.automaticAnalysis, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+    return completeAutomaticAnalysis(fail(refusal.code, refusal.message, refusal.actor), undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
 }
 /**
  * runLab's step for a shared-world plan. It runs a live plan's local checks (the keys, a local
@@ -103,11 +104,11 @@ export async function admitSharedWorldPlan(plan, input, config) {
         return { ok: false, outcome: sharedWorldOutcome(refused) };
     return {
         ok: true,
-        run: async (scorer) => sharedWorldOutcome(await runAdmittedSharedWorldRun(plan, sharedWorldInputWithScorer(input, scorer), config)),
+        run: async (scorer) => sharedWorldOutcome(await runAdmittedSharedWorldRun(plan, withLateScorer(input, scorer, browserRouteScorer), config)),
     };
 }
 function sharedWorldOutcome(result) {
-    return { route: "shared-world", backend: "concurrent-shared-world", result };
+    return { route: "shared-world", result };
 }
 /** Run a shared-world plan: its local checks, then the run. */
 export async function runSharedWorldPlan(plan, input, config) {
@@ -122,29 +123,25 @@ export async function runSharedWorldPlan(plan, input, config) {
 async function admitSharedWorldRun(plan, input) {
     if (plan.dryRun)
         return undefined;
-    const env = input.hooks?.env ?? process.env;
-    const subjectEnvNames = plan.plane.kind === "provisioned" ? plan.plane.subject.env : [];
+    const env = input.env ?? process.env;
     const fail = (code, message) => completeSharedWorldAnalysis(plan, input, sharedWorldFailure(plan, input)(code, message, sharedWorldDescriptorOf(plan.actor).id), undefined);
-    // OPENAI_API_KEY drives an openai brain's seats and the external-public plane's lobby-code
-    // reader; a local-agent brain's seats run on the operator's signed-in agent instead.
-    const openaiKeyNeeded = plan.brain.kind === "openai" || plan.plane.kind === "external-public";
-    const missingKeys = [
-        ...(env.OPENAI_API_KEY?.trim() || !openaiKeyNeeded ? [] : ["OPENAI_API_KEY"]),
-        ...(env.E2B_API_KEY?.trim() ? [] : ["E2B_API_KEY"]),
-    ];
-    if (missingKeys.length > 0) {
-        return fail("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_KEYS_MISSING", `Live concurrent shared-world labs need ${missingKeys.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missingKeys, env)}`);
+    // The plan lists OPENAI_API_KEY for an openai brain's participants and the external-public
+    // plane's lobby-code reader; a local-agent brain's participants run on the operator's signed-in
+    // agent instead.
+    const missing = missingKeys(plan.requirements, env);
+    if (missing.length > 0) {
+        return fail("HUMANISH_SHARED_WORLD_KEYS_MISSING", `Live concurrent shared-world labs need ${missing.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missing, env)}`);
     }
     if (plan.brain.kind === "local-agent") {
-        // A missing or signed-out agent found after the seats' desktops are paid for is the same
+        // A missing or signed-out agent found after the participants' desktops are paid for is the same
         // news at the worst moment.
         const refusal = await localAgentRefusal({ agent: plan.brain.agent, env, caps: plan.caps });
         if (refusal)
             return fail(LOCAL_AGENT_REFUSAL_CODES[refusal.kind], refusal.message);
     }
-    const missingSubjectEnv = subjectEnvNames.filter((name) => !env[name]?.trim());
-    if (missingSubjectEnv.length > 0) {
-        return fail("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_SUBJECT_ENV_MISSING", `subject.env declares ${missingSubjectEnv.join(", ")} but the environment does not provide ${missingSubjectEnv.length === 1 ? "it" : "them"} (pass via --env-file; values are never persisted).`);
+    const unsetSubjectEnv = missingSubjectEnv(plan.requirements, env);
+    if (unsetSubjectEnv.length > 0) {
+        return fail("HUMANISH_SHARED_WORLD_SUBJECT_ENV_MISSING", `subject.env declares ${unsetSubjectEnv.join(", ")} but the environment does not provide ${unsetSubjectEnv.length === 1 ? "it" : "them"} (pass via --env-file; values are never persisted).`);
     }
     return undefined;
 }
@@ -160,7 +157,7 @@ function runAdmittedSharedWorldRun(plan, input, config) {
     });
 }
 function completeSharedWorldAnalysis(plan, input, result, finished) {
-    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input.automaticAnalysis, {
+    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input, {
         ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
         preferLargerOutput: plan.analysis?.preferLargerOutput === true,
     });
@@ -180,8 +177,8 @@ function sharedWorldFailure(plan, input) {
 async function runPlanInScope(plan, input, config, scope) {
     const { dryRun } = plan;
     const requestedCwd = path.resolve(input.cwd);
-    const hooks = input.hooks ?? {};
-    const env = hooks.env ?? process.env;
+    const deps = input.deps ?? {};
+    const env = input.env ?? process.env;
     const fail = sharedWorldFailure(plan, input);
     const descriptor = sharedWorldDescriptorOf(plan.actor);
     const planeClass = plan.plane.kind === "external-public" ? "external-public" : "provisioned-getHost";
@@ -194,7 +191,7 @@ async function runPlanInScope(plan, input, config, scope) {
     const subjectRepo = plan.residual.subject.repos?.[0] ?? "";
     const subjectEnvNames = [...(subject?.env ?? [])];
     const checkpoints = [...(subject?.state.checkpoint ?? [])];
-    const runSession = hooks.runSession ?? descriptor.runSession;
+    const runSession = deps.runSession ?? descriptor.runSession;
     const openaiApiKey = env.OPENAI_API_KEY?.trim() ?? "";
     const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
     const knownSecretValues = [
@@ -212,7 +209,7 @@ async function runPlanInScope(plan, input, config, scope) {
         input,
         config,
         requestedCwd,
-        hooks,
+        deps,
         env,
         descriptor,
         planeClass,
@@ -236,13 +233,13 @@ async function runPlanInScope(plan, input, config, scope) {
     const { ctx, live, results } = prepared;
     const planeRan = await runPlane(ctx, live, results, prepared.plane);
     if (!planeRan) {
-        return fail("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID", "the provisioned-getHost concurrent shared-world route requires `subject.serve`.", descriptor.id);
+        return fail("HUMANISH_SHARED_WORLD_INVALID", "the provisioned-getHost concurrent shared-world route requires `subject.serve`.", descriptor.id);
     }
     return finishConcurrentRun(ctx, live, results, prepared.finish);
 }
 /**
- * Runs the plane the lab declares, then finalizes email receiving and stops the seats' flush on
- * every exit. Returns false when a provisioned lab reaches it without `subject.serve`.
+ * Runs the plane the study declares, then finalizes email receiving and stops the participants'
+ * flush on every exit. Returns false when a provisioned study reaches it without `subject.serve`.
  */
 async function runPlane(ctx, live, results, plane) {
     const { dryRun } = ctx.plan;
@@ -270,7 +267,7 @@ async function runPlane(ctx, live, results, plane) {
         catch {
             ctx.warnings.push("Email finalization could not complete. Inspect humanish comms recover; provider cleanup remains unresolved.");
         }
-        // Stop the seats' flush timer on every exit, before the final write.
+        // Stop the participants' flush timer on every exit, before the final write.
         await live.flush?.stop();
     }
     return true;

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

@@ -1,17 +1,18 @@
 import type { CuaActorDescriptor } from "../../actors/registry.js";
 import type { LabConfig, LabSubjectServe, LabSubjectStateCheckpoint } from "../../lab/types.js";
 import type { RunScope } from "../../run/run.js";
-import type { ConcurrentSharedWorldLabErrorCode, ConcurrentSharedWorldLabResult, ConcurrentSharedWorldPlaneClass, FinishFacts, LiveParticipants, PlaneContext, PlaneResults, PlaneSelection, SharedWorldLabHooks, SharedWorldRunInput } from "./types.js";
+import type { ConcurrentSharedWorldLabErrorCode, ConcurrentSharedWorldLabResult, ConcurrentSharedWorldPlaneClass, FinishFacts, LiveParticipants, PlaneContext, PlaneResults, PlaneSelection, SharedWorldRunInput } from "./types.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
 import type { SharedWorldPlan } from "../../lab/plan-types.js";
 /** What validation derived from the lab, which setup reads. */
 interface AdmittedLab {
     plan: SharedWorldPlan;
     input: SharedWorldRunInput;
-    /** Read by the computer-use lane runner, whose hooks and desktop setup take the whole config.
-     *  Seats, their count and their host and entry come from the plan's participants. */
+    /** Read for the subject's serve URL, which each participant's subject names. Participants, their
+     *  count and their host and entry come from the plan's participants. */
     config: LabConfig;
     requestedCwd: string;
-    hooks: SharedWorldLabHooks;
+    deps: LabDeps;
     env: Record<string, string | undefined>;
     descriptor: CuaActorDescriptor;
     planeClass: ConcurrentSharedWorldPlaneClass;
@@ -31,7 +32,7 @@ interface AdmittedLab {
     fail: (code: ConcurrentSharedWorldLabErrorCode, message: string, actorLabel?: string) => ConcurrentSharedWorldLabResult;
 }
 /**
- * Starts the run and prepares what the planes read: the physical project, the run, the seat
+ * Starts the run and prepares what the planes read: the physical project, the run, the participant
  * specs, comms, the packed tree and email receiving. Returns the refusal when one of them fails.
  */
 export declare function prepareConcurrentRun(lab: AdmittedLab, scope: RunScope): Promise<{

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

@@ -1,5 +1,5 @@
 // Starts a concurrent shared-world run and prepares what its plane reads: the physical project,
-// the run, the seat specs, comms, the packed tree and email receiving.
+// the run, the participant specs, comms, the packed tree and email receiving.
 import { randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import { buildRunSource } from "../../run/bundle.js";
@@ -10,7 +10,7 @@ import { prepareEmailReceiving, prepareExternalComms, receivingSourceOf, subject
 import { declaredOriginDigestOf } from "./external-public.js";
 import { packSubjectTree } from "./provisioned.js";
 import { emptyPlaneResults } from "./result.js";
-import { buildParticipantSpecs, defaultSessionTimeoutMs } from "./seats.js";
+import { buildParticipantSpecs, defaultSessionTimeoutMs } from "./participant-specs.js";
 import { planeStateOf } from "./plan.js";
 import path from "node:path";
 import { e2bRequestTimeoutMs } from "../../substrates/e2b/lifetime.js";
@@ -49,7 +49,7 @@ async function bindPhysicalProject(requestedCwd) {
         .physicalPath;
 }
 function startConcurrentRun(lab, cwd, scope) {
-    const { plan, input, hooks } = lab;
+    const { plan, input, deps } = lab;
     return scope.startRun({
         cwd,
         runId: input.runId,
@@ -57,15 +57,15 @@ function startConcurrentRun(lab, cwd, scope) {
         mode: plan.dryRun ? "dry-run" : "live",
         lab: plan.lab,
         renderReview: renderConcurrentReviewMarkdown,
-        observer: { open: input.open === true, render: hooks.renderObserverFn },
+        observer: { open: input.open === true, render: deps.renderObserver },
     });
 }
 /**
- * Starts the run and prepares what the planes read: the physical project, the run, the seat
+ * Starts the run and prepares what the planes read: the physical project, the run, the participant
  * specs, comms, the packed tree and email receiving. Returns the refusal when one of them fails.
  */
 export async function prepareConcurrentRun(lab, scope) {
-    const { plan, input, config, requestedCwd, hooks, env, descriptor, planeClass, fail } = lab;
+    const { plan, input, config, requestedCwd, deps, env, descriptor, planeClass, fail } = lab;
     const { runBudget, runSession, localTreeRoute, subjectEnvNames, publicRepo } = lab;
     const { openaiApiKey, e2bApiKey, knownSecretValues, scrubKnownValues } = lab;
     const { dryRun, concurrency } = plan;
@@ -73,22 +73,19 @@ export async function prepareConcurrentRun(lab, scope) {
     const warnings = [];
     // The comms catch and the packed tree are checked before the run starts, so a refusal leaves
     // no run directory. Neither spends: the probe is one request and packing runs on the host.
-    const externalComms = await prepareExternalComms(plan.residual, planeClass, dryRun, warnings);
+    const externalComms = await prepareExternalComms(plan.residual, planeClass, dryRun, warnings, env);
     if (!externalComms.ok) {
-        return {
-            ok: false,
-            result: fail("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE", externalComms.message),
-        };
+        return { ok: false, result: fail(externalComms.code, externalComms.message) };
     }
     // Pack the working tree once per run, on the host, before any sandbox exists: a packing
     // failure fails the run closed without sandbox cost. Dry-run packs nothing.
     const packed = localTreeRoute && !dryRun
-        ? await packSubjectTree(cwd, plan.residual, hooks, scrubKnownValues)
+        ? await packSubjectTree(cwd, plan.residual, deps, scrubKnownValues)
         : { ok: true, archive: undefined, buffer: undefined };
     if (!packed.ok) {
         return {
             ok: false,
-            result: fail("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED", packed.message, descriptor.id),
+            result: fail("HUMANISH_SHARED_WORLD_FAILED", packed.message, descriptor.id),
         };
     }
     const localTreeArchive = packed.archive;
@@ -102,9 +99,9 @@ export async function prepareConcurrentRun(lab, scope) {
     const timeoutMs = plan.sessionTimeoutMs ?? defaultSessionTimeoutMs(plan);
     const requestTimeoutMs = e2bRequestTimeoutMs(env);
     const redactScreenshots = plan.residual.policies?.redactScreenshots === true;
-    const timers = hooks.detachedTimers ?? {};
-    const now = hooks.now ?? Date.now;
-    const proberCadenceMs = hooks.proberCadenceMs ?? DEFAULT_PROBER_CADENCE_MS;
+    const timers = deps.detachedTimers ?? {};
+    const now = deps.now ?? Date.now;
+    const proberCadenceMs = deps.proberCadenceMs ?? DEFAULT_PROBER_CADENCE_MS;
     const seedDigest = seedRecipeDigest(planeStateOf(plan));
     const source = await buildRunSource({
         capturedAt: createdAt,
@@ -134,7 +131,7 @@ export async function prepareConcurrentRun(lab, scope) {
         return {
             ok: false,
             result: {
-                ...fail("HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID", email.message, descriptor.id),
+                ...fail("HUMANISH_SHARED_WORLD_INVALID", email.message, descriptor.id),
                 runId,
             },
         };
@@ -147,7 +144,7 @@ export async function prepareConcurrentRun(lab, scope) {
         input,
         config,
         descriptor,
-        hooks,
+        deps,
         env,
         concurrency,
         runBudget,
@@ -155,6 +152,7 @@ export async function prepareConcurrentRun(lab, scope) {
         openaiApiKey,
         e2bApiKey,
         scrubKnownValues,
+        knownSecretValues,
         cwd,
         run,
         runId,