humanish 0.40.0 → 0.42.0

package/dist/cua-actor-lab.js

@@ -31,7 +31,7 @@ import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS, chromiumEvidenceProfilePreferencesJson
 import { DEFAULT_OPENAI_CU_MODEL } from "./openai-responses-cu.js";
 import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 import { probeUrl, readDetachedLog, runDetachedStep, startDetachedProcess } from "./e2b-detached.js";
-import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, deployCommsCatch, refreshInboxSurface, writeInboxSurface } from "./comms-sandbox-catch.js";
+import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, collectExternalCommsThread, deployCommsCatch, externalCatchHealthy, externalInboxUrl, refreshInboxSurface, writeInboxSurface } from "./comms-sandbox-catch.js";
 import { FakeInbox } from "./comms-fake-inbox.js";
 import { buildOriginMap } from "./comms-inbox.js";
 import { DEFAULT_DEVICE_PRESET, isDevicePresetName, resolveDevicePreset } from "./device-presets.js";
@@ -43,12 +43,13 @@ import { buildObserverData } from "./observer-data.js";
 import { corepackCommandFor, needsNodeRuntime, nodeBootstrapCommand } from "./subject-runtime.js";
 import { personaToDirectives, renderPersonaPromptSection } from "./persona.js";
 import { labPersonaIds, resolveCommittedPersonas } from "./persona-resolve.js";
+import { renderTaskPrompt } from "./tasks.js";
 import { attachObserverRuntimeStreamUrls, renderObserver } from "./observer.js";
 import { containsSensitive, digestText, redactedTail, redactText } from "./redaction.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareContainedOutputDirectory, prepareSelectedOutputDirectory, writeContainedOutputFile, writePreparedRunLatestPointer } from "./selected-output-paths.js";
 import { prepareRunArtifactPaths, validatePreparedRunArtifactPaths } from "./run-paths.js";
 import { createLocalTreeArchive } from "./source-archive.js";
-import { buildRunSource, loadRunBundle, PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA } from "./run.js";
+import { buildRunSource, loadRunBundle, PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA, aggregateTaskFunnels, formatParticipantOutcomes, formatStudyTaskFunnel, tallyParticipantOutcomes } from "./run.js";
 import { estimateActorCost, estimateDesktopCost, MODEL_RATES, round6 } from "./pricing.js";
 export const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
 // The only fan-out topology this slice ships: N lanes = N independent E2B desktop sandboxes,
@@ -61,7 +62,28 @@ export const CUA_ACTOR_LAB_PROVIDER_METADATA = {
     mode: "cua-actor-lab",
     tool: "humanish"
 };
-const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
+// The DEFAULT session budget, sized so a study can FINISH (docs/principles/three-roles.md: a
+// session ends because the participant is done, not because a timer fired — the time-box is a
+// session-level cap a researcher sets generously; spend protection is the dollar caps' job).
+// The old 300s default ended real signup studies mid-flow: observed studies run 16-40 turns at
+// ~5-6s per turn BEFORE any email wait, so five minutes was the biggest single source of
+// budget_reached endings that read as participant failures.
+//
+// App-url and in-process routes default to 30 minutes. Provisioned routes (clone/local-tree)
+// default to whatever the 1-hour sandbox cap leaves after provisioning, declared state seeding,
+// and the teardown buffer — 20 minutes on a stateless clone — floored at the old five minutes so
+// a state-heavy lab still gets a session at all. An EXPLICIT execution.timeoutMs is never
+// adjusted: when it cannot be provisioned, the plan-time cap refusal shows the arithmetic.
+const DEFAULT_APP_URL_SESSION_TIMEOUT_MS = 30 * 60_000;
+const MIN_DERIVED_SESSION_TIMEOUT_MS = 5 * 60_000;
+function defaultSessionTimeoutMs(config) {
+    const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
+    if (!provisionedRoute)
+        return DEFAULT_APP_URL_SESSION_TIMEOUT_MS;
+    const stateBudgetMs = (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
+    const room = MAX_SANDBOX_MS - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
+    return Math.max(MIN_DERIVED_SESSION_TIMEOUT_MS, Math.min(DEFAULT_APP_URL_SESSION_TIMEOUT_MS, room));
+}
 // Settle after opening the browser, before the first screenshot — long enough for a cold
 // browser + page load to paint (2s captured a blank desktop; the render empirically needs ~6-9s).
 const BROWSER_SETTLE_MS = 8_000;
@@ -101,6 +123,10 @@ export function composeLaneInstructions(args) {
     const deviceLine = preset.isMobile
         ? `You are a mobile user on a ${name} device (${preset.width}x${preset.height} @${preset.deviceScaleFactor}x). Expect a mobile/touch layout.`
         : `You are a desktop user (${name}, ${preset.width}x${preset.height}).`;
+    // The protocol as the PARTICIPANT reads it: numbered goals, nothing else. The success criteria
+    // are the researcher's instrument and must never reach this prompt — a persona told how it will
+    // be measured optimizes for the measurement instead of using the product (src/tasks.ts).
+    const taskLines = renderTaskPrompt(args.tasks ?? []);
     // A resolved persona contributes its compiled directives (friction tolerance, skill bias,
     // accessibility behavior, constraints) through the SAME persona.ts compiler the terminal lane
     // uses, so one persona file means one behavior across every route.
@@ -112,6 +138,7 @@ export function composeLaneInstructions(args) {
         personaLine,
         deviceLine,
         args.mission,
+        taskLines,
         args.instruction ? `Lane focus: ${args.instruction}` : undefined
     ].filter((part) => Boolean(part));
     const instructions = parts.join("\n\n");
@@ -212,7 +239,7 @@ export function resolveLaneDevice(config, lane) {
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
  *  costs the same wall-clock room either way. */
 function resolvePerLaneSandboxMs(config) {
-    const timeoutMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const timeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config);
     const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
     const stateBudgetMs = provisionedRoute
         ? (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0)
@@ -244,6 +271,7 @@ function laneSpecsAndPlan(config, opts = {}) {
     const env = opts.env ?? {};
     const actor = config.actors[0];
     const mission = actor?.mission ?? DEFAULT_MISSION;
+    const tasks = actor?.tasks;
     const roster = actor?.lanes;
     const laneCount = roster ? roster.length : Math.max(1, opts.countOverride ?? actor?.count ?? 1);
     const lanes = [];
@@ -257,6 +285,7 @@ function laneSpecsAndPlan(config, opts = {}) {
         const resolvedPersona = personaId === undefined ? undefined : opts.personas?.get(personaId);
         const composed = composeLaneInstructions({
             mission,
+            ...(tasks === undefined ? {} : { tasks }),
             ...(personaId === undefined ? {} : { persona: personaId }),
             ...(resolvedPersona === undefined ? {} : { resolvedPersona }),
             ...(((roster ? lane?.instruction : actor?.laneFocus?.instruction)) === undefined ? {} : { instruction: (roster ? lane?.instruction : actor?.laneFocus?.instruction) }),
@@ -274,6 +303,7 @@ function laneSpecsAndPlan(config, opts = {}) {
             instructions: composed.instructions,
             ...(lane?.target === undefined ? {} : { targetUrl: lane.target }),
             ...((lane?.stopWhen ?? actor?.stopWhen) === undefined ? {} : { stopWhen: (lane?.stopWhen ?? actor?.stopWhen) }),
+            ...(tasks === undefined ? {} : { tasks }),
             deviceName: device.name,
             devicePreset: device.preset,
             resolution: device.resolution,
@@ -283,7 +313,7 @@ function laneSpecsAndPlan(config, opts = {}) {
     }
     const resolved = resolveCuaConcurrency(config, laneCount, env);
     const concurrency = resolved.bound;
-    const perLaneSessionBudgetMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const perLaneSessionBudgetMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config);
     const perLaneSandboxMs = resolvePerLaneSandboxMs(config);
     const plan = {
         strategy: CUA_FANOUT_STRATEGY,
@@ -474,6 +504,20 @@ function phaseEventIdSuffix(type) {
         .replace(/\.(started|completed)$/, "")
         .replace(/\./g, "-");
 }
+export function makeCuaRunBudget(maxTotalUsd) {
+    const laneEstimates = new Map();
+    return {
+        maxTotalUsd,
+        note(laneId, estimateUsd) {
+            if (estimateUsd !== null)
+                laneEstimates.set(laneId, estimateUsd);
+            let total = 0;
+            for (const value of laneEstimates.values())
+                total += value;
+            return total;
+        }
+    };
+}
 /** Build a lane's writeScreenshot closure: writes under screenshots/<screenshotDir>/ and records
  *  the relative path the trace references (screenshots/<name> at N=1; screenshots/<laneId>/<name>
  *  at N>1). */
@@ -785,7 +829,16 @@ export function chromeCdpPortResolutionScript(endpoint) {
 }
 /** Shared CDP page-selection preamble: pinned target id first, then this lane's target URL,
  *  then a single-page fallback; never an arbitrary page from a multi-page endpoint. */
-function chromeCdpPageSelectionScript(endpoint, targetId) {
+function chromeCdpPageSelectionScript(endpoint, targetId, 
+/**
+ * "pinned" (default): the launch-time target, for measurements about the ORIGINAL window
+ * (geometry). "active": the tab the participant is driving NOW — Chrome's /json lists page
+ * targets most-recently-focused first. The state observer must follow the participant: a
+ * verification link that opens in a NEW tab left the pinned observer reading the old tab
+ * forever, so the observed URL never changed again and stopWhen/task criteria went blind
+ * (a live run's funnel read reach-dashboard 0/2 under a screenshot OF the dashboard).
+ */
+prefer = "pinned") {
     return [
         ...chromeCdpPortResolutionScript(endpoint),
         "const pages = await fetch('http://127.0.0.1:' + cdpPort + '/json').then((r) => r.json()).catch(() => []);",
@@ -793,22 +846,27 @@ function chromeCdpPageSelectionScript(endpoint, targetId) {
         `const expectedTargetUrl = ${JSON.stringify(endpoint.targetUrl)};`,
         "const normalizeUrl = (value) => String(value || '').replace(/\\/$/, '');",
         "const httpPages = Array.isArray(pages) ? pages.filter((entry) => entry && entry.type === 'page' && /^https?:/.test(String(entry.url || ''))) : [];",
-        "const page = expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : (httpPages.find((entry) => normalizeUrl(entry.url) === normalizeUrl(expectedTargetUrl)) || (httpPages.length === 1 ? httpPages[0] : undefined));"
+        prefer === "active"
+            ? "const page = httpPages[0] || (expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : undefined);"
+            : "const page = expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : (httpPages.find((entry) => normalizeUrl(entry.url) === normalizeUrl(expectedTargetUrl)) || (httpPages.length === 1 ? httpPages[0] : undefined));"
     ];
 }
 export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, targetId) {
     return async () => {
         const script = [
-            ...chromeCdpPageSelectionScript(endpoint, targetId),
+            // "active": follow the participant to whatever tab they are driving now — never pin the
+            // state observer to the launch tab (see chromeCdpPageSelectionScript).
+            ...chromeCdpPageSelectionScript(endpoint, targetId, "active"),
             "if (!page) { console.log('{}'); process.exit(0); }",
             "let text = '';",
+            "let scrollY = undefined;",
             "let url = String(page.url || '');",
             "let title = String(page.title || '');",
             "if (typeof WebSocket === 'function' && page.webSocketDebuggerUrl) {",
             "  const ws = new WebSocket(page.webSocketDebuggerUrl);",
             "  const result = await new Promise((resolve) => {",
             "    const timer = setTimeout(() => resolve(undefined), 1500);",
-            "    ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { returnByValue: true, expression: '({ url: location.href, title: document.title, text: (document.body && document.body.innerText || \"\").slice(0, 20000) })' } }));",
+            "    ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { returnByValue: true, expression: '({ url: location.href, title: document.title, text: (document.body && document.body.innerText || \"\").slice(0, 20000), scrollY: (window.scrollY || 0) })' } }));",
             "    ws.onmessage = (event) => {",
             "      try {",
             "        const payload = JSON.parse(String(event.data));",
@@ -823,9 +881,10 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoi
             "    url = typeof result.url === 'string' ? result.url : url;",
             "    title = typeof result.title === 'string' ? result.title : title;",
             "    text = typeof result.text === 'string' ? result.text : '';",
+            "    scrollY = typeof result.scrollY === 'number' ? result.scrollY : undefined;",
             "  }",
             "}",
-            "console.log(JSON.stringify({ url, title, text }));"
+            "console.log(JSON.stringify({ url, title, text, scrollY }));"
         ].join("\n");
         const result = await desktop.commands.run(`node --input-type=module -e ${shellSingleQuote(script)}`, {
             requestTimeoutMs,
@@ -843,7 +902,8 @@ export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoi
             return {
                 ...(typeof record.url === "string" && record.url.length > 0 ? { url: record.url } : {}),
                 ...(typeof record.title === "string" && record.title.length > 0 ? { title: record.title } : {}),
-                ...(typeof record.text === "string" && record.text.length > 0 ? { text: record.text } : {})
+                ...(typeof record.text === "string" && record.text.length > 0 ? { text: record.text } : {}),
+                ...(typeof record.scrollY === "number" && Number.isFinite(record.scrollY) ? { scrollY: record.scrollY } : {})
             };
         }
         catch {
@@ -1380,10 +1440,14 @@ export async function runCuaLane(spec, deps) {
             const maxUsd = config.execution?.caps?.maxUsd;
             const sessionOptions = {
                 // Tell the persona where its inbox is — but only when comms is live AND this lane has a declared
-                // recipient it can actually receive mail into (else it would stall on an inbox that stays empty).
+                // recipient it can actually receive mail into (else it would stall on an inbox that stays
+                // empty). Two comms planes, mutually exclusive by parse: the in-sandbox catch humanish
+                // deployed, or the adopter-hosted one (#380).
                 instructions: commsEmail && commsInboxUrl && deployedComms?.ready && laneHasInboxRecipient(commsEmail, spec.laneId)
                     ? withInboxMission(spec, commsInboxUrl, inboxRecipientFor(commsEmail, spec.laneId)?.address).instructions
-                    : spec.instructions,
+                    : deps.externalComms && laneHasInboxRecipient(deps.externalComms.email, spec.laneId)
+                        ? withInboxMission(spec, deps.externalComms.inboxUrl, inboxRecipientFor(deps.externalComms.email, spec.laneId)?.address).instructions
+                        : spec.instructions,
                 persona: spec.persona,
                 timeoutMs: deps.timeoutMs,
                 openai: {
@@ -1414,6 +1478,24 @@ export async function runCuaLane(spec, deps) {
                 ...(spec.idleSteps === undefined ? {} : { idleSteps: spec.idleSteps }),
                 ...(spec.noProgressSteps === undefined ? {} : { noProgressSteps: spec.noProgressSteps }),
                 ...(spec.stopWhen === undefined ? {} : { stopWhen: spec.stopWhen }),
+                ...(spec.tasks === undefined ? {} : { tasks: spec.tasks }),
+                // The STUDY budget (#299): this lane notes its own running estimate on the shared ledger
+                // and stops when the RUN total crosses the cap — independent of the per-lane maxUsd above.
+                ...(deps.runBudget === undefined
+                    ? {}
+                    : {
+                        overRunBudget: (usage) => {
+                            const estimate = estimateActorCost({
+                                input: usage.input,
+                                output: usage.output,
+                                ...(usage.cachedInput > 0 ? { cachedInput: usage.cachedInput } : {})
+                            }, capModelId).estimatedCostUsd;
+                            const totalUsd = deps.runBudget.note(spec.laneId, estimate);
+                            return totalUsd > deps.runBudget.maxTotalUsd
+                                ? `study budget reached: the run's estimated model spend $${round6(totalUsd)} crossed execution.caps.maxTotalUsd=$${deps.runBudget.maxTotalUsd}; this lane stops here and sibling lanes stop at their next turn`
+                                : null;
+                        }
+                    }),
                 ...(deps.onObservedUrl === undefined ? {} : { onObservedUrl: deps.onObservedUrl }),
                 ...(deps.onMessage === undefined ? {} : { onMessage: deps.onMessage }),
                 ...(deps.onScreenshot === undefined ? {} : { onScreenshot: deps.onScreenshot })
@@ -1626,7 +1708,8 @@ async function runInProcessLane(spec, deps) {
             redactScreenshots: deps.redactScreenshots,
             scrubText: deps.scrubKnownValues,
             writeScreenshot,
-            ...(spec.stopWhen === undefined ? {} : { stopWhen: spec.stopWhen })
+            ...(spec.stopWhen === undefined ? {} : { stopWhen: spec.stopWhen }),
+            ...(spec.tasks === undefined ? {} : { tasks: spec.tasks })
         };
         session = await deps.runSession(sessionOptions);
     }
@@ -1960,6 +2043,15 @@ export async function runCuaActorLab(options) {
     const runSession = hooks.runSession ?? descriptor.runSession;
     const inProcessRoute = hooks.buildExecutor !== undefined;
     const localAppSubject = config.subject.source === "local-app";
+    // Adopter-hosted comms plane on the app-url route (#380): humanish provisions no subject here,
+    // so it cannot host a catch — the OPERATOR runs one, and humanish still does every other part
+    // of the funnel: tells each persona its address and inbox URL, drains the catch over HTTP after
+    // the lanes, and writes the same digest-only evidence. Declaring `external` previously did
+    // nothing on this route (and, per #387, on every other) while its docs said otherwise.
+    const externalCommsConfig = !cloneRoute && !localTreeRoute && !inProcessRoute
+        ? config.comms?.email?.external
+        : undefined;
+    const externalCommsEmail = externalCommsConfig ? config.comms?.email : undefined;
     // Engine re-enforcement of the clone-route structure (library API surface).
     if (cloneRoute && (!serve || !subjectRepo || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(subjectRepo))) {
         return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", !serve
@@ -2017,7 +2109,7 @@ export async function runCuaActorLab(options) {
     const derivedSandboxMs = resolvePerLaneSandboxMs(config);
     if (derivedSandboxMs > MAX_SANDBOX_MS) {
         const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
-        const sessionMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+        const sessionMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config);
         const headroomMs = derivedSandboxMs - sessionMs;
         return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", `execution.timeoutMs ${Math.round(sessionMs / 60_000)}m derives a ${Math.round(derivedSandboxMs / 60_000)}m sandbox deadline, and a sandbox may not live longer than ${MAX_SANDBOX_MS / 60_000}m. The deadline is the session budget plus ${Math.round(headroomMs / 60_000)}m of provisioning and teardown headroom${provisionedRoute ? " (this route clones, installs, builds and serves the subject before the actor starts)" : ""}. Lower execution.timeoutMs to at most ${Math.round((MAX_SANDBOX_MS - headroomMs) / 60_000)}m, or set execution.desktop.sandboxTimeoutMs explicitly.`, descriptor.id);
     }
@@ -2099,19 +2191,26 @@ export async function runCuaActorLab(options) {
         // runaway-retry protection. Refuse at PREFLIGHT (before any sandbox/spend) rather than run
         // uncapped: an unenforceable cap is more dangerous than none. The operator adds a rate to
         // src/pricing.ts (the honest place) or removes the cap.
-        if (config.execution?.caps?.maxUsd !== undefined) {
+        if (config.execution?.caps?.maxUsd !== undefined || config.execution?.caps?.maxTotalUsd !== undefined) {
             const capModelId = (config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
             if (!MODEL_RATES[capModelId]) {
-                return fail("HUMANISH_CUA_LAB_UNPRICED_CAP", `execution.caps.maxUsd is set but src/pricing.ts has no rate for model "${config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL}"; add a rate or remove the cap — an unenforceable cap is refused rather than run uncapped.`, descriptor.id);
+                return fail("HUMANISH_CUA_LAB_UNPRICED_CAP", `execution.caps declares a spend cap (maxUsd/maxTotalUsd) but src/pricing.ts has no rate for model "${config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL}"; add a rate or remove the cap — an unenforceable cap is refused rather than run uncapped.`, descriptor.id);
             }
         }
+        // Adopter-hosted comms catch (#380): fail closed BEFORE any sandbox is created — a comms lab
+        // whose catch is unreachable collects nothing while every lane still spends. The probe asserts
+        // OUR service marker in /health, so an adopter's proxy answering 200 for everything cannot
+        // pass for a catch.
+        if (externalCommsConfig && !(await externalCatchHealthy(externalCommsConfig))) {
+            return fail("HUMANISH_CUA_LAB_COMMS_CATCH_UNREACHABLE", "comms.email.external.catchBaseUrl is not reachable as a humanish comms catch (GET /health must return the humanish-comms-catch service marker). Start it with `humanish comms catch` on that host, or drop comms.email to run without the inbox funnel.", descriptor.id);
+        }
     }
     const runId = options.runId ?? makeCuaRunId();
     const runPaths = await prepareRunArtifactPaths(cwd, runId);
     const artifactRoot = runPaths.absoluteRunRoot;
     const physicalArtifactRoot = runPaths.physicalRunRoot;
     const createdAt = new Date().toISOString();
-    const timeoutMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const timeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config);
     const requestTimeoutMs = readPositiveInt(env.HUMANISH_E2B_REQUEST_TIMEOUT_MS, 60_000);
     const redactScreenshots = config.policies?.redactScreenshots === true;
     await prepareContainedOutputDirectory(runPaths, "screenshots");
@@ -2169,6 +2268,14 @@ export async function runCuaActorLab(options) {
         redactScreenshots,
         scrubKnownValues,
         runSession,
+        // The study-level ledger exists once per RUN, shared by every lane (#299). Dry runs never
+        // spend, so they carry none.
+        ...(dryRun || config.execution?.caps?.maxTotalUsd === undefined
+            ? {}
+            : { runBudget: makeCuaRunBudget(config.execution.caps.maxTotalUsd) }),
+        ...(externalCommsConfig === undefined || externalCommsEmail === undefined
+            ? {}
+            : { externalComms: { email: externalCommsEmail, inboxUrl: externalInboxUrl(externalCommsConfig) } }),
         now: hooks.now ?? Date.now,
         hooks: liveHooks
     };
@@ -2245,6 +2352,47 @@ export async function runCuaActorLab(options) {
             failFastReason = ran.failFastReason;
         }
     }
+    const externalCommsWarnings = [];
+    // Adopter-hosted drain (#380): once per RUN, after every lane finished — the catch is one
+    // shared external endpoint, not a per-sandbox file. Same routing and digest-only artifact as
+    // the in-sandbox drain; the artifact is registered on every lane that declared a recipient
+    // address, since the thread carries each inbox's mail. A drain failure never fails the run.
+    if (!dryRun && externalCommsConfig && externalCommsEmail && outcomes !== undefined) {
+        try {
+            const commsChannel = new FakeInbox();
+            const commsInboxes = [];
+            for (const recipient of externalCommsEmail.recipients ?? []) {
+                if (recipient.address !== undefined) {
+                    commsInboxes.push(await commsChannel.provisionAddress(recipient.lane, recipient.address));
+                }
+            }
+            const authToken = externalCommsConfig.authTokenEnv === undefined ? undefined : env[externalCommsConfig.authTokenEnv];
+            const collected = await collectExternalCommsThread({
+                external: { ...externalCommsConfig, ...(authToken === undefined ? {} : { authToken }) },
+                channel: commsChannel,
+                inboxes: commsInboxes
+            });
+            if (collected.artifact) {
+                const commsPath = "comms/thread.json";
+                await writeContainedOutputFile(runPaths, commsPath, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
+                for (const [index, outcome] of outcomes.entries()) {
+                    const laneId = laneSpecs[index]?.laneId;
+                    if (laneId !== undefined && outcome.commsArtifactPath === undefined && laneHasInboxRecipient(externalCommsEmail, laneId)) {
+                        outcome.commsArtifactPath = commsPath;
+                    }
+                }
+            }
+            else if (collected.captured > 0) {
+                externalCommsWarnings.push(`Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`);
+            }
+            else {
+                externalCommsWarnings.push(`Comms catch captured ZERO email sends — your app never delivered mail through the catch at ${externalCommsConfig.catchBaseUrl}. Verify the app's email-API base URL points at it and that the flow reached an email step.`);
+            }
+        }
+        catch (error) {
+            externalCommsWarnings.push(`Comms evidence collection failed against the adopter-hosted catch (run continues): ${redactText(scrubKnownValues(toErrorMessage(error)))}`);
+        }
+    }
     // Per-lane subject projections (invariant 5).
     const laneSubjects = laneSpecs.map((_spec, index) => {
         const outcome = outcomes?.[index];
@@ -2268,14 +2416,14 @@ export async function runCuaActorLab(options) {
     // lane's projection already carries the identical archiveSha256/commit/dirty: the
     // `first.source !== "clone"` branch below returns it directly, with no unanimity math needed
     // (there is nothing that could diverge).
-    const aggregateWarnings = [];
+    const aggregateWarnings = [...externalCommsWarnings];
     // execution.caps.maxUsd is a PER-LANE cap: it is enforced INSIDE each lane's loop independently,
     // so an N-lane fan-out can spend up to N × maxUsd before any lane aborts, while the run cost
-    // summary reports the (larger) aggregate. Warn at run level so the operator sees the true ceiling.
-    // A shared, run-level budget is future work — there is no cross-lane counter today.
+    // summary reports the (larger) aggregate. Warn at run level so the operator sees the true
+    // ceiling — unless the study declared the shared budget (#299), which caps the run as a whole.
     const perLaneCapUsd = config.execution?.caps?.maxUsd;
-    if (perLaneCapUsd !== undefined && laneCount > 1) {
-        aggregateWarnings.push(`execution.caps.maxUsd ($${perLaneCapUsd}) is a PER-LANE cap; ${laneCount} lanes may spend up to ${laneCount} × $${perLaneCapUsd} (~$${round6(perLaneCapUsd * laneCount)} total) before any lane aborts. A shared run-level budget is future work.`);
+    if (perLaneCapUsd !== undefined && laneCount > 1 && config.execution?.caps?.maxTotalUsd === undefined) {
+        aggregateWarnings.push(`execution.caps.maxUsd ($${perLaneCapUsd}) is a PER-LANE cap; ${laneCount} lanes may spend up to ${laneCount} × $${perLaneCapUsd} (~$${round6(perLaneCapUsd * laneCount)} total) before any lane aborts. Set execution.caps.maxTotalUsd for a shared study budget.`);
     }
     const aggregateSubject = (() => {
         const first = laneSubjects[0];
@@ -3006,6 +3154,80 @@ export function buildCuaCostSummary(args) {
 function desktopSpanToMinutes(desktopDurationMs) {
     return desktopDurationMs === undefined ? undefined : desktopDurationMs / 60_000;
 }
+/**
+ * Feedback candidates derived from what LIVE participants actually reported (#392).
+ *
+ * A live run's feedback draft used to fall through to a dry-run template, because no browser route
+ * ever built a candidate. The candidate worth filing is the one the study produced: a participant
+ * who reported friction on the way (the most valuable thing a run captures), or one who stopped
+ * trying. A clean pass files nothing here — feedback exists to carry findings, and a run without
+ * any falls back to an honest live summary in the draft layer instead of a template.
+ *
+ * Everything quoted is already scrub+redacted — `session.reason` passes through redactNarration in
+ * the loop before it ever lands on a trace — and passes redactText again here as defense-in-depth.
+ */
+export function participantFeedbackCandidates(args) {
+    const candidates = [];
+    for (const lane of args.lanes) {
+        const session = lane.session;
+        if (session === undefined)
+            continue;
+        const friction = resolveSelfReportedBlocker(session);
+        const abandoned = session.status === "abandoned";
+        if (friction === undefined && !abandoned)
+            continue;
+        const summary = friction !== undefined
+            ? `Participant ${lane.personaId} (${lane.laneId}) reported friction on the way through the study goal`
+            : `Participant ${lane.personaId} (${lane.laneId}) stopped before completing the study goal`;
+        const lastScreenshot = lane.screenshots[lane.screenshots.length - 1];
+        candidates.push({
+            schema: "humanish.feedback-candidate.v1",
+            id: `participant-report-${lane.laneId}`,
+            run_id: args.runId,
+            stream_id: lane.streamId,
+            adapter_id: args.adapterId,
+            scenario_id: args.scenarioId,
+            persona_id: lane.personaId,
+            actor: "computer-use",
+            substrate: args.substrate,
+            // The participant is reporting on the PRODUCT: friction and abandonment are target-app
+            // findings by the three-roles rule. A harness failure never reaches this builder — it is
+            // not a participant report.
+            failure_owner: "target-app",
+            summary,
+            expected: args.goal,
+            actual: redactText(friction ?? session.reason),
+            evidence: [
+                ...(lane.traceArtifactPath === undefined ? [] : [{
+                        path: lane.traceArtifactPath,
+                        kind: "trace",
+                        note: "Full actor trace: turns, actions, and the participant's own report."
+                    }]),
+                ...(lastScreenshot === undefined ? [] : [{
+                        path: lastScreenshot,
+                        kind: "screenshot",
+                        note: "Final screenshot at the moment the session ended."
+                    }]),
+                ...(lane.commsArtifactPath === undefined ? [] : [{
+                        path: lane.commsArtifactPath,
+                        kind: "log",
+                        note: "Digest-only comms thread captured in-sandbox."
+                    }])
+            ],
+            redaction: {
+                status: "passed",
+                notes: "Quoted participant text passed the loop's known-value scrub and pattern redaction before persisting, and redactText again here."
+            },
+            idempotency_key: `humanish:${args.runId}:${lane.laneId}:participant-report`,
+            proposed_next_state: "study-quality-review",
+            acceptance_proof: [
+                `pnpm humanish -- verify --run ${args.runId} --json`,
+                `pnpm humanish -- watch --run ${args.runId} --no-open`
+            ]
+        });
+    }
+    return candidates;
+}
 export function buildCuaBundle(args) {
     const publicAppUrl = publicSafeAppUrlLabel(args.appUrl);
     // Run-level cost ESTIMATE (advisory; omitted when nothing was priced and no sandbox ran).
@@ -3212,6 +3434,11 @@ export function buildCuaBundle(args) {
             streamId: "stream-001"
         });
     }
+    // A funnel with a denominator of one is still the funnel — and its absence stays honest: no
+    // declared protocol (or a dry run) means no `tasks` field, never an empty one.
+    const singleStudyTasks = args.inProgress !== true && args.session?.trace.taskFunnel !== undefined
+        ? aggregateTaskFunnels([args.session.trace.taskFunnel])
+        : undefined;
     const review = {
         schema: REVIEW_SCHEMA,
         verdict: args.inProgress === true
@@ -3221,6 +3448,12 @@ export function buildCuaBundle(args) {
                 : args.sessionError
                     ? "fail"
                     : "contract_proof_only",
+        // One lane is still a study with a denominator of one, and saying so keeps a single-lane
+        // result from being read as though it generalized.
+        ...(args.session && args.inProgress !== true
+            ? { participants: tallyParticipantOutcomes([args.session.status]) }
+            : {}),
+        ...(singleStudyTasks === undefined ? {} : { tasks: singleStudyTasks }),
         summary: reason,
         gaps: args.session || args.sessionError
             ? []
@@ -3246,7 +3479,7 @@ export function buildCuaBundle(args) {
         scenario: {
             id: `cua-${args.labId}`,
             title: args.labTitle ?? `Computer-use lab: ${args.labId}`,
-            goal: args.mission,
+            goal: redactText(args.mission),
             source: `lab:${args.labId}`,
             sourceDigest: args.persona.promptDigest
         },
@@ -3278,7 +3511,26 @@ export function buildCuaBundle(args) {
             events: "events.ndjson"
         },
         review,
-        feedbackCandidates: [],
+        // What the participant reported, when it reported anything (#392). Dry-run and in-progress
+        // bundles carry none — there is no participant yet to quote.
+        feedbackCandidates: args.dryRun || args.inProgress === true
+            ? []
+            : participantFeedbackCandidates({
+                runId: args.runId,
+                scenarioId: `cua-${args.labId}`,
+                adapterId: args.labId,
+                goal: redactText(args.mission),
+                substrate: args.desktopRoute === false ? "local-filesystem" : "e2b-desktop",
+                lanes: [{
+                        laneId: args.laneId ?? "lane-01",
+                        streamId: "stream-001",
+                        personaId: args.persona.id,
+                        ...(args.session === undefined ? {} : { session: args.session }),
+                        ...(args.traceArtifactPath === undefined ? {} : { traceArtifactPath: args.traceArtifactPath }),
+                        screenshots: args.screenshots,
+                        ...(args.commsArtifactPath === undefined ? {} : { commsArtifactPath: args.commsArtifactPath })
+                    }]
+            }),
         // Custom desktop image provenance (omitted on the stock-template default → byte-stable).
         ...(args.desktopTemplate === undefined ? {} : { desktopTemplate: args.desktopTemplate }),
         ...(args.desktopBrowser === undefined ? {} : { desktopBrowser: args.desktopBrowser }),
@@ -3614,14 +3866,31 @@ export function buildCuaFanoutBundle(args) {
         && outcome.sessionError === undefined
         && !outcome.noEngagement
         && !outcome.selfReportedBlocker).length;
+    // What happened to the PARTICIPANTS, with the denominator attached. The verdict above has to
+    // collapse the run to one word; this does not (docs/principles/three-roles.md).
+    const terminalOutcomes = (outcomes ?? []).filter((outcome) => outcome?.session?.status !== undefined);
+    const participants = terminalOutcomes.length > 0
+        ? tallyParticipantOutcomes(terminalOutcomes.map((outcome) => outcome.session.status), 
+        // A participant who reached the goal AND told you the road there was broken is the most
+        // useful result a study produces; reporting only the outcome would bury it.
+        terminalOutcomes.map((outcome) => outcome.selfReportedBlocker === true))
+        : undefined;
+    // The study funnel: per-task completion rates across every session that measured one. This is
+    // "where did people get stuck" as data, next to WHO got stuck (participants) above.
+    const participantFunnels = (outcomes ?? [])
+        .map((outcome) => outcome?.session?.trace.taskFunnel)
+        .filter((funnel) => funnel !== undefined);
+    const studyTasks = args.inProgress === true ? undefined : aggregateTaskFunnels(participantFunnels);
     const review = {
         schema: REVIEW_SCHEMA,
         verdict,
+        ...(participants === undefined ? {} : { participants }),
+        ...(studyTasks === undefined ? {} : { tasks: studyTasks }),
         summary: args.inProgress === true
             ? `Live computer-use fan-out is running (${specs.length} per-lane worlds); terminal lane evidence has not been written yet.`
             : args.dryRun
                 ? `${args.rerun ? `Rerun contract from ${args.rerun.sourceRunId}: ` : ""}Dry-run fan-out contract: ${specs.length} per-lane-world lanes composed for ${args.descriptor.id} against ${args.appUrl}; no desktops launched, $0 spend.`
-                : `${args.rerun ? `Rerun from ${args.rerun.sourceRunId}: ` : ""}Computer-use fan-out (${specs.length} per-lane worlds): ${passedLanes}/${specs.length} lane(s) reached a terminal, engaged verdict.`,
+                : `${args.rerun ? `Rerun from ${args.rerun.sourceRunId}: ` : ""}Computer-use fan-out (${specs.length} per-lane worlds): ${passedLanes}/${specs.length} lane(s) reached a terminal, engaged verdict${participants ? ` — ${formatParticipantOutcomes(participants)}` : ""}${studyTasks ? `; tasks: ${formatStudyTaskFunnel(studyTasks)}` : ""}.`,
         gaps: args.inProgress === true
             ? ["Live fan-out session is still running."]
             : args.dryRun
@@ -3682,7 +3951,15 @@ export function buildCuaFanoutBundle(args) {
         scenario: {
             id: `cua-${config.id}`,
             title: config.title ?? `Computer-use fan-out: ${config.id}`,
-            goal: specs[0].instructions,
+            // Redacted at WRITE time, like every other raw-text surface in the bundle. Lane records are
+            // digest-only by design, but scenario.goal keeps one lane's composed instructions verbatim —
+            // and an adopter whose authored lane text must name a runtime world URL (an inbox on a route
+            // where the harness does not inject one) put an *.e2b.app address in it. That landed raw here
+            // and in observer-data.json, the sensitive-text scanner matched it, and verify failed a bundle
+            // this writer produced. The only adopter-side workaround was scanner evasion (#412).
+            //
+            // The instructions the model actually receives are untouched; only the persisted copy changes.
+            goal: redactText(specs[0].instructions),
             source: `lab:${config.id}`,
             sourceDigest: specs[0].persona.promptDigest
         },
@@ -3713,7 +3990,29 @@ export function buildCuaFanoutBundle(args) {
             events: "events.ndjson"
         },
         review,
-        feedbackCandidates: [],
+        // What the participants reported, when any reported anything (#392). Dry-run and in-progress
+        // bundles carry none — there is no participant yet to quote.
+        feedbackCandidates: args.dryRun || args.inProgress === true
+            ? []
+            : participantFeedbackCandidates({
+                runId: args.runId,
+                scenarioId: `cua-${config.id}`,
+                adapterId: config.id,
+                goal: redactText(specs[0].instructions),
+                substrate: "e2b-desktop",
+                lanes: specs.map((spec, index) => {
+                    const outcome = outcomes?.[index];
+                    return {
+                        laneId: spec.laneId,
+                        streamId: spec.streamId,
+                        personaId: spec.persona.id,
+                        ...(outcome?.session === undefined ? {} : { session: outcome.session }),
+                        ...(outcome?.session === undefined ? {} : { traceArtifactPath: spec.traceArtifactPath }),
+                        screenshots: outcome?.screenshots ?? [],
+                        ...(outcome?.commsArtifactPath === undefined ? {} : { commsArtifactPath: outcome.commsArtifactPath })
+                    };
+                })
+            }),
         // Custom desktop image provenance (every lane launched on it); omitted on the stock default.
         ...(config.execution?.desktop?.template === undefined ? {} : { desktopTemplate: config.execution.desktop.template }),
         ...(configuredBrowser === undefined