humanish 0.112.0 → 0.113.0

package/dist/routes/computer-use/local-vm.js

@@ -3,8 +3,9 @@ import path from "node:path";
 import { inboxRecipientFor, } from "./participant-desktop.js";
 import { createLocalFirecrackerDesktop, } from "../../substrates/local/firecracker-desktop.js";
 import { localBrowserDefaults, localBrowserUnsupportedReason, } from "../../substrates/local/runtime-config.js";
-import { prepareLocalRuntime } from "../../substrates/local/runtime.js";
-import { dockerCommandLine } from "../../substrates/local/runtime-host.js";
+import { localRuntimeCapacity, prepareLocalRuntime } from "../../substrates/local/runtime.js";
+import { dockerCommandLine, usesLima } from "../../substrates/local/runtime-host.js";
+import { outOfMemoryMessage } from "../../substrates/local/capacity.js";
 import { checkRestrictedCodexAnalysisReadiness } from "../../analysis/restricted-codex.js";
 import { createRestrictedCodexParticipant } from "../../actors/codex/restricted-participant.js";
 import { withCloseReport } from "./participant-model.js";
@@ -110,6 +111,11 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
                         warnings.push("Desktop video/audio recording could not be retained. Screenshots and participant evidence remain available.");
                     }
                 }
+                // Asked before close, which removes the container; the answer comes from Docker's events.
+                if ((await session.killedForMemory?.()) === true) {
+                    evidence.failureCode = "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY";
+                    evidence.desktopFailure = outOfMemoryMessage(usesLima() ? "lima-vm" : "linux-host");
+                }
                 try {
                     evidence.released = (await session.close()).status === "released";
                 }
@@ -180,6 +186,7 @@ export function prepareLocalVmRun(options) {
         options: account ? { ...runOptions, createProvider: accountProvider(state) } : runOptions,
         localVm: {
             desktop: (run, warnings, artifactRoot) => createLocalParticipantDesktop(context, run, warnings, artifactRoot),
+            capacity: () => localRuntimeCapacity(),
             analysisRefusal: () => state.cleanupUnconfirmed ? "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED" : undefined,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         },

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

@@ -16,6 +16,12 @@ export type ParticipantDesktopEvidence = {
     /** The substrate confirmed the desktop was released (an E2B kill or a local VM shutdown). The participant
      *  outcome records it as `killed`. */
     released: boolean;
+    /**
+     * Why the desktop itself ended the session, in words a person reads, when the substrate knows:
+     * a local desktop Docker killed for memory. It replaces the session's error for a participant
+     * who did not pass.
+     */
+    desktopFailure?: string;
 } & Pick<ParticipantRunOutcome, "sandboxId" | "sandboxRelease" | "desktopDurationMs" | "desktopResources" | "streamUrlPresent" | "subjectCommit" | "desktopBrowser" | "desktopGeometry" | "stateStepRecords" | "phaseRecords" | "failureCode" | "commsArtifactPath" | "recording">;
 /**
  * The desktop one participant runs on, owned from preparation through final evidence collection.

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

@@ -107,6 +107,15 @@ export async function runCuaParticipant(spec, deps) {
             });
         }
     }
+    const { released, desktopFailure, ...desktopEvidence } = desktop.snapshot();
+    // A desktop that died under the participant explains the failure better than the transport
+    // error the session saw. A session that passed keeps its result.
+    if (desktopFailure !== undefined) {
+        if (session?.status === "passed")
+            warnings.push(desktopFailure);
+        else
+            sessionError = desktopFailure;
+    }
     if (session)
         await recordParticipantTrace(spec, deps, session, warnings);
     const { noEngagement, selfReportedBlocker, reportedFriction } = judgeParticipantSession(session, deps, warnings);
@@ -116,7 +125,6 @@ export async function runCuaParticipant(spec, deps) {
         providerCleanupError !== undefined ||
         providerPolicyError !== undefined ||
         session?.completionReason === "harness_error";
-    const { released, ...desktopEvidence } = desktop.snapshot();
     return {
         spec,
         ...(session ? { session } : {}),

package/dist/routes/computer-use/rerun-selection.js

@@ -4,42 +4,44 @@ import {} from "../../run/bundle.js";
 import { loadRunBundle } from "../../run/locate.js";
 import {} from "../../run/streams.js";
 import { plural } from "../../run/text.js";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { cli } from "../../cli/invocation.js";
 export async function resolveCuaRerunSelection(args) {
-    const source = await loadRunBundle(args.cwd, args.sourceRunId);
+    const { studyId, sourceRunId } = args;
+    // Every refusal ends with the command that runs the whole study, which is what a user who
+    // reached for a rerun too early wants.
+    const instead = `To run every participant of ${studyId} instead, leave out --rerun-failed-from: ${cli(`watch ${studyId}`)} or ${cli(`run ${studyId}`)}.`;
+    const refuse = (what) => ({ ok: false, message: `${what} ${instead}` });
+    const source = await loadRunBundle(args.cwd, sourceRunId);
     if (!source) {
-        return { ok: false, message: `source run not found or invalid: ${args.sourceRunId}` };
+        const noRuns = sourceRunId === "latest" &&
+            !(await access(path.join(args.cwd, ".humanish", "runs", "latest.json")).then(() => true, () => false));
+        return refuse(noRuns
+            ? "--rerun-failed-from latest found no run: this project has no runs yet, and a rerun repeats the failed participants of an earlier live run."
+            : `--rerun-failed-from ${sourceRunId} names no run humanish can read in this project. ${cli("runs")} lists its runs.`);
     }
     const bundle = source.bundle;
+    const run = `Run ${bundle.runId}${sourceRunId === bundle.runId ? "" : ` (the ${sourceRunId} run)`}`;
+    const notFanout = `${run} is not a live computer-use run with more than one participant, so it has no participants to rerun.`;
     if (bundle.mode !== "live") {
-        return {
-            ok: false,
-            message: `source run ${bundle.runId} is ${bundle.mode}; rerun selection only applies to live CUA fan-out evidence.`,
-        };
+        return refuse(`${run} is a dry run: no participant ran in it, so none can be rerun. A rerun repeats the failed participants of a live run with more than one participant.`);
     }
     const fanoutEvent = bundle.events.some((event) => event.type === "cua-lab.fanout.plan");
-    if (!fanoutEvent || bundle.streams.length < 2) {
-        return { ok: false, message: `source run ${bundle.runId} is not a CUA fan-out run.` };
-    }
+    if (!fanoutEvent || bundle.streams.length < 2)
+        return refuse(notFanout);
     const prior = bundle.streams
         .map(snapshotPriorParticipant)
         .filter((entry) => entry !== null);
     const priorById = new Map(prior.map((entry) => [entry.participantId, entry]));
-    if (priorById.size < 2) {
-        return {
-            ok: false,
-            message: `source run ${bundle.runId} does not expose multiple participant ids.`,
-        };
-    }
+    if (priorById.size < 2)
+        return refuse(notFanout);
     const explicitIds = uniqueIds(args.participantIds ?? []);
     const selectedIds = explicitIds.length > 0
         ? explicitIds
         : prior.filter((entry) => entry.rerunnable).map((entry) => entry.participantId);
-    if (selectedIds.length === 0) {
-        return {
-            ok: false,
-            message: `source run ${bundle.runId} has no participant to rerun: none failed, was blocked, timed out or ended without engaging.`,
-        };
-    }
+    if (selectedIds.length === 0)
+        return refuse(`${run} has no participant to rerun: none failed, was blocked, timed out or ended without engaging.`);
     const missingPrior = selectedIds.filter((id) => !priorById.has(id));
     if (missingPrior.length > 0) {
         return {

package/dist/routes/computer-use/result.js

@@ -98,8 +98,9 @@ function cuaStudyResult(args) {
             };
         }
         const failing = (outcomes ?? []).find((outcome) => !participantOk(outcome));
-        const geometryFailure = (outcomes ?? []).find((outcome) => outcome.failureCode === "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY");
-        const code = geometryFailure?.failureCode ?? "HUMANISH_COMPUTER_USE_FAILED";
+        // A participant whose desktop failed for a known cause gives the run that cause's code.
+        const codedFailure = (outcomes ?? []).find((outcome) => outcome.failureCode !== undefined);
+        const code = codedFailure?.failureCode ?? "HUMANISH_COMPUTER_USE_FAILED";
         return {
             code,
             message: observer.ok

package/dist/routes/computer-use/self-report.js

@@ -200,8 +200,14 @@ export function resolveSelfReportedFriction(session) {
     // reached the goal and described what was hard on the way has reported friction.
     if (session.trace.declaredOutcome === "blocked")
         return session.reason;
+    // Impressions are opinions about the product, not reports of what went wrong in the session.
+    const impressions = new Set(session.trace.impressions?.status === "collected"
+        ? session.trace.impressions.items.map((item) => item.messageId)
+        : []);
     const messages = session.trace.items
-        .filter((item) => item.kind === "message" && item.id !== session.trace.debrief?.messageId)
+        .filter((item) => item.kind === "message" &&
+        item.id !== session.trace.debrief?.messageId &&
+        !impressions.has(item.id))
         .map((item) => item.text?.trim() ?? "")
         .filter((text) => text.length > 0);
     // A custom session may keep its closing report only in reason even when earlier messages exist.

package/dist/routes/computer-use/setup.js

@@ -22,6 +22,7 @@ import {} from "./bundle.js";
 import { packRunLocalTree } from "./local-tree-pack.js";
 import { projectParticipantSubjects, subjectProvenanceArg } from "./subject-projection.js";
 import { participantSubjectEnv, } from "./types.js";
+import { capacityShortfall } from "../../substrates/local/capacity.js";
 import { studyPersonaIds } from "../../study/persona-resolve.js";
 import { refusedResult } from "../../run/study-result.js";
 /** The physical project, bound before any caller hook runs. */
@@ -145,6 +146,11 @@ export async function admitCuaRun(plan, input, config) {
         });
         if (rejection)
             return refuse(rejection.code, rejection.message, descriptor.id);
+        const shortfall = await localCapacityShortfall(input.localVm, participantPlan.concurrency);
+        if (shortfall !== undefined && "refusal" in shortfall)
+            return refuse("HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED", shortfall.refusal, descriptor.id);
+        if (shortfall !== undefined)
+            process.stderr.write(`warning: ${shortfall.warning}\n`);
     }
     // Pack the working tree once per run, on the host, before any sandbox or provider call: every
     // fan-out participant below uploads this same archive, so one archiveSha256 describes every
@@ -192,6 +198,14 @@ export async function admitCuaRun(plan, input, config) {
         },
     };
 }
+/**
+ * Whether a local study's desktops at once fit the local runtime. Read before any desktop: a
+ * desktop past the VM's memory is killed mid-session, after its participant has spent.
+ */
+async function localCapacityShortfall(localVm, desktops) {
+    const capacity = await localVm?.capacity?.();
+    return capacity === undefined ? undefined : capacityShortfall(capacity, desktops);
+}
 /** Starts the run and builds what the participants and the finish read: the deps and the bundle base. */
 export async function startCuaRun(plan, input, admitted, scope) {
     const { cwd, descriptor, participantRuns, participantPlan, publicRepo } = admitted;

package/dist/routes/computer-use/types.d.ts

@@ -1,4 +1,5 @@
 import type { Verdict } from "../../run/judge.js";
+import type { LocalCapacity } from "../../substrates/local/capacity.js";
 import type { RunDesktopRecording } from "../../evidence/desktop-recording-types.js";
 import type { CuaExecutor, CuaLiveMetadata, CuaLoopResult, CuaProvider } from "../../actors/computer-use/loop.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
@@ -38,6 +39,8 @@ export declare const MIN_DERIVED_SESSION_TIMEOUT_MS: number;
  */
 export interface LocalVmInput {
     readonly desktop: ParticipantDesktopFactory;
+    /** How many desktops the local runtime holds, or undefined when it cannot be read. */
+    readonly capacity?: () => Promise<LocalCapacity | undefined>;
     /** The skip reason automatic analysis records instead of running, or undefined to run it. */
     readonly analysisRefusal: () => AutomaticAnalysisRefusal | undefined;
     readonly signal?: AbortSignal;
@@ -182,7 +185,7 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED" | "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
 /** Subject provenance projection: what the actor actually drove. */
 export interface CuaSubjectProjection {
     source: "app-url" | "clone" | "local-tree";

package/dist/routes/shared-world/bundle-records.js

@@ -81,16 +81,17 @@ function sharedWorldStream(ctx, spec, index, view) {
     const { args } = ctx;
     const { name, session, screenshots, lastScreenshot, desktopGeometry, screenshotMode } = view;
     const judged = view.judgment.judgedStatus;
+    const caption = participantCaption({
+        id: spec.planned.id,
+        personaId: spec.persona.id,
+        device: spec.planned.device,
+    });
     return participantStream(spec, {
         ...(spec.evidenceAssignment === undefined
             ? {}
             : { assignment: participantAssignment(spec.evidenceAssignment) }),
         kind: "browser",
-        label: participantCaption({
-            id: spec.planned.id,
-            personaId: spec.persona.id,
-            device: spec.planned.device,
-        }),
+        label: caption,
         status: view.status,
         ...(judged === undefined ? {} : { judgedStatus: judged }),
         transport: "snapshot",
@@ -99,9 +100,9 @@ function sharedWorldStream(ctx, spec, index, view) {
             ? {
                 kind: "screenshot",
                 url: lastScreenshot,
-                title: `Shared plane, persona ${spec.planned.id} (${screenshotMode})`,
+                title: `${caption} (${screenshotMode})`,
             }
-            : { kind: "placeholder", title: `Shared plane, persona ${spec.planned.id}` },
+            : { kind: "placeholder", title: caption },
         ...(desktopGeometry.viewport === undefined
             ? {}
             : {

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

@@ -252,7 +252,7 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
     const overlaps = args.judgment.world.overlap;
     const deltas = (stateSeries ?? []).filter((snapshot, i) => i > 0 && snapshot.digest !== (stateSeries ?? [])[i - 1].digest).length;
     const stateSeriesLabel = external
-        ? "stateSeries omitted (no authoritative shared-state proof on the external-public plane)"
+        ? "Shared app state was not recorded because the app is hosted outside humanish"
         : `stateSeries ${plural((stateSeries ?? []).length, "snapshot")}, ${plural(deltas, "delta")}`;
     const convergenceLabel = external
         ? `; lobby convergence ${args.lobbyConvergenceDigest ? "shown (all participants reached one /lobby/CODE)" : "not observed"}`

package/dist/run/detail.js

@@ -13,7 +13,7 @@ import { estimateActorCostForExecution } from "./pricing.js";
 import { resolveRunPath } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { savedCaption } from "./participant-caption.js";
-import { streamParticipantIdOf } from "./participant-records.js";
+import { recordedPersonaId, streamParticipantIdOf } from "./participant-records.js";
 import { readContainedRegularFile } from "./contained-output.js";
 import { isPathInside, resolvePhysicalCwd } from "./paths.js";
 const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
@@ -43,12 +43,12 @@ function latestThought(trace) {
     }
     return undefined;
 }
-function participantFrom(stream, index) {
+function participantFrom(stream, index, savedPersonaId) {
     // A live run's flush wins over the finished trace: while both exist, the live one is the newer
     // account of what is happening.
     const trace = stream.liveActor ?? stream.actor ?? {};
     const id = stream.id ?? `stream-${index + 1}`;
-    const personaId = trace.persona?.id;
+    const personaId = trace.persona?.id ?? savedPersonaId;
     const participantId = streamParticipantIdOf(stream);
     // Computed once: calling it twice to test-then-use reads as though the two could differ.
     const thought = latestThought(trace);
@@ -140,7 +140,7 @@ export async function readRunDetail(cwdInput, runId) {
         ...(automaticAnalysis === undefined ? {} : { automaticAnalysis }),
         schema: RUN_DETAIL_SCHEMA,
         runId: bundle.runId ?? runId,
-        participants: streams.map(participantFrom),
+        participants: streams.map((stream, index) => participantFrom(stream, index, recordedPersonaId(bundle, stream))),
         ...(isPathInside(cwd, observerAbsolute)
             ? { observerPath: path.relative(cwd, observerAbsolute) }
             : { observerPath: observerAbsolute }),

package/dist/run/participant-caption.d.ts

@@ -25,6 +25,7 @@ export interface SavedCaptionFacts {
  * The caption a saved stream shows: its label, which a route writes with `participantCaption`.
  * Earlier releases wrote ids and taxonomy into the label (`lane-01 · browser`, `CUA participant
  * <id>: <study>`, `Concurrent persona <id> (type:<t> / ...) · <study>`), so a stream saved that way
- * is captioned again from the id it names, without a device.
+ * is captioned again from the id it names. Older terminal and scripted labels use the
+ * recorded persona; a scripted mobile surface also identifies a phone.
  */
 export declare function savedCaption(stream: SavedCaptionFacts): string;

package/dist/run/participant-caption.js

@@ -28,11 +28,13 @@ export function participantCaption(participant) {
 }
 const OLDER_SHARED_WORLD_LABEL = /^Concurrent persona (\S+)/;
 const OLDER_COMPUTER_USE_LABEL = /^CUA |^\S+ · browser$/;
+const OLDER_TERMINAL_OR_SCRIPTED_LABEL = /^(Terminal agent|Desktop browser surface|Mobile browser surface) · /;
 /**
  * The caption a saved stream shows: its label, which a route writes with `participantCaption`.
  * Earlier releases wrote ids and taxonomy into the label (`lane-01 · browser`, `CUA participant
  * <id>: <study>`, `Concurrent persona <id> (type:<t> / ...) · <study>`), so a stream saved that way
- * is captioned again from the id it names, without a device.
+ * is captioned again from the id it names. Older terminal and scripted labels use the
+ * recorded persona; a scripted mobile surface also identifies a phone.
  */
 export function savedCaption(stream) {
     const { label, participantId, personaId } = stream;
@@ -40,6 +42,14 @@ export function savedCaption(stream) {
     if (sharedWorldId !== undefined) {
         return participantCaption({ id: sharedWorldId, personaId: personaId ?? sharedWorldId });
     }
+    if (OLDER_TERMINAL_OR_SCRIPTED_LABEL.test(label) && personaId !== undefined) {
+        return participantCaption({
+            personaId,
+            ...(label.startsWith("Mobile browser surface · ")
+                ? { device: { name: "mobile", preset: { isMobile: true } } }
+                : {}),
+        });
+    }
     if (OLDER_COMPUTER_USE_LABEL.test(label) && personaId !== undefined) {
         return participantCaption({
             ...(participantId === undefined ? {} : { id: participantId }),

package/dist/run/participant-records.d.ts

@@ -1,4 +1,4 @@
-import type { RunEvent, RunProviderResource, RunSimulation } from "./bundle.js";
+import type { RunBundle, RunEvent, RunProviderResource, RunSimulation } from "./bundle.js";
 import type { RunStream } from "./streams.js";
 /** The ids a participant's saved records carry: its record id and its stream id. */
 export interface ParticipantIds {
@@ -26,3 +26,5 @@ export declare function recordIdOf(stream: RunStream): string;
 export declare function eventRecordIdOf(event: RunEvent): string | undefined;
 /** The participant id an adapter recorded on a saved stream (a fan-out `lane-NN` id), when it has one. */
 export declare function streamParticipantIdOf(stream: Pick<RunStream, "laneId">): string | undefined;
+/** The persona recorded for a stream, including dry runs without an actor trace. */
+export declare function recordedPersonaId(bundle: Partial<Pick<RunBundle, "simulations">>, stream: Partial<Pick<RunStream, "simId">>): string | undefined;

package/dist/run/participant-records.js

@@ -61,3 +61,9 @@ export function eventRecordIdOf(event) {
 export function streamParticipantIdOf(stream) {
     return stream.laneId;
 }
+/** The persona recorded for a stream, including dry runs without an actor trace. */
+export function recordedPersonaId(bundle, stream) {
+    if (stream.simId === undefined || !Array.isArray(bundle.simulations))
+        return undefined;
+    return bundle.simulations.find((record) => record?.id === stream.simId)?.personaId;
+}

package/dist/run-study.js

@@ -4,6 +4,9 @@
 // which runs the route's local checks that need no scorer (keys, subject env, the local agent) and
 // returns the route's run. prepareStudy is the same path in two steps, so the CLI can present either
 // refusal before it loads a declared review scorer.
+import { participantList } from "./study/study-fields.js";
+import { personaBackgroundWarnings } from "./study/warnings.js";
+import { resolveCommittedPersonasForCwd, studyPersonaIds } from "./study/persona-resolve.js";
 import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./study/route-inputs.js";
 import { planStudy, resolveStudyDryRun, routeOf } from "./study/plan.js";
 import { normalizeRunStudyOptions, optionRefusalOutcome, removedOptionRefusal, } from "./study/run-study-options.js";
@@ -70,7 +73,9 @@ export async function prepareStudy(config, options, deps = {}) {
         outcome.result.warnings.push(...normalized.warnings);
         return { ok: false, outcome };
     }
-    const admitted = await admitPlan(study, planning, planned.planned.plan, deps, normalized.emit);
+    const runWarnings = [...(planned.planned.plan.warnings ?? [])];
+    const plan = { ...planned.planned.plan, warnings: runWarnings };
+    const admitted = await admitPlan(study, planning, plan, deps, normalized.emit);
     if (!admitted.ok) {
         await vm?.close();
         admitted.outcome.result.warnings.push(...normalized.warnings);
@@ -92,6 +97,17 @@ export async function prepareStudy(config, options, deps = {}) {
                         return outcome;
                     }
                 }
+                // Admission keeps its refusal order; these warnings join the plan before its run scope opens.
+                const personas = route === "computer-use" || route === "shared-world"
+                    ? (await resolveCommittedPersonasForCwd(options.cwd, studyPersonaIds(study))).personas
+                    : new Map();
+                const backgroundWarnings = personaBackgroundWarnings(route === "computer-use" &&
+                    options.count !== undefined &&
+                    participantList(study) === undefined
+                    ? { ...study, participants: options.count }
+                    : study, personas);
+                runWarnings.splice(0, runWarnings.length, ...(planned.planned.plan.warnings ?? []), ...backgroundWarnings);
+                normalized.warnings.push(...backgroundWarnings);
                 // The route layers the scorer over the inputs it admitted, and the local study is not
                 // rebuilt for it. The admitted runSession, provider and participant desktop belong to this
                 // study, so a rebuilt one would leave the participants they start for no finally to close.

package/dist/study/discover.js

@@ -1,3 +1,4 @@
+import { personaBackgroundWarnings } from "./warnings.js";
 import { studyPersonaIds, resolveCommittedPersonasForCwd } from "./persona-resolve.js";
 import { personaBrief, PersonaConfigError } from "./persona.js";
 import { constants } from "node:fs";
@@ -193,7 +194,11 @@ export async function inspectStudyManifest(cwd, study) {
         config: resolved.config,
         origin: resolved.origin,
         path: resolved.path,
-        warnings: [...resolved.warnings, ...personaResolution.warnings],
+        warnings: [
+            ...resolved.warnings,
+            ...personaResolution.warnings,
+            ...personaBackgroundWarnings(resolved.config, personaResolution.personas),
+        ],
     };
 }
 function parseResolvedStudy(args) {

package/dist/study/doctor.d.ts

@@ -65,6 +65,8 @@ export declare function studySetupChecks(args: StudySetupCheckArgs): Promise<{
     keys: string[];
     reads?: ReadonlySet<string>;
     checks: Check[];
+    /** The step to take first, which doctor prints before its rows. */
+    next?: string;
 }>;
 /**
  * The ids of the project's labs that need each provider key for a live run, from the same plan

package/dist/study/doctor.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
+import { capacityShortfall, describeCapacity, } from "../substrates/local/capacity.js";
 import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { localAgentReady, localAgentVersionRefusal, } from "../actors/local-agent/cli.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
@@ -178,8 +179,11 @@ export async function studySetupChecks(args) {
     // One account check, shared by the local participant row and the Codex analysis row.
     let accountReadiness;
     const checkAccount = () => (accountReadiness ??= (args.codexAnalysisReadiness ?? codexAccountReadiness)(args.env).catch(() => ({ ready: false, errorCode: "codex_unavailable" })));
-    if (local)
-        checks.push(...(await localBrowserChecks(config, args)));
+    const plan = planned.planned.plan;
+    const desktopsAtOnce = plan.route === "computer-use" ? plan.concurrency : undefined;
+    const localChecks = local ? await localBrowserChecks(config, args, desktopsAtOnce) : undefined;
+    if (localChecks !== undefined)
+        checks.push(...localChecks.checks);
     if (config.comms?.email?.kind === "real")
         checks.push(await realEmailCheck(config.comms.email.connection, keys, args));
     checks.push(...(await participantChecks(config, route, keys, local, args, checkAccount)));
@@ -193,10 +197,19 @@ export async function studySetupChecks(args) {
     const reads = config.review?.scorer === undefined
         ? new Set([...keyNamesOf(planned.planned.plan), ...keys])
         : undefined;
-    return { desktop, keys, ...(reads === undefined ? {} : { reads }), checks };
+    return {
+        desktop,
+        keys,
+        ...(reads === undefined ? {} : { reads }),
+        checks,
+        ...(localChecks?.next === undefined ? {} : { next: localChecks.next }),
+    };
 }
-/** A local browser study's runtime and, with an external catch, its captured inbox. */
-async function localBrowserChecks(config, args) {
+/**
+ * A local browser study's runtime, how many of its desktops fit and, with an external catch, its
+ * captured inbox. `next` is the runtime's message when it is not ready, which doctor leads with.
+ */
+async function localBrowserChecks(config, args, desktopsAtOnce) {
     const checks = [];
     const runtime = await (args.localRuntimeReadiness ??
         (() => localRuntimeStatus({
@@ -204,7 +217,14 @@ async function localBrowserChecks(config, args) {
             media: config.execution?.desktop?.media !== undefined ||
                 config.execution?.desktop?.recording !== undefined,
         })))();
-    checks.push({ name: "local browser runtime", ok: runtime.ok, message: runtime.message });
+    checks.push({
+        name: "local browser runtime",
+        ok: runtime.ok,
+        message: runtime.message,
+        ...(runtime.ok && !runtime.installed ? { status: "note" } : {}),
+    });
+    if (runtime.capacity !== undefined && desktopsAtOnce !== undefined)
+        checks.push(capacityCheck(runtime.capacity, desktopsAtOnce));
     const email = config.comms?.email;
     if (email?.kind === "fake" && email.external) {
         const healthy = await externalCatchHealthy(email.external, { timeoutMs: 5000 });
@@ -216,7 +236,25 @@ async function localBrowserChecks(config, args) {
                 : `Captured inbox is unavailable or outdated. Start or upgrade and restart ${cli("comms catch")}, then check comms.email.external.catchBaseUrl (and inboxBaseUrl if set). No participant was allocated.`,
         });
     }
-    return checks;
+    return {
+        checks,
+        ...(runtime.ok && runtime.installed ? {} : { next: runtime.message }),
+    };
+}
+/** Whether the desktops the study runs at once fit the VM or this machine, and why. */
+function capacityCheck(capacity, desktopsAtOnce) {
+    const shortfall = capacityShortfall(capacity, desktopsAtOnce);
+    const name = "local desktop capacity";
+    if (shortfall === undefined)
+        return {
+            name,
+            ok: true,
+            message: `${describeCapacity(capacity)} This study runs ${desktopsAtOnce} at once, so it fits.`,
+        };
+    // Linux runs a study that is short of memory with a warning, so the row is advice there.
+    return "refusal" in shortfall
+        ? { name, ok: false, message: shortfall.refusal }
+        : { name, ok: true, status: "note", message: shortfall.warning };
 }
 /** The saved real email connection. Adds the key it needs to `keys`. */
 async function realEmailCheck(connection, keys, args) {

package/dist/study/init-templates.js

@@ -159,9 +159,11 @@ export const starterFiles = [
 id: synthetic-new-user
 name: Synthetic New User
 summary: A privacy-safe first-time user evaluating the app with realistic but synthetic needs.
-traits:
-  patience: medium
-  technical_confidence: medium
+background: >-
+  Alex keeps personal plans in a notebook and uses email and a few everyday apps without trouble.
+  They are trying an unfamiliar app to see whether it can make everyday tasks easier. They work
+  through some friction but stop when more effort no longer seems worth it, and they take the
+  straightforward path the screen offers.
 constraints:
   - Do not use real personal data.
   - Do not use production accounts.
@@ -175,9 +177,12 @@ constraints:
 id: skeptical-power-user
 name: Skeptical Power User
 summary: A privacy-safe experienced user looking for speed, reversibility, and clear proof.
+background: >-
+  Robin manages several volunteer projects with spreadsheets and keyboard shortcuts and is at ease
+  with advanced options. They want faster tools but have lost work before and care about undoing
+  mistakes. They have little patience for repeated friction and stop when a tool keeps getting in
+  the way.
 traits:
-  patience: low
-  technical_confidence: high
   accessibility_needs: keyboard_first
 constraints:
   - Do not use real personal data.

package/dist/study/plan.js

@@ -12,7 +12,7 @@ import { planBase } from "./plan-base.js";
 import { routeOf } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
 import { declaredParticipantCount } from "./study-fields.js";
-import { egressAllowIgnoredWarning } from "./warnings.js";
+import { egressAllowIgnoredWarning, scriptedMissionWarnings } from "./warnings.js";
 export { routeOf } from "./routing.js";
 /** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
 export function resolveStudyDryRun(config, override, fallback) {
@@ -76,10 +76,11 @@ export function planStudy(config, options, deps = {}) {
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
     const warning = egressAllowIgnoredWarning(study);
+    const warnings = [...(warning === undefined ? [] : [warning]), ...scriptedMissionWarnings(study)];
     const plan = {
         ...result.plan,
         ...(options.study === undefined ? {} : { study: options.study }),
-        ...(warning === undefined ? {} : { warnings: [warning] }),
+        ...(warnings.length === 0 ? {} : { warnings }),
     };
     return { ok: true, planned: { plan } };
 }

package/dist/study/preflight-result.d.ts

@@ -3,6 +3,7 @@ import type { StudyPreflightCheck, StudyPreflightResult, PreflightContext } from
 export declare const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export declare function finalize(ctx: PreflightContext, args?: {
     check?: StudyPreflightCheck;
+    checks?: StudyPreflightCheck[];
 }): StudyPreflightResult;
 export declare function fail(ctx: PreflightContext, code: NonNullable<StudyPreflightResult["error"]>["code"], message: string, checks: StudyPreflightCheck[]): StudyPreflightResult;
 export declare function digest(value: string): string;

package/dist/study/preflight-result.js

@@ -5,7 +5,7 @@ import { digestText } from "../evidence/redaction.js";
 /** The schema of `study check` results: whether a study is ready to run on this machine. */
 export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
-    const checks = args?.check ? [...ctx.checks, args.check] : ctx.checks;
+    const checks = [...ctx.checks, ...(args?.check ? [args.check] : []), ...(args?.checks ?? [])];
     const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route);
     return {
         schema: STUDY_CHECK_SCHEMA,

package/dist/study/preflight.d.ts

@@ -9,6 +9,8 @@ export interface StudyPreflightCheck {
     name: string;
     ok: boolean;
     message: string;
+    /** `false` on a row the CLI could not check; its message names the command that checks it. */
+    checked?: false;
 }
 export interface StudyPreflightTarget {
     label: string;