humanish 0.112.0 → 0.114.0

package/dist/run/notes.d.ts

@@ -0,0 +1,37 @@
+import type { RunBundle } from "./bundle.js";
+import { type RunNote } from "./note-files.js";
+import { type PreparedRunArtifactPaths } from "./paths.js";
+export { MAX_NOTE_TEXT, readNotesForSharing, readRunNotes, type RunNote, type RunNotes, } from "./note-files.js";
+export interface RunNoteInput {
+    atMs: number;
+    participant: string | null;
+    text: string;
+}
+export type RunNoteErrorCode = "HUMANISH_INVALID_RUN_BUNDLE" | "HUMANISH_NOTE_INVALID" | "HUMANISH_NOTE_NO_CLOCK" | "HUMANISH_NOTE_UNKNOWN_PARTICIPANT" | "HUMANISH_NOTE_OUTSIDE_RUN" | "HUMANISH_NOTES_UNREADABLE" | "HUMANISH_NOTES_FULL" | "HUMANISH_NOTE_ID_TAKEN";
+export type AddRunNoteResult = 
+/** `scrubbed`: redaction replaced part of the text before it was written. */
+{
+    ok: true;
+    note: RunNote;
+    scrubbed: boolean;
+} | {
+    ok: false;
+    error: {
+        code: RunNoteErrorCode;
+        message: string;
+    };
+};
+/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
+export declare function runParticipantCaptions(bundle: RunBundle): Map<string, string>;
+/** A run clock time as the Observer shows it: whole minutes and seconds, `02:31`. */
+export declare function formatRunTime(ms: number): string;
+/** The run clock: the first and last timed capture or desktop video moment, in epoch ms. */
+export declare function runClock(bundle: RunBundle): {
+    startMs: number;
+    endMs: number;
+} | null;
+/**
+ * Adds a note as a new file, notes/<id>.json, published under a name nothing holds. It reads no
+ * other note and replaces nothing, so notes added at the same time, from any process, are all kept.
+ */
+export declare function addRunNote(prepared: PreparedRunArtifactPaths, input: RunNoteInput): Promise<AddRunNoteResult>;

package/dist/run/notes.js

@@ -0,0 +1,198 @@
+// Reviewer notes: free text a person adds at a moment of a recorded run. Each note is its own file
+// in the run directory (note-files.ts). A note's time counts from the run clock's start, the
+// first timed capture or desktop video of any participant, which is the Observer's study clock.
+import { redactText } from "../evidence/redaction.js";
+import { writeNewContainedOutputFile } from "./contained-output.js";
+import { loadRunBundlePrepared } from "./locate.js";
+import { countRunNotes, encodeRunNote, MAX_NOTE_TEXT, MAX_RUN_NOTES, newRunNoteId, runNoteFile, } from "./note-files.js";
+import { streamCaptions } from "./participant-caption.js";
+import { recordedPersonaId, streamParticipantIdOf } from "./participant-records.js";
+import { physicalCwdOf, runIdOf } from "./paths.js";
+import { transientCommsKnownValueScrub } from "./transient-comms-secrets.js";
+import { isNodeError } from "./type-guards.js";
+export { MAX_NOTE_TEXT, readNotesForSharing, readRunNotes, } from "./note-files.js";
+const DEFAULT_AUTHOR = "you";
+/** New ids a note tries when the one before was taken. */
+const PUBLISH_ATTEMPTS = 5;
+const refuse = (code, message) => ({
+    ok: false,
+    error: { code, message },
+});
+/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
+export function runParticipantCaptions(bundle) {
+    return streamCaptions(bundle.streams.map((stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        const personaId = recordedPersonaId(bundle, stream);
+        return {
+            id: stream.id,
+            label: stream.label,
+            ...(participantId === undefined ? {} : { participantId }),
+            ...(personaId === undefined ? {} : { personaId }),
+        };
+    }));
+}
+/**
+ * The stream id a note's participant names: a stream id, or the participant's own id from the study
+ * (`charge-nurse`). Both kinds of id are matched, so a name that is one stream's id and another
+ * stream's study id is refused, naming both, as is a study id that two streams record. Otherwise
+ * the refusal names the run's participants by caption, with the id to type for each.
+ */
+function participantStreamId(bundle, named) {
+    const captions = runParticipantCaptions(bundle);
+    const matching = bundle.streams.filter((stream) => stream.id === named || streamParticipantIdOf(stream) === named);
+    if (matching.length === 1)
+        return matching[0].id;
+    const described = (stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        return `${captions.get(stream.id)} (stream id ${stream.id}${participantId === undefined ? "" : `, study id ${participantId}`})`;
+    };
+    if (matching.length > 1)
+        return refuse("HUMANISH_NOTE_UNKNOWN_PARTICIPANT", `${named} names ${matching.length} participants in run ${bundle.runId}: ${matching.map(described).join(" and ")}. Name the one you mean by an id only it has.`);
+    const known = bundle.streams.map((stream) => `${captions.get(stream.id)} (${streamParticipantIdOf(stream) ?? stream.id})`);
+    return refuse("HUMANISH_NOTE_UNKNOWN_PARTICIPANT", `Run ${bundle.runId} has no participant ${named}. Its participants are ${known.join(", ")}; leave the participant out for a note on the whole run.`);
+}
+/** A run clock time as the Observer shows it: whole minutes and seconds, `02:31`. */
+export function formatRunTime(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    return `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}`;
+}
+/** The run clock: the first and last timed capture or desktop video moment, in epoch ms. */
+export function runClock(bundle) {
+    const moments = bundle.streams.flatMap((stream) => [
+        ...(captureTimes(stream) ?? []),
+        ...recordingMoments(stream),
+    ]);
+    if (moments.length === 0)
+        return null;
+    // A loop, since spreading a long recording's capture times into Math.min can overflow the stack.
+    let startMs = Infinity;
+    let endMs = -Infinity;
+    for (const moment of moments) {
+        startMs = Math.min(startMs, moment);
+        endMs = Math.max(endMs, moment);
+    }
+    return { startMs, endMs };
+}
+function traceItems(stream) {
+    return stream.actor?.items ?? stream.liveActor?.items ?? [];
+}
+const stamp = (item) => item.at === undefined ? Number.NaN : Date.parse(item.at);
+/**
+ * A participant's capture times, as the Observer's study clock reads them: only when every capture
+ * is stamped and the stamps never go back. Otherwise the participant adds nothing to the clock.
+ */
+function captureTimes(stream) {
+    const times = traceItems(stream)
+        .filter((item) => (item.kind === "screenshot" || item.kind === "ui_action") && item.screenshotRef)
+        .map(stamp);
+    const ordered = times.every((time, index) => Number.isFinite(time) && (index === 0 || time >= times[index - 1]));
+    return ordered ? times : null;
+}
+function recordingMoments(stream) {
+    const recording = stream.recording;
+    if (!recording)
+        return [];
+    const startMs = Date.parse(recording.startedAt);
+    const endMs = startMs + recording.durationMs;
+    return Number.isFinite(startMs) && Number.isFinite(endMs) && recording.durationMs > 0
+        ? [startMs, endMs]
+        : [];
+}
+/** The latest stamped trace item at or before `moment`, among the given participants. */
+function nearestItem(streams, moment) {
+    let best = null;
+    for (const stream of streams)
+        for (const item of traceItems(stream)) {
+            const time = stamp(item);
+            if (Number.isFinite(time) && time <= moment && (best === null || time >= best.time))
+                best = { participant: stream.id, itemId: item.id, time };
+        }
+    return best === null ? null : { participant: best.participant, itemId: best.itemId };
+}
+/**
+ * The text as it is written: line breaks as `\n`, the run's known values and every secret-shaped
+ * value or local path replaced, as other run text is before it is written.
+ */
+function scrubNoteText(text) {
+    let known;
+    try {
+        known = transientCommsKnownValueScrub()(text);
+    }
+    catch {
+        // A closed run scope refuses to scrub and has dropped its values. The note then gets the
+        // pattern redaction that a separate `humanish notes` process gives it.
+        known = text;
+    }
+    return redactText(known.replace(/\r\n?/g, "\n").trim());
+}
+/** Why the text cannot be a note, or null when it can. */
+function noteTextProblem(text) {
+    if (text.length === 0)
+        return "A note needs some text.";
+    if (text.length > MAX_NOTE_TEXT)
+        return `A note holds at most ${MAX_NOTE_TEXT} characters; this one has ${text.length}. Shorten it and add it again.`;
+    if (/[\u0000-\u0008\u000b-\u001f\u007f]/.test(text))
+        return "A note holds plain text and line breaks; this one has a control character. Remove it and add the note again.";
+    return null;
+}
+/**
+ * Adds a note as a new file, notes/<id>.json, published under a name nothing holds. It reads no
+ * other note and replaces nothing, so notes added at the same time, from any process, are all kept.
+ */
+export async function addRunNote(prepared, input) {
+    const text = scrubNoteText(input.text);
+    const problem = noteTextProblem(text);
+    if (problem)
+        return refuse("HUMANISH_NOTE_INVALID", problem);
+    // Containment checks throw on a link or special file anywhere in the run directory.
+    const loaded = await loadRunBundlePrepared(physicalCwdOf(prepared), prepared).catch(() => null);
+    if (!loaded)
+        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `Run ${runIdOf(prepared)} has no run.json humanish can read safely, so no note was added. \`humanish verify --run ${runIdOf(prepared)}\` says what is wrong with it.`);
+    const { bundle } = loaded;
+    const clock = runClock(bundle);
+    if (!clock)
+        return refuse("HUMANISH_NOTE_NO_CLOCK", `Run ${bundle.runId} has no captures with recorded times, so a note cannot point at a moment of it.`);
+    const participant = input.participant === null ? null : participantStreamId(bundle, input.participant);
+    if (participant !== null && typeof participant !== "string")
+        return participant;
+    // The Observer shows whole seconds, so a moment in the second the clock ends is its end.
+    const durationMs = clock.endMs - clock.startMs;
+    if (!Number.isFinite(input.atMs) ||
+        input.atMs < 0 ||
+        Math.floor(input.atMs / 1000) > Math.floor(durationMs / 1000))
+        return refuse("HUMANISH_NOTE_OUTSIDE_RUN", `A note on run ${bundle.runId} needs a moment from 00:00 to ${formatRunTime(durationMs)}, the time its captures cover.`);
+    const atMs = Math.min(Math.round(input.atMs), durationMs);
+    const streams = bundle.streams.filter((stream) => participant === null || stream.id === participant);
+    const now = new Date();
+    const fields = {
+        atMs,
+        participant,
+        nearest: nearestItem(streams, clock.startMs + atMs),
+        text,
+        author: DEFAULT_AUTHOR,
+        createdAt: now.toISOString(),
+        editedAt: null,
+    };
+    try {
+        // A count of the files notes/ lists; no note is read.
+        if ((await countRunNotes(prepared)) >= MAX_RUN_NOTES)
+            return refuse("HUMANISH_NOTES_FULL", `Run ${bundle.runId} already has ${MAX_RUN_NOTES} notes, the most one run keeps.`);
+        // The note appears only under a name nothing holds; a taken name gets a new id.
+        for (let attempt = 0; attempt < PUBLISH_ATTEMPTS; attempt += 1) {
+            const note = { id: newRunNoteId(now), ...fields };
+            try {
+                await writeNewContainedOutputFile(prepared, runNoteFile(note.id), encodeRunNote(note, bundle.runId));
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === "EEXIST")
+                    continue;
+                throw error;
+            }
+            return { ok: true, note, scrubbed: text !== input.text.replace(/\r\n?/g, "\n").trim() };
+        }
+    }
+    catch {
+        return refuse("HUMANISH_NOTES_UNREADABLE", `The notes folder in run ${bundle.runId} is not a plain folder inside the run, so no note was added. Move it out of the run directory and add the note again.`);
+    }
+    return refuse("HUMANISH_NOTE_ID_TAKEN", `Each new id humanish chose for the note was already taken in run ${bundle.runId}'s notes folder, so no note was added. Something else is writing files there; add the note again.`);
+}

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

@@ -25,6 +25,16 @@ 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;
+/** A saved stream, as much of it as `streamCaptions` reads. */
+export interface CaptionedStream extends SavedCaptionFacts {
+    readonly id: string;
+}
+/**
+ * Each stream's caption, by stream id, as the Observer shows it: the saved caption, with the
+ * participant id or the stream id added where two streams would read the same.
+ */
+export declare function streamCaptions(streams: readonly CaptionedStream[]): Map<string, 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 }),
@@ -48,3 +58,22 @@ export function savedCaption(stream) {
     }
     return label;
 }
+/**
+ * Each stream's caption, by stream id, as the Observer shows it: the saved caption, with the
+ * participant id or the stream id added where two streams would read the same.
+ */
+export function streamCaptions(streams) {
+    const repeated = (labels) => new Set(labels.filter((label, index) => labels.indexOf(label) !== index));
+    const saved = streams.map(savedCaption);
+    const savedTwice = repeated(saved);
+    const qualified = streams.map((stream, index) => savedTwice.has(saved[index])
+        ? `${saved[index]} · ${stream.participantId ?? stream.id}`
+        : saved[index]);
+    const qualifiedTwice = repeated(qualified);
+    return new Map(streams.map((stream, index) => [
+        stream.id,
+        qualifiedTwice.has(qualified[index])
+            ? `${qualified[index]} · ${stream.id}`
+            : qualified[index],
+    ]));
+}

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) {
@@ -330,7 +368,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         ok: true,
         ...(keyed ? {} : { status: "note" }),
         message: keyed
-            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its estimate is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its expected cost plus a 10% margin is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
             : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
     };
 }

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

@@ -2,11 +2,12 @@
 // preflight-probes.ts both finish through these, so they live below both.
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { digestText } from "../evidence/redaction.js";
+import { computerUseParticipantCount } from "./routing.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 analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route);
+    const checks = [...ctx.checks, ...(args?.check ? [args.check] : []), ...(args?.checks ?? [])];
+    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
     return {
         schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),

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;