humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,327 @@
+// Finishing a concurrent shared-world run: publishing its bundle, rendering the Observer, and the
+// lab result with each role's outcome and the one error a run that did not pass reports.
+import { redactText } from "../../evidence/redaction.js";
+import { adapterScoreFailureMessage, applyBrowserAdapterHooks, } from "../../lab/adapter-extension.js";
+import { attachObserverRuntimeStreamUrls } from "../../observer/render.js";
+import { foldScorerFailures, judgeExecution, OUTCOME_POLICIES, participantHarnessFailed, resultOk, sharedWorldShortfall, } from "../../run/judge.js";
+import { participantFactsOf } from "../computer-use/participant-facts.js";
+import { resolveSubjectState } from "../computer-use/subject-projection.js";
+import { actorRunPassed, buildConcurrentSharedWorldBundle, judgeSharedWorldRun, maxSimultaneousWindows, } from "./bundle.js";
+import { planeStateOf } from "./plan.js";
+import { buildSubjectProvenance, hostOriginDigest } from "./provenance.js";
+import { CONCURRENT_SHARED_WORLD_LAB_SCHEMA, } from "./types.js";
+/** The results of a run whose plane did not run (a dry run) or has not reported yet. */
+export function emptyPlaneResults() {
+    return {
+        actorResults: [],
+        runError: undefined,
+        subjectCommit: undefined,
+        subjectSandboxId: undefined,
+        subjectKilled: false,
+        subjectDesktop: undefined,
+        getHostUrl: undefined,
+        publicOriginDigest: undefined,
+        lobbyConvergenceDigest: undefined,
+        handoffTimedOut: false,
+        hostHandoffFailure: undefined,
+        commsArtifactPath: undefined,
+    };
+}
+/** Each participant's outcome, in plan order. */
+function concurrentParticipantResults(actorSpecs, actorResults, dryRun) {
+    const participantOk = (result) => {
+        if (dryRun)
+            return true;
+        return actorRunPassed(result);
+    };
+    return actorSpecs.map((spec, index) => {
+        const result = actorResults[index];
+        const base = { id: spec.planned.id, index: index + 1, persona: spec.persona.id };
+        if (dryRun || !result) {
+            return { ...base, status: "contract_proof_only", ok: dryRun };
+        }
+        const session = result.outcome.session;
+        const thisOk = participantOk(result);
+        return {
+            ...base,
+            status: session ? session.status : "failed",
+            ok: thisOk,
+            window: { startedAt: result.startedAt, endedAt: result.endedAt },
+            ...(session
+                ? {
+                    session: {
+                        status: session.status,
+                        completionReason: session.completionReason,
+                        reason: session.reason,
+                        screenshots: result.outcome.screenshots.length,
+                    },
+                }
+                : {}),
+            ...(result.outcome.sandboxId === undefined
+                ? {}
+                : { sandbox: { sandboxId: result.outcome.sandboxId, killed: result.outcome.killed } }),
+            ...(thisOk
+                ? {}
+                : {
+                    error: {
+                        code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED",
+                        message: result.outcome.sessionError ??
+                            (result.outcome.noEngagement
+                                ? "Actor took no actions and produced no message (likely a blank/still-loading screen); not a credible goal_satisfied."
+                                : result.outcome.selfReportedBlocker
+                                    ? "Actor reported goal_satisfied while its final message described a blocker or asked for missing instructions; not a credible pass."
+                                    : session?.completionReason === "harness_error"
+                                        ? `Participant ended with a harness error: ${session.reason}`
+                                        : "Actor did not produce a terminal session."),
+                    },
+                }),
+        };
+    });
+}
+/** The error a run that did not pass reports, most specific cause first. */
+function concurrentLabError(args) {
+    const { ok, handoffTimedOut, hostHandoffFailure, observer, runError, adapterFailure } = args;
+    const { participantResults, participantCount } = args;
+    if (ok)
+        return undefined;
+    if (handoffTimedOut) {
+        // Checked BEFORE the observer failure: the host never yielded a /lobby/CODE within the
+        // deadline (followers failed closed without opening), which is the ROOT CAUSE — and it can
+        // itself make the Observer unable to render a coherent run. Report the distinct, honest
+        // handoff-timeout code rather than a generic observer/run failure.
+        return {
+            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT",
+            message: runError ??
+                "The host participant never produced a /lobby/CODE URL within the handoff deadline.",
+        };
+    }
+    if (hostHandoffFailure !== undefined) {
+        return { code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED", message: hostHandoffFailure };
+    }
+    // The run's own failure before the Observer's: a run that stopped early (a desktop module that
+    // failed to load, a plane that failed to start) leaves a bundle verify then refuses, and naming
+    // only that refusal would hide the cause. The execution failures keep the same order (run, then
+    // evidence).
+    if (runError) {
+        return {
+            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED",
+            message: observer.ok ? runError : `${runError} The run bundle it left failed verification.`,
+        };
+    }
+    if (!observer.ok) {
+        return {
+            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED",
+            message: observer.error?.message ?? "Observer failed for the concurrent shared-world run.",
+        };
+    }
+    if (adapterFailure !== undefined) {
+        return { code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED", message: adapterFailure };
+    }
+    const passed = participantResults.filter((result) => result.ok).length;
+    if (passed === participantCount && args.shortfall !== undefined) {
+        return {
+            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED",
+            message: `Concurrent shared-world run did not run coherently. ${args.shortfall}`,
+        };
+    }
+    if (passed === participantCount && args.executionFailure !== undefined) {
+        return {
+            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED",
+            message: `Concurrent shared-world run failed as an execution. ${args.executionFailure}`,
+        };
+    }
+    return {
+        code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED",
+        message: `Concurrent shared-world run did not run coherently: ${passed}/${participantCount} actor(s) reached a terminal, engaged passed session.`,
+    };
+}
+/**
+ * The refusal envelope for a run that stops before it has results: the requested cwd, no roles,
+ * and the run id the caller asked for, if any. `actor` is the label when a refusal names none.
+ */
+export function concurrentLabFailure(envelope) {
+    return (code, message, actorLabel) => ({
+        schema: CONCURRENT_SHARED_WORLD_LAB_SCHEMA,
+        ok: false,
+        cwd: envelope.cwd,
+        labId: envelope.labId,
+        actor: actorLabel ?? envelope.actor,
+        topology: "shared-world",
+        topologyMode: "concurrent",
+        roleCount: envelope.participantCount,
+        concurrency: envelope.concurrency,
+        dryRun: envelope.dryRun,
+        runId: envelope.runId ?? "not-created",
+        roles: [],
+        warnings: [],
+        error: { code, message },
+    });
+}
+/**
+ * The run's execution failures: a run error (the handoff, the plane), each seat whose session
+ * failed in the harness, and an Observer that failed.
+ */
+function sharedWorldExecutionFailures(args) {
+    const { runError, actorResults, observer } = args;
+    return [
+        ...(runError === undefined ? [] : [{ kind: "run", message: runError }]),
+        ...actorResults
+            .filter((result) => participantHarnessFailed(participantFactsOf(result.outcome)))
+            .map((result) => ({
+            kind: "harness",
+            message: `${result.spec.planned.id}: ${result.outcome.sessionError ?? result.outcome.session?.reason ?? "harness error"}`,
+        })),
+        ...actorResults.flatMap((result) => result.outcome.providerCleanupError === undefined
+            ? []
+            : [
+                {
+                    kind: "provider-cleanup",
+                    message: `${result.spec.planned.id}: ${result.outcome.providerCleanupError}`,
+                },
+            ]),
+        ...(observer.ok
+            ? []
+            : [
+                {
+                    kind: "evidence",
+                    message: observer.error?.message ?? "Observer failed for the concurrent shared-world run.",
+                },
+            ]),
+    ];
+}
+/** Builds and publishes the bundle, renders the Observer and returns the lab result. */
+export async function finishConcurrentRun(ctx, live, results, plane) {
+    const { plan, input, descriptor, hooks, actorSpecs, run, runId, createdAt } = ctx;
+    const participantCount = plan.plane.participants.length;
+    const { cwd, concurrency, source, seedDigest, receiving, warnings, scrubKnownValues } = ctx;
+    const { dryRun } = plan;
+    const physicalArtifactRoot = ctx.runPaths.physicalRunRoot;
+    const { planeClass, localTreeRoute, localTreeArchive, publicRepo, subjectEnvNames } = plane;
+    const { stateStepRecords, stateSnapshots, declaredOriginDigest } = plane;
+    const { actorResults, runError, subjectCommit, subjectSandboxId, subjectKilled } = results;
+    const { getHostUrl, publicOriginDigest, lobbyConvergenceDigest } = results;
+    const { handoffTimedOut, hostHandoffFailure, commsArtifactPath, subjectDesktop } = results;
+    // Subject provenance: external-public is the operator-declared, operator-owned public deployment
+    // (neither provisioned nor seeded); the provisioned path builds clone/local-tree provenance.
+    const subject = planeClass === "external-public"
+        ? { source: "app-url", envNames: [], state: { provenance: "external-public" } }
+        : buildSubjectProvenance({
+            localTreeRoute,
+            publicRepo,
+            subjectCommit: localTreeRoute ? localTreeArchive?.git?.commit : subjectCommit,
+            localTreeArchive,
+            subjectEnvNames,
+            state: resolveSubjectState({
+                declared: planeStateOf(plan),
+                dryRun,
+                executed: stateStepRecords,
+            }),
+        });
+    const planeCommit = localTreeRoute ? localTreeArchive?.git?.commit : subjectCommit;
+    // Collect per-actor warnings (each lane's own teardown/raw-screenshot notes).
+    for (const result of actorResults) {
+        warnings.push(...result.outcome.warnings);
+    }
+    const bundleArgs = {
+        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        plan,
+        descriptor,
+        createdAt,
+        dryRun,
+        runId,
+        source,
+        actorSpecs,
+        actorResults,
+        stateSnapshots,
+        subject,
+        seedDigest,
+        planeClass,
+        ...(planeCommit === undefined ? {} : { subjectCommit: planeCommit }),
+        ...(getHostUrl === undefined ? {} : { hostDigest: hostOriginDigest(getHostUrl) }),
+        ...(publicOriginDigest === undefined ? {} : { publicOriginDigest }),
+        ...(declaredOriginDigest === undefined ? {} : { declaredOriginDigest }),
+        ...(lobbyConvergenceDigest === undefined ? {} : { lobbyConvergenceDigest }),
+        ...(commsArtifactPath === undefined ? {} : { commsArtifactPath }),
+        ...(runError === undefined ? {} : { runError }),
+        ...(subjectDesktop === undefined ? {} : { subjectDesktop }),
+    };
+    // One judgment for the whole run: the bundle's verdict and the result's ok both read it.
+    const judgment = judgeSharedWorldRun(bundleArgs);
+    const bundle = buildConcurrentSharedWorldBundle({ ...bundleArgs, judgment });
+    const adapterWarnings = [];
+    const scorerResult = await applyBrowserAdapterHooks({
+        hooks,
+        bundle,
+        context: {
+            bundle,
+            runDir: physicalArtifactRoot,
+            labId: plan.labId,
+            runId,
+            actor: descriptor.id,
+            backend: "concurrent-shared-world",
+            dryRun,
+            laneCount: participantCount,
+        },
+        sanitize: (text) => redactText(scrubKnownValues(text)),
+        warnings: adapterWarnings,
+        hookLabel: "sharedWorldHooks",
+        ...(input.scorerProvenance === undefined ? {} : { scorerProvenance: input.scorerProvenance }),
+    });
+    // The one final verdict fold: scoring can only make the judged verdict stricter.
+    bundle.review = foldScorerFailures(bundle.review, scorerResult.failures);
+    if (receiving)
+        bundle.commsReceiving = receiving.snapshot();
+    const finished = await run.finish(bundle);
+    const observer = await finished.renderObserver();
+    if (observer.ok && live.observer) {
+        attachObserverRuntimeStreamUrls(observer, live.streamUrls);
+    }
+    // Concurrent "ok": every actor must produce a terminal, engaged PASSED session, and the seats
+    // must show the concurrency verify requires of a pass (judgeSharedWorld). This is a
+    // harness/session-credibility gate, not mission-completion proof; a failed actor trace cannot
+    // make the route green just because the harness got a terminal.
+    const adapterFailure = adapterScoreFailureMessage(bundle);
+    const policy = OUTCOME_POLICIES["shared-world"];
+    const execution = judgeExecution(sharedWorldExecutionFailures({ runError, actorResults, observer }), policy);
+    const ok = resultOk({ judgment, execution, scorerFailures: scorerResult.failures, policy });
+    const overlapProven = !dryRun && judgment.world.overlap;
+    const participantResults = concurrentParticipantResults(actorSpecs, actorResults, dryRun);
+    const errorResult = concurrentLabError({
+        ok,
+        handoffTimedOut,
+        hostHandoffFailure,
+        observer,
+        runError,
+        adapterFailure,
+        participantResults,
+        participantCount,
+        shortfall: dryRun ? undefined : sharedWorldShortfall(judgment.world),
+        executionFailure: execution.failures[0]?.message,
+    });
+    const result = {
+        schema: CONCURRENT_SHARED_WORLD_LAB_SCHEMA,
+        ok,
+        cwd,
+        labId: plan.labId,
+        actor: descriptor.id,
+        topology: "shared-world",
+        topologyMode: "concurrent",
+        roleCount: participantCount,
+        concurrency,
+        dryRun,
+        runId,
+        ...(getHostUrl === undefined ? {} : { host: getHostUrl }),
+        ...(subjectSandboxId === undefined
+            ? {}
+            : { subjectSandbox: { sandboxId: subjectSandboxId, killed: subjectKilled } }),
+        ...(dryRun ? {} : { overlapProven }),
+        ...(dryRun ? {} : { maxSimultaneousLanes: maxSimultaneousWindows(actorResults) }),
+        subject,
+        roles: participantResults,
+        observer,
+        warnings: [...warnings, ...adapterWarnings, ...observer.warnings],
+        ...(errorResult === undefined ? {} : { error: errorResult }),
+    };
+    await finished.recordOutcome({ ok, execution });
+    return result;
+}

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

@@ -0,0 +1,21 @@
+import { type SharedWorldRefusal } from "./plan.js";
+import type { SharedWorldPlan } from "../../lab/plan-types.js";
+import type { AdmittedPlan } from "../../run-lab.js";
+import type { LabConfig } from "../../lab/types.js";
+import { type ConcurrentSharedWorldLabResult, type SharedWorldRunInput, type RunConcurrentSharedWorldLabOptions } from "./types.js";
+/**
+ * The library entry for a shared-world lab. It plans the config with planSharedWorldLab and runs
+ * the plan with runSharedWorldPlan, whose run scope and withTransientCommsSecrets wrapper cover the
+ * run and its analysis.
+ */
+export declare function runConcurrentSharedWorld(options: RunConcurrentSharedWorldLabOptions): Promise<ConcurrentSharedWorldLabResult>;
+/** A refused shared-world lab's result: the route's envelope, and a refusal's analysis record. */
+export declare function sharedWorldLabRefusal(options: RunConcurrentSharedWorldLabOptions, refusal: SharedWorldRefusal): Promise<ConcurrentSharedWorldLabResult>;
+/**
+ * runLab's step for a shared-world plan. It runs a live plan's local checks (the keys, a local
+ * agent's sign-in and the subject env) before any run scope opens, so the CLI can present their refusal before it loads a
+ * declared scorer, and returns the run that continues from them with that scorer.
+ */
+export declare function admitSharedWorldPlan(plan: SharedWorldPlan, input: SharedWorldRunInput, config: LabConfig): Promise<AdmittedPlan<"shared-world">>;
+/** Run a shared-world plan: its local checks, then the run. */
+export declare function runSharedWorldPlan(plan: SharedWorldPlan, input: SharedWorldRunInput, config: LabConfig): Promise<ConcurrentSharedWorldLabResult>;

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

@@ -0,0 +1,277 @@
+// 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
+// pieces + the getHost wrapper:
+//
+//   - 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.
+//   - 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.
+//
+// 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
+// `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.
+//
+// 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
+// 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
+// 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).
+import path from "node:path";
+import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
+import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import { scrubLiterals } from "../../evidence/redaction.js";
+import { describeMissingKeys } from "../../keys/key-resolution.js";
+import { withTransientCommsSecrets } from "../../run/transient-comms-secrets.js";
+import { runScope } from "../../run/run.js";
+import { makeCuaRunBudget } from "../computer-use/participant-model.js";
+import { runExternalPublicPlane } from "./external-public.js";
+import { planSharedWorldLab, sharedWorldDescriptorOf } from "./plan.js";
+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 {} 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",
+};
+/**
+ * The library entry for a shared-world lab. It plans the config with planSharedWorldLab and runs
+ * the plan with runSharedWorldPlan, whose run scope and withTransientCommsSecrets wrapper cover the
+ * run and its analysis.
+ */
+export async function runConcurrentSharedWorld(options) {
+    const { config, dryRun, lab, ...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 ?? {},
+    });
+    if (planned.ok)
+        return runSharedWorldPlan(planned.plan, input, config);
+    return sharedWorldLabRefusal(options, planned.refusal);
+}
+/** A refused shared-world lab's result: the route's envelope, and a refusal's analysis record. */
+export function sharedWorldLabRefusal(options, refusal) {
+    const { config, dryRun } = options;
+    const declared = rosterOf(config.actors[0]) ?? [];
+    const fail = concurrentLabFailure({
+        cwd: path.resolve(options.cwd),
+        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).
+        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" });
+}
+/**
+ * runLab's step for a shared-world plan. It runs a live plan's local checks (the keys, a local
+ * agent's sign-in and the subject env) before any run scope opens, so the CLI can present their refusal before it loads a
+ * declared scorer, and returns the run that continues from them with that scorer.
+ */
+export async function admitSharedWorldPlan(plan, input, config) {
+    const refused = await admitSharedWorldRun(plan, input);
+    if (refused)
+        return { ok: false, outcome: sharedWorldOutcome(refused) };
+    return {
+        ok: true,
+        run: async (scorer) => sharedWorldOutcome(await runAdmittedSharedWorldRun(plan, sharedWorldInputWithScorer(input, scorer), config)),
+    };
+}
+function sharedWorldOutcome(result) {
+    return { route: "shared-world", backend: "concurrent-shared-world", result };
+}
+/** Run a shared-world plan: its local checks, then the run. */
+export async function runSharedWorldPlan(plan, input, config) {
+    const refused = await admitSharedWorldRun(plan, input);
+    return refused ?? runAdmittedSharedWorldRun(plan, input, config);
+}
+/**
+ * A live plan's local checks, made outside any run scope: the keys, a local agent's sign-in, then
+ * the subject env. A refusal is the result runSharedWorldPlan returns for it, with the analysis
+ * record of a run that never started.
+ */
+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 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)}`);
+    }
+    if (plan.brain.kind === "local-agent") {
+        // A missing or signed-out agent found after the seats' 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).`);
+    }
+    return undefined;
+}
+/**
+ * Runs an admitted plan in its own run scope, then its automatic analysis. The
+ * withTransientCommsSecrets wrapper scopes any email secret the run registers to this run and its
+ * analysis.
+ */
+function runAdmittedSharedWorldRun(plan, input, config) {
+    return withTransientCommsSecrets(async () => {
+        const { result, finished } = await runScope((scope) => runPlanInScope(plan, input, config, scope));
+        return completeSharedWorldAnalysis(plan, input, result, finished);
+    });
+}
+function completeSharedWorldAnalysis(plan, input, result, finished) {
+    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input.automaticAnalysis, {
+        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
+        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
+    });
+}
+/** The route's envelope for a run that stops before its bundle. */
+function sharedWorldFailure(plan, input) {
+    return concurrentLabFailure({
+        cwd: path.resolve(input.cwd),
+        labId: plan.labId,
+        actor: plan.actor,
+        participantCount: plan.plane.participants.length,
+        concurrency: plan.concurrency,
+        dryRun: plan.dryRun,
+        runId: input.runId,
+    });
+}
+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 fail = sharedWorldFailure(plan, input);
+    const descriptor = sharedWorldDescriptorOf(plan.actor);
+    const planeClass = plan.plane.kind === "external-public" ? "external-public" : "provisioned-getHost";
+    const { maxTotalUsd } = plan.caps;
+    const runBudget = !dryRun && maxTotalUsd !== undefined ? makeCuaRunBudget(maxTotalUsd) : undefined;
+    // The provisioned plane's subject; the external-public plane has none.
+    const subject = plan.plane.kind === "provisioned" ? plan.plane.subject : undefined;
+    const serve = subject?.serve;
+    const localTreeRoute = subject?.kind === "local-tree";
+    const subjectRepo = plan.residual.subject.repos?.[0] ?? "";
+    const subjectEnvNames = [...(subject?.env ?? [])];
+    const checkpoints = [...(subject?.state.checkpoint ?? [])];
+    const runSession = hooks.runSession ?? descriptor.runSession;
+    const openaiApiKey = env.OPENAI_API_KEY?.trim() ?? "";
+    const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
+    const knownSecretValues = [
+        openaiApiKey,
+        e2bApiKey,
+        ...subjectEnvNames.map((name) => env[name] ?? ""),
+        ...checkpoints.flatMap((probe) => probe.redact ?? []),
+    ].filter((value) => value.length >= 4);
+    const scrubKnownValues = scrubLiterals(knownSecretValues);
+    const redactRepoLabel = plan.residual.policies?.redactRepos ?? subjectEnvNames.includes("GITHUB_TOKEN");
+    const publicRepo = redactRepoLabel ? "repo-01" : subjectRepo;
+    const hasGithubToken = subjectEnvNames.includes("GITHUB_TOKEN");
+    const prepared = await prepareConcurrentRun({
+        plan,
+        input,
+        config,
+        requestedCwd,
+        hooks,
+        env,
+        descriptor,
+        planeClass,
+        runBudget,
+        runSession,
+        serve,
+        localTreeRoute,
+        subjectRepo,
+        subjectEnvNames,
+        checkpoints,
+        openaiApiKey,
+        e2bApiKey,
+        knownSecretValues,
+        scrubKnownValues,
+        publicRepo,
+        hasGithubToken,
+        fail,
+    }, scope);
+    if (!prepared.ok)
+        return prepared.result;
+    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 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`.
+ */
+async function runPlane(ctx, live, results, plane) {
+    const { dryRun } = ctx.plan;
+    try {
+        if (!dryRun && plane.planeClass === "provisioned-getHost") {
+            // Defense-in-depth: concurrentSharedWorldValidationReason already required serve above.
+            if (!plane.provisioned)
+                return false;
+            const { commsArtifactPath, ...outcome } = await runProvisionedPlane(ctx, live, plane.provisioned);
+            Object.assign(results, outcome);
+            if (commsArtifactPath !== undefined)
+                results.commsArtifactPath = commsArtifactPath;
+        }
+        if (!dryRun && plane.planeClass === "external-public") {
+            const { commsArtifactPath, ...outcome } = await runExternalPublicPlane(ctx, live, plane.externalWiring);
+            Object.assign(results, outcome);
+            if (commsArtifactPath !== undefined)
+                results.commsArtifactPath = commsArtifactPath;
+        }
+    }
+    finally {
+        try {
+            await ctx.receiving?.finish();
+        }
+        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.
+        await live.flush?.stop();
+    }
+    return true;
+}

package/dist/routes/shared-world/seat-records.d.ts

@@ -0,0 +1,20 @@
+import type { RunEvent, RunSimulation } from "../../run/bundle.js";
+import type { RunStream } from "../../run/streams.js";
+import type { DesktopParticipantRun } from "../computer-use/types.js";
+import type { ConcurrentBundleArgs } from "./types.js";
+/** What every participant's records share. */
+export interface SharedWorldRecordContext {
+    args: ConcurrentBundleArgs;
+    external: boolean;
+    inProgress: boolean;
+    /** The public-safe plane label: never the raw getHost URL or public origin. */
+    appUrl: string;
+    /** Numbers events in the order they are pushed. */
+    nextEventId: (suffix: string) => string;
+}
+/** One participant's simulation, stream and events. */
+export declare function sharedWorldParticipantRecords(ctx: SharedWorldRecordContext, spec: DesktopParticipantRun, index: number): {
+    simulation: RunSimulation;
+    stream: RunStream;
+    events: RunEvent[];
+};