humanish 0.111.2 → 0.111.4

package/dist/routes/computer-use/bundle-parts.js

@@ -1,13 +1,12 @@
 // The parts both computer-use bundle shapes share: the subject-state story and provenance line,
-// feedback candidates from what live participants reported, provider-resource records, and the
-// public-safe app URL label, the URL digest and the subject-phase event id suffix. The builders are bundle.ts (the dispatcher and the judge),
-// single-bundle.ts and fanout-bundle.ts.
-import { feedbackProofCommands } from "../../feedback/proof.js";
+// provider-resource records, and the public-safe app URL label, the URL digest and the
+// subject-phase event id suffix. The builders are bundle.ts (the dispatcher and the judge),
+// single-bundle.ts and fanout-bundle.ts. Feedback candidates from participant reports are in
+// participant-feedback.ts, which the shared-world bundle reads too.
 import { scanEncodedText } from "../../evidence/encoded-text.js";
-import { digestText, redactText } from "../../evidence/redaction.js";
+import { digestText } from "../../evidence/redaction.js";
 import {} from "../../run/bundle.js";
 import { participantResourceIds } from "../../run/participant-records.js";
-import { resolveSelfReportedFriction } from "./self-report.js";
 import {} from "./types.js";
 import { plural } from "../../run/text.js";
 /** The human-readable state story appended to the provenance event (and review.md via it). */
@@ -25,92 +24,6 @@ export function describeSubjectState(state, dryRun) {
             return "external-public (operator-declared, operator-owned public deployment; neither provisioned nor seeded)";
     }
 }
-/**
- * Feedback candidates derived from what live participants actually reported.
- *
- * A live run's feedback draft comes from these candidates, never from a dry-run template. 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 a live summary in the draft layer instead of a template.
- *
- * Everything quoted is already scrub+redacted (participant messages and `session.reason` pass
- * through redactNarration in the loop) and passes redactText again here as defense-in-depth.
- */
-export function participantFeedbackCandidates(args) {
-    const candidates = [];
-    for (const participant of args.participants) {
-        const session = participant.session;
-        if (session === undefined)
-            continue;
-        const friction = resolveSelfReportedFriction(session);
-        const abandoned = session.status === "abandoned";
-        if (friction === undefined && !abandoned)
-            continue;
-        const summary = friction !== undefined
-            ? `Participant ${participant.personaId} (${participant.participantId}) reported friction on the way through the study goal`
-            : `Participant ${participant.personaId} (${participant.participantId}) stopped before completing the study goal`;
-        const lastScreenshot = participant.screenshots[participant.screenshots.length - 1];
-        candidates.push({
-            schema: "humanish.feedback-candidate.v1",
-            id: `participant-report-${participant.participantId}`,
-            run_id: args.runId,
-            stream_id: participant.streamId,
-            adapter_id: args.adapterId,
-            scenario_id: args.scenarioId,
-            persona_id: participant.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: [
-                ...(participant.traceArtifactPath === undefined
-                    ? []
-                    : [
-                        {
-                            path: participant.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.",
-                        },
-                    ]),
-                ...(participant.commsArtifactPath === undefined
-                    ? []
-                    : [
-                        {
-                            path: participant.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}:${participant.participantId}:participant-report`,
-            proposed_next_state: "study-quality-review",
-            acceptance_proof: [
-                feedbackProofCommands(args.runId).verify,
-                feedbackProofCommands(args.runId).observe,
-            ],
-        });
-    }
-    return candidates;
-}
 /** Human-readable provenance line for the single-participant subject.provenance event:
  *  claims "cloned/packed and served" only when it actually happened. */
 export function subjectProvenanceMessage(provenance, publicAppUrl, dryRun, hasSession) {

package/dist/routes/computer-use/e2b-desktop/prepare.js

@@ -1,6 +1,7 @@
 // The first half of an E2B desktop participant's preparation: acquire the sandbox, verify its screen, and
 // provision the subject. Each step fills the participant's state; a step that cannot proceed throws.
 import { redactText } from "../../../evidence/redaction.js";
+import { validatePreparedRunArtifactPaths } from "../../../run/paths.js";
 import { provisionCloneSubject } from "../../../subject/clone.js";
 import { provisionDesktopCli } from "../../../subject/desktop-cli.js";
 import { provisionLocalTreeSubject } from "../../../subject/local-tree.js";
@@ -94,10 +95,16 @@ export async function acquireParticipantDesktop(ctx, state) {
     if ("reason" in desktopResources) {
         warnings.push(`Desktop resource size unavailable (${desktopResources.reason}); compute cost remains unpriced.`);
     }
-    await deps.prepareDesktop?.(desktop, {
-        kind: "participant",
-        participant: { id: spec.planned.id, index: spec.planned.index, count: deps.participantCount },
-    });
+    if (deps.prepareDesktop) {
+        await deps.prepareDesktop(desktop, {
+            kind: "participant",
+            participant: { id: spec.planned.id, index: spec.planned.index, count: deps.participantCount },
+        });
+        // The caller's hook runs with this process's file access, so the run directory is checked
+        // again before more evidence goes into it.
+        if ("physicalRunRoot" in deps.artifactRoot)
+            await validatePreparedRunArtifactPaths(deps.artifactRoot);
+    }
     if (deps.receiving) {
         state.receivingInboxUrl = await attachReceivingInbox(shell, spec, { ...deps, receiving: deps.receiving }, ctx.targetUrl);
         state.commsArtifactPath = "comms/receiving.json";

package/dist/routes/computer-use/fanout-bundle.js

@@ -4,7 +4,8 @@ import { actorEnding } from "../../actors/stop-cause.js";
 import { redactText } from "../../evidence/redaction.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, tallyParticipantOutcomes, withCuaReviewProvenance, } from "../../run/outcomes.js";
-import { participantFeedbackCandidates, providerResourcesForOutcome, publicSafeAppUrlLabel, } from "./bundle-parts.js";
+import { providerResourcesForOutcome, publicSafeAppUrlLabel } from "./bundle-parts.js";
+import { participantFeedbackCandidates } from "./participant-feedback.js";
 import { participantFactsOf } from "./participant-facts.js";
 import { participantPassed, participantStatus } from "../../run/judge.js";
 import { buildRunCostSummary, desktopSpanToMinutes } from "../../run/cost-summary.js";
@@ -141,7 +142,6 @@ function fanoutFeedbackCandidates(args) {
             runId: args.run.runId,
             scenarioId: `cua-${plan.studyId}`,
             adapterId: plan.studyId,
-            goal: redactText(specs[0].evidenceInstructions ?? specs[0].instructions),
             substrate: plan.residual.execution?.target === "local" ? "local-desktop" : "e2b-desktop",
             participants: specs.map((spec, index) => {
                 const outcome = outcomes?.[index];
@@ -149,6 +149,7 @@ function fanoutFeedbackCandidates(args) {
                     participantId: spec.planned.id,
                     streamId: spec.streamId,
                     personaId: spec.persona.id,
+                    goal: redactText(spec.evidenceInstructions ?? spec.instructions),
                     ...(outcome?.session === undefined ? {} : { session: outcome.session }),
                     ...(outcome?.session === undefined
                         ? {}

package/dist/routes/computer-use/live-phase.js

@@ -15,7 +15,7 @@ import { participantSubjectEnv } from "./types.js";
 export async function runStudyParticipants(setup, participants) {
     const { plan, input, cwd, streams, descriptor, run } = setup;
     const { participantRuns, participantPlan, bundleBase } = setup;
-    const { env, knownSecretValues, deps, liveTrace, externalComms, inProgress, fail } = participants;
+    const { env, deps, liveTrace, externalComms, inProgress, fail } = participants;
     const { dryRun } = plan;
     const inProcess = plan.runner.desktop === "in-process";
     const subjectEnvNames = [...participantSubjectEnv(plan.runner.subject)];
@@ -76,11 +76,7 @@ export async function runStudyParticipants(setup, participants) {
                 env,
                 participants: participantRuns.map((spec) => spec.planned.id),
                 runPaths,
-                registerSecrets: (values) => {
-                    for (const value of values)
-                        if (value.length >= 4 && !knownSecretValues.includes(value))
-                            knownSecretValues.push(value);
-                },
+                registerSecrets: (values) => run.secrets.add(values),
             });
             if (receiving)
                 deps.receiving = receiving;
@@ -129,7 +125,7 @@ export async function runStudyParticipants(setup, participants) {
             runPaths,
             participantRuns: participantRuns,
             outcomes,
-            knownSecretValues,
+            knownSecretValues: run.secrets.values(),
         })
         : [];
     return {

package/dist/routes/computer-use/participant-deps.d.ts

@@ -0,0 +1,46 @@
+import type { ComputerUsePlan, SharedWorldPlan } from "../../study/plan-types.js";
+import type { StudyDeps } from "../../study/study-deps.js";
+import type { LiveTraceFlush } from "./live-flush.js";
+import type { CuaParticipantDeps } from "./types.js";
+/** The deps a desktop route builds once per run. Each participant adds the app URL it opens. */
+export type DesktopParticipantDeps = Omit<CuaParticipantDeps, "signalProvisioned" | "appUrl" | "onObservedUrl">;
+/** What every participant of a desktop run reads. Each route supplies all of it. */
+interface DesktopRunFacts {
+    plan: Pick<ComputerUsePlan | SharedWorldPlan, "studyId" | "residual" | "caps" | "dryRun">;
+    /** The plan's brain. A local agent runs each participant on the operator's signed-in CLI. */
+    brain: CuaParticipantDeps["brain"];
+    /** What the participant's desktop does with the subject. */
+    subject: CuaParticipantDeps["subject"];
+    /** The run's env. The E2B request timeout is read from it. */
+    env: CuaParticipantDeps["env"];
+    openaiApiKey: string;
+    e2bApiKey: string;
+    /** Each participant's session budget. */
+    timeoutMs: number;
+    /** Each participant's sandbox lifetime. */
+    sandboxMs: number;
+    participantCount: number;
+    artifactRoot: CuaParticipantDeps["artifactRoot"];
+    studyCwd: string;
+    redactScreenshots: boolean;
+    scrubKnownValues: (text: string) => string;
+    runSession: CuaParticipantDeps["runSession"];
+    /** The run's live-trace flush, once a live run has started it. */
+    liveFlush: () => LiveTraceFlush["flush"] | undefined;
+    onStream: CuaParticipantDeps["onStream"];
+    reportSubjectPhase: CuaParticipantDeps["reportSubjectPhase"];
+    /** The run's test seams: the clock, the E2B SDK loader and the detached timers. */
+    seams: StudyDeps;
+    /** The caller's prepareDesktop, which each participant's desktop runs. */
+    prepareDesktop: CuaParticipantDeps["prepareDesktop"];
+}
+/** The fields one desktop route sets and the other does not. Undefined leaves a field out. */
+type DesktopRouteOverrides = {
+    [K in "createDesktop" | "createProvider" | "inProcessExecutor" | "localTreeArchiveBuffer" | "externalComms" | "receiving" | "screenMismatchPolicy"]?: CuaParticipantDeps[K] | undefined;
+};
+/**
+ * One run's participant deps. Call it once per run: the run budget it creates is the one ledger
+ * every participant notes its spend on, and a dry run, which never spends, gets none.
+ */
+export declare function desktopParticipantDeps(run: DesktopRunFacts, overrides: DesktopRouteOverrides): DesktopParticipantDeps;
+export {};

package/dist/routes/computer-use/participant-deps.js

@@ -0,0 +1,48 @@
+// The deps every desktop participant reads, built here for computer use and shared world. A field
+// both routes hand their participants is added once, in desktopParticipantDeps; each route passes
+// what only it knows as overrides.
+import { e2bRequestTimeoutMs } from "../../substrates/e2b/lifetime.js";
+import { makeCuaRunBudget } from "./participant-model.js";
+/**
+ * One run's participant deps. Call it once per run: the run budget it creates is the one ledger
+ * every participant notes its spend on, and a dry run, which never spends, gets none.
+ */
+export function desktopParticipantDeps(run, overrides) {
+    const { plan, seams } = run;
+    const { maxTotalUsd } = plan.caps;
+    const optional = {
+        ...overrides,
+        prepareDesktop: run.prepareDesktop,
+        desktopModule: seams.desktopModule,
+        detachedTimers: seams.detachedTimers,
+        runBudget: plan.dryRun || maxTotalUsd === undefined ? undefined : makeCuaRunBudget(maxTotalUsd),
+    };
+    return {
+        ...definedFields(optional),
+        onTrace: (participantId, items, usage, metadata) => run.liveFlush()?.(participantId, items, usage, metadata),
+        residual: plan.residual,
+        studyId: plan.studyId,
+        caps: plan.caps,
+        brain: run.brain,
+        subject: run.subject,
+        env: run.env,
+        openaiApiKey: run.openaiApiKey,
+        e2bApiKey: run.e2bApiKey,
+        requestTimeoutMs: e2bRequestTimeoutMs(run.env),
+        sandboxMs: run.sandboxMs,
+        timeoutMs: run.timeoutMs,
+        participantCount: run.participantCount,
+        artifactRoot: run.artifactRoot,
+        studyCwd: run.studyCwd,
+        redactScreenshots: run.redactScreenshots,
+        scrubKnownValues: run.scrubKnownValues,
+        runSession: run.runSession,
+        now: seams.now ?? Date.now,
+        onStream: run.onStream,
+        reportSubjectPhase: run.reportSubjectPhase,
+    };
+}
+/** The fields of `fields` that are set. The deps never carry a key whose value is undefined. */
+function definedFields(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}

package/dist/routes/computer-use/participant-facts.d.ts

@@ -5,8 +5,9 @@ export declare function participantFactsOf(outcome: ParticipantRunOutcome): Part
 /** Whether a participant passed. A dry-run participant passes as a contract. */
 export declare function participantOutcomeOk(outcome: ParticipantRunOutcome | undefined, dryRun: boolean): boolean;
 /**
- * One sandbox-cleanup failure per participant desktop not confirmed released: an E2B sandbox that
- * was not killed, or a desktop whose release says why (a local VM names its container). A
- * participant that never acquired a desktop (skipped, in-process) adds none.
+ * The execution failures a run's participants caused, by kind: each session that failed in the
+ * harness, each provider whose cleanup is unconfirmed, each provider that reported a disallowed
+ * item after its last request, then each desktop not confirmed released. Participants keep their
+ * order within each kind.
  */
-export declare function unreleasedSandboxFailures(outcomes: readonly ParticipantRunOutcome[] | undefined, runId: string): ExecutionFailure[];
+export declare function participantExecutionFailures(outcomes: readonly ParticipantRunOutcome[] | undefined, runId: string): ExecutionFailure[];

package/dist/routes/computer-use/participant-facts.js

@@ -1,7 +1,7 @@
 // A participant run outcome's facts for the judge (src/run/judge.ts), and the pass check built on
 // them. The bundle builders, the result, the participant runner and shared-world all read these,
 // so they sit in a file that imports only the judge and the types.
-import { participantPassed, sandboxCleanupFailure, } from "../../run/judge.js";
+import { participantHarnessFailed, participantPassed, sandboxCleanupFailure, } from "../../run/judge.js";
 /** A participant outcome's facts for the judge. */
 export function participantFactsOf(outcome) {
     return {
@@ -20,12 +20,47 @@ export function participantOutcomeOk(outcome, dryRun) {
         return true;
     return outcome !== undefined && participantPassed(participantFactsOf(outcome));
 }
+/**
+ * The execution failures a run's participants caused, by kind: each session that failed in the
+ * harness, each provider whose cleanup is unconfirmed, each provider that reported a disallowed
+ * item after its last request, then each desktop not confirmed released. Participants keep their
+ * order within each kind.
+ */
+export function participantExecutionFailures(outcomes, runId) {
+    const all = outcomes ?? [];
+    const named = (outcome, text) => `${outcome.spec.planned.id}: ${text}`;
+    return [
+        ...all
+            .filter((outcome) => participantHarnessFailed(participantFactsOf(outcome)))
+            .map((outcome) => ({
+            kind: "harness",
+            message: named(outcome, outcome.sessionError ?? outcome.session?.reason ?? "harness error"),
+        })),
+        ...all.flatMap((outcome) => outcome.providerCleanupError === undefined
+            ? []
+            : [
+                {
+                    kind: "provider-cleanup",
+                    message: named(outcome, outcome.providerCleanupError),
+                },
+            ]),
+        ...all.flatMap((outcome) => outcome.providerPolicyError === undefined
+            ? []
+            : [
+                {
+                    kind: "provider-policy",
+                    message: named(outcome, outcome.providerPolicyError),
+                },
+            ]),
+        ...unreleasedSandboxFailures(all, runId),
+    ];
+}
 /**
  * One sandbox-cleanup failure per participant desktop not confirmed released: an E2B sandbox that
  * was not killed, or a desktop whose release says why (a local VM names its container). A
  * participant that never acquired a desktop (skipped, in-process) adds none.
  */
-export function unreleasedSandboxFailures(outcomes, runId) {
+function unreleasedSandboxFailures(outcomes, runId) {
     return (outcomes ?? [])
         .filter((outcome) => outcome.sandboxRelease !== undefined ||
         (outcome.sandboxId !== undefined && !outcome.killed))

package/dist/routes/computer-use/participant-feedback.d.ts

@@ -0,0 +1,33 @@
+import type { CuaLoopResult } from "../../actors/computer-use/loop.js";
+import type { RunFeedbackCandidate } from "../../run/bundle.js";
+/**
+ * Feedback candidates derived from what live participants actually reported.
+ *
+ * A live run's feedback draft comes from these candidates, never from a dry-run template. 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 a live summary in the draft layer instead of a template.
+ *
+ * Everything quoted is already scrub+redacted (participant messages and `session.reason` pass
+ * through redactNarration in the loop) and passes redactText again here as defense-in-depth.
+ */
+export declare function participantFeedbackCandidates(args: {
+    runId: string;
+    scenarioId: string;
+    adapterId: string;
+    substrate: RunFeedbackCandidate["substrate"];
+    participants: Array<{
+        /** The participant's plan id; it names the candidate and its idempotency key. */
+        participantId: string;
+        streamId: string;
+        personaId: string;
+        /** The participant's own already-redacted instructions, which the candidate's `expected`
+         *  quotes. Participants of one study get different instructions, each naming its persona. */
+        goal: string;
+        session?: CuaLoopResult;
+        traceArtifactPath?: string;
+        screenshots: string[];
+        commsArtifactPath?: string;
+    }>;
+}): RunFeedbackCandidate[];

package/dist/routes/computer-use/participant-feedback.js

@@ -0,0 +1,92 @@
+// Feedback candidates from what live participants reported. The computer-use bundles (single and
+// fan-out) and the shared-world bundle all build them here, so a participant's report becomes the
+// same candidate whichever route ran it.
+import { redactText } from "../../evidence/redaction.js";
+import { feedbackProofCommands } from "../../feedback/proof.js";
+import { resolveSelfReportedFriction } from "./self-report.js";
+/**
+ * Feedback candidates derived from what live participants actually reported.
+ *
+ * A live run's feedback draft comes from these candidates, never from a dry-run template. 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 a live summary in the draft layer instead of a template.
+ *
+ * Everything quoted is already scrub+redacted (participant messages and `session.reason` pass
+ * through redactNarration in the loop) and passes redactText again here as defense-in-depth.
+ */
+export function participantFeedbackCandidates(args) {
+    const candidates = [];
+    for (const participant of args.participants) {
+        const session = participant.session;
+        if (session === undefined)
+            continue;
+        const friction = resolveSelfReportedFriction(session);
+        const abandoned = session.status === "abandoned";
+        if (friction === undefined && !abandoned)
+            continue;
+        const summary = friction !== undefined
+            ? `Participant ${participant.personaId} (${participant.participantId}) reported friction on the way through the study goal`
+            : `Participant ${participant.personaId} (${participant.participantId}) stopped before completing the study goal`;
+        const lastScreenshot = participant.screenshots[participant.screenshots.length - 1];
+        candidates.push({
+            schema: "humanish.feedback-candidate.v1",
+            id: `participant-report-${participant.participantId}`,
+            run_id: args.runId,
+            stream_id: participant.streamId,
+            adapter_id: args.adapterId,
+            scenario_id: args.scenarioId,
+            persona_id: participant.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: participant.goal,
+            actual: redactText(friction ?? session.reason),
+            evidence: [
+                ...(participant.traceArtifactPath === undefined
+                    ? []
+                    : [
+                        {
+                            path: participant.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.",
+                        },
+                    ]),
+                ...(participant.commsArtifactPath === undefined
+                    ? []
+                    : [
+                        {
+                            path: participant.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}:${participant.participantId}:participant-report`,
+            proposed_next_state: "study-quality-review",
+            acceptance_proof: [
+                feedbackProofCommands(args.runId).verify,
+                feedbackProofCommands(args.runId).observe,
+            ],
+        });
+    }
+    return candidates;
+}

package/dist/routes/computer-use/participant-model.d.ts

@@ -41,4 +41,15 @@ export declare function judgeParticipantSession(session: CuaLoopResult | undefin
     selfReportedBlocker: boolean;
     reportedFriction: boolean;
 };
+/**
+ * caps.maxUsd is enforced inside each participant's loop independently, so N participants can
+ * spend up to N × maxUsd before any of them stops, while the run cost summary reports the larger
+ * aggregate. The warning names that ceiling, unless the study declared a shared maxTotalUsd budget.
+ * `capped` names what the cap counts: shared world says model spend, because the external-public
+ * plane's lobby-code reads are not counted against it.
+ */
+export declare function participantCapWarning(caps: {
+    readonly maxUsd?: number;
+    readonly maxTotalUsd?: number;
+}, participantCount: number, capped?: string): string | undefined;
 export declare function makeCuaRunBudget(maxTotalUsd: number): CuaRunBudget;

package/dist/routes/computer-use/participant-model.js

@@ -257,6 +257,21 @@ export function judgeParticipantSession(session, deps, warnings) {
     }
     return { noEngagement, selfReportedBlocker, reportedFriction };
 }
+/**
+ * caps.maxUsd is enforced inside each participant's loop independently, so N participants can
+ * spend up to N × maxUsd before any of them stops, while the run cost summary reports the larger
+ * aggregate. The warning names that ceiling, unless the study declared a shared maxTotalUsd budget.
+ * `capped` names what the cap counts: shared world says model spend, because the external-public
+ * plane's lobby-code reads are not counted against it.
+ */
+export function participantCapWarning(caps, participantCount, capped = "each participant") {
+    const capUsd = caps.maxUsd;
+    if (capUsd === undefined || participantCount <= 1)
+        return undefined;
+    if (caps.maxTotalUsd !== undefined)
+        return undefined;
+    return `caps.maxUsd ($${capUsd}) caps ${capped}, so ${participantCount} participants may spend up to ${participantCount} × $${capUsd} (about $${round6(capUsd * participantCount)}) before any of them stops. Set caps.maxTotalUsd for one budget across the study.`;
+}
 export function makeCuaRunBudget(maxTotalUsd) {
     const participantEstimates = new Map();
     return {