humanish 0.111.4 → 0.113.0

package/dist/run/run-index.d.ts

@@ -1,6 +1,6 @@
 import { AnalysisCostCache } from "./run-index-analysis.js";
 import type { RunAnalysisCost } from "./run-cost.js";
-import { type RunLiveness, type RunStatusRecord } from "./status.js";
+import { type RunLiveness } from "./status.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import type { ExecutionFailure } from "./judge.js";
 declare const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
@@ -51,13 +51,6 @@ export interface RunIndexResult {
     /** Directories that could not be read at all, by name: surfaced, never silently dropped. */
     unreadable: string[];
 }
-/** What a cached entry was derived from, so a changed file invalidates exactly that entry. */
-interface CacheKey {
-    file: string;
-    mtimeMs: number;
-    size: number;
-    ino: number;
-}
 /**
  * A process-lifetime cache. Deliberately explicit rather than module-global state: a caller that
  * refreshes on a cadence keeps one and passes it back, and a caller that wants a cold read passes
@@ -67,51 +60,12 @@ export declare class RunIndexCache {
     private readonly slots;
     /** Analysis costs, keyed on their own fingerprint: analysis lands after the status record. */
     readonly analysis: AnalysisCostCache;
-    get(runId: string, key: CacheKey): RunIndexEntry | undefined;
-    set(runId: string, key: CacheKey, entry: RunIndexEntry): void;
+    get(runId: string, key: string): RunIndexEntry | undefined;
+    set(runId: string, key: string, entry: RunIndexEntry): void;
     /** Drop entries for runs that no longer exist, so a long-lived surface cannot leak. */
     retain(runIds: Iterable<string>): void;
     get size(): number;
 }
-/** The legacy shape this reads out of a bundle. Narrow on purpose: only listing facts. */
-interface BundleFacts {
-    runId?: string;
-    mode?: string;
-    createdAt?: string;
-    study?: unknown;
-    lab?: unknown;
-    persona?: {
-        source?: string;
-    };
-    scenario?: {
-        source?: string;
-    };
-    simulations?: {
-        status?: string;
-    }[];
-    review?: {
-        verdict?: string;
-        participants?: {
-            total: number;
-            reachedGoal: number;
-            reportedFriction?: number;
-        };
-    };
-    cost?: {
-        estimatedTotalUsd?: number | null;
-        fullyEstimated?: unknown;
-    };
-    outcome?: unknown;
-}
-/**
- * One run's liveness from files already read: its status record when usable, else its bundle.
- * `readRunIndex` reads in the same order; `humanish verify` calls this with both in hand. `record`
- * is the status record the liveness came from, when there was one.
- */
-export declare function runLiveness(runId: string, status: unknown, bundle: Pick<BundleFacts, "simulations" | "outcome">, nowMs: number): {
-    liveness: RunLiveness;
-    record?: RunStatusRecord;
-};
 export interface ReadRunIndexOptions {
     /** Reused across refreshes so unchanged runs are not re-read. */
     cache?: RunIndexCache;
@@ -122,7 +76,7 @@ export interface ReadRunIndexOptions {
     limit?: number;
 }
 /**
- * Read every run in `.humanish/runs`, cheapest source first. Never throws for a bad run directory;
+ * Read every run in `.humanish/runs`, from its cached source files. Never throws for a bad run directory;
  * an unreadable one is named in `unreadable`.
  */
 export declare function readRunIndex(cwdInput: string, options?: ReadRunIndexOptions): Promise<RunIndexResult>;

package/dist/run/run-index.js

@@ -1,20 +1,9 @@
-// The run index: list and classify every run in a project without parsing bundles.
-//
-// The existing `listRuns` walks each run tree, screenshots included, validating symlinks and
-// then parses each `run.json`: measured 197ms cold / 152ms warm at 25 runs. That is fine for a
-// command that prints once and exits, and much too hot for a surface that refreshes on a cadence
-// over SSH. This module reads the small `status.json` record each run now writes (586 bytes beside
-// a 92KB bundle) and caches per-run entries keyed on the stat of the file each was derived from.
-//
-// Rules, unchanged from the record itself:
-//   - `run.json` is the evidence-of-record. Every field here is a projection for listing and
-//     classification; nothing here is a claim about what a participant did.
-//   - A run with no status record is not assumed finished. It is classified from what is on disk:
-//     a bundle means finished, receipts without a bundle mean interrupted. That is the
-//     reading of a run whose process died (and, before this contract existed, of every run).
-//   - One unreadable run directory degrades that run, never the listing.
+// The run index caches listing facts by both source files. run.json's outcome wins over status,
+// including when a process stopped between publishing its bundle and finalizing its heartbeat.
+// A status record supplies freshness only when the bundle has no outcome.
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { runLiveness } from "./liveness.js";
 import { AnalysisCostCache, readIndexedAnalysisCost } from "./run-index-analysis.js";
 import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, } from "./status.js";
 import { studyProvenanceOf } from "./study-provenance.js";
@@ -34,11 +23,7 @@ export class RunIndexCache {
         const slot = this.slots.get(runId);
         if (slot === undefined)
             return undefined;
-        const same = slot.key.file === key.file &&
-            slot.key.mtimeMs === key.mtimeMs &&
-            slot.key.size === key.size &&
-            slot.key.ino === key.ino;
-        return same ? slot.entry : undefined;
+        return slot.key === key ? slot.entry : undefined;
     }
     set(runId, key, entry) {
         this.slots.set(runId, { key, entry });
@@ -81,7 +66,7 @@ function entryFromStatus(record, nowMs) {
     return {
         runId: record.runId,
         derivedFrom: "status",
-        liveness: classifyRunStatus(record, nowMs),
+        liveness: runLiveness(record.runId, record, {}, nowMs).liveness,
         mode: record.mode,
         ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
         ...studyEntry(studyProvenanceOf(record)),
@@ -109,29 +94,6 @@ function entryFromStatus(record, nowMs) {
 function usableStatusRecord(raw, runId) {
     return isRunStatusRecord(raw) && raw.runId === runId;
 }
-/**
- * The bundle-only reading, for a run with no usable status record. A bundle on disk usually means
- * the run reached its final write. But a live run now flushes an in-progress bundle as it goes (so
- * anything asking what a participant is doing has something to read), and that bundle marks its
- * simulations `running`. With no status record there is no freshness to judge, and the
- * reading of "it started, and nothing here says it finished" is interrupted, not finished.
- */
-function bundleLiveness(bundle) {
-    if (isRunOutcome(bundle.outcome))
-        return bundle.outcome.state;
-    const inProgress = (bundle.simulations ?? []).some((simulation) => simulation?.status === "running");
-    return inProgress ? "interrupted" : "finished";
-}
-/**
- * One run's liveness from files already read: its status record when usable, else its bundle.
- * `readRunIndex` reads in the same order; `humanish verify` calls this with both in hand. `record`
- * is the status record the liveness came from, when there was one.
- */
-export function runLiveness(runId, status, bundle, nowMs) {
-    return usableStatusRecord(status, runId)
-        ? { liveness: classifyRunStatus(status, nowMs), record: status }
-        : { liveness: bundleLiveness(bundle) };
-}
 function studyEntry(study) {
     return study === undefined ? {} : { study };
 }
@@ -141,7 +103,7 @@ function entryFromBundle(runId, bundle) {
     return {
         runId,
         derivedFrom: "bundle",
-        liveness: bundleLiveness(bundle),
+        liveness: runLiveness(runId, undefined, { simulations: bundle.simulations, outcome }, Date.now()).liveness,
         ...(bundle.mode === "dry-run" || bundle.mode === "live" ? { mode: bundle.mode } : {}),
         ...studyEntry(studyProvenanceOf(bundle)),
         ...(bundle.createdAt === undefined ? {} : { startedAt: bundle.createdAt }),
@@ -160,7 +122,7 @@ function entryFromBundle(runId, bundle) {
     };
 }
 /**
- * Read every run in `.humanish/runs`, cheapest source first. Never throws for a bad run directory;
+ * Read every run in `.humanish/runs`, from its cached source files. Never throws for a bad run directory;
  * an unreadable one is named in `unreadable`.
  */
 export async function readRunIndex(cwdInput, options = {}) {
@@ -199,52 +161,60 @@ export async function readRunIndex(cwdInput, options = {}) {
         unreadable,
     };
 }
-/** One run's entry, cheapest source first, or "unreadable" when its bundle cannot be parsed. */
+/** One run's entry, from its cached source files, or "unreadable" when its bundle cannot be parsed. */
 async function readEntry(runId, runDir, cache, nowMs) {
     const statusFile = path.join(runDir, RUN_STATUS_FILE);
     const bundleFile = path.join(runDir, RUN_BUNDLE_FILE);
-    // Cheapest source first: the status record. Its stat is the cache key, so a live run whose
-    // record ticks every 5s re-reads 586 bytes and nothing else.
-    const statusKey = await statKey(statusFile);
-    if (statusKey !== null) {
-        const cached = cache?.get(runId, statusKey);
-        if (cached !== undefined) {
-            // A running record's liveness is time-dependent, so it is recomputed even on a cache hit:
-            // an unchanged record can still have gone stale. An ended record (finished or
-            // interrupted, both with completedAt) keeps the liveness it was cached with.
-            return cached.derivedFrom === "status" &&
-                cached.updatedAt !== undefined &&
-                cached.completedAt === undefined
-                ? {
-                    ...cached,
-                    liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
-                }
-                : cached;
-        }
-        const raw = await readJson(statusFile);
-        if (usableStatusRecord(raw, runId)) {
-            const entry = entryFromStatus(raw, nowMs);
-            cache?.set(runId, statusKey, entry);
-            return entry;
-        }
+    const [statusKey, bundleKey] = await Promise.all([statKey(statusFile), statKey(bundleFile)]);
+    const key = JSON.stringify([statusKey, bundleKey]);
+    const cached = cache?.get(runId, key);
+    if (cached !== undefined) {
+        return cached.derivedFrom === "status" &&
+            cached.updatedAt !== undefined &&
+            cached.completedAt === undefined
+            ? {
+                ...cached,
+                liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
+            }
+            : cached;
+    }
+    const [status, raw] = await Promise.all([
+        statusKey === null ? undefined : readJson(statusFile),
+        bundleKey === null ? undefined : readJson(bundleFile),
+    ]);
+    const record = usableStatusRecord(status, runId) ? status : undefined;
+    const bundle = raw !== null && typeof raw === "object" ? raw : undefined;
+    let entry;
+    if (bundle !== undefined && isRunOutcome(bundle.outcome)) {
+        const metadata = record === undefined ? undefined : entryFromStatus(record, nowMs);
+        entry = {
+            ...(metadata === undefined
+                ? {}
+                : {
+                    pid: metadata.pid,
+                    startedAt: metadata.startedAt,
+                    updatedAt: metadata.updatedAt,
+                    ...(metadata.completedAt === undefined ? {} : { completedAt: metadata.completedAt }),
+                    ...(metadata.durationMs === undefined ? {} : { durationMs: metadata.durationMs }),
+                    ...studyEntry(metadata.study),
+                }),
+            ...entryFromBundle(runId, bundle),
+        };
+    }
+    else if (record !== undefined) {
+        entry = entryFromStatus(record, nowMs);
+    }
+    else if (bundle !== undefined) {
+        entry = entryFromBundle(runId, bundle);
+    }
+    else if (bundleKey !== null) {
+        return "unreadable";
     }
-    // No usable status record: fall back to the bundle. This is every run written before the
-    // contract existed, and it is why an old project still lists correctly.
-    const bundleKey = await statKey(bundleFile);
-    if (bundleKey !== null) {
-        const cached = cache?.get(runId, bundleKey);
-        if (cached !== undefined)
-            return cached;
-        const raw = await readJson(bundleFile);
-        if (raw === null || typeof raw !== "object")
-            return "unreadable";
-        const entry = entryFromBundle(runId, raw);
-        cache?.set(runId, bundleKey, entry);
-        return entry;
+    else {
+        return { runId, derivedFrom: "directory", liveness: "interrupted" };
     }
-    // Neither record nor bundle: receipts without an outcome. That is precisely an interrupted
-    // run (the shape a dropped connection leaves), and saying so is more useful than hiding it.
-    return { runId, derivedFrom: "directory", liveness: "interrupted" };
+    cache?.set(runId, key, entry);
+    return entry;
 }
 /** Newest-first ordering: the most recent thing known about a run, else its id's own timestamp. */
 function sortKey(entry) {

package/dist/run/run.d.ts

@@ -15,7 +15,7 @@ interface StartRunOptions {
     /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
     sandboxes?: "none" | undefined;
     /** review.md for the published bundle. */
-    renderReview: (bundle: RunBundle) => string;
+    renderReview: (bundle: RunBundle, status?: unknown) => string;
     /** Used by `FinishedRun.renderObserver`; `render` is the `StudyDeps.renderObserver` seam. */
     observer?: {
         open: boolean;
@@ -53,7 +53,7 @@ interface RouteRunOptions {
     cwd: string;
     prefix: RunIdPrefix;
     /** review.md for the published bundle. */
-    renderReview: (bundle: RunBundle) => string;
+    renderReview: (bundle: RunBundle, status?: unknown) => string;
     /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
     sandboxes?: "none" | undefined;
     /** Clock for `createdAt` and the latest pointer. The minted id reads the wall clock. */

package/dist/run/run.js

@@ -14,7 +14,8 @@ import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
 import { RunSecrets } from "./secrets.js";
-import { beginRunStatus, runStatusOutcome, } from "./status.js";
+import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
+import { readRunJsonIfExists } from "./locate.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";
@@ -165,11 +166,12 @@ function runPublisher(args) {
         });
         await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(publicBundle), "utf8");
         await afterBundle(publicBundle);
+        const status = recorded === undefined ? await readRunJsonIfExists(paths, RUN_STATUS_FILE) : undefined;
         await writeContainedOutputFile(paths, "review.json", json(publicBundle.review), "utf8");
-        await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle), "utf8");
+        await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle, status), "utf8");
         const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");
         await writeContainedOutputFile(paths, "events.ndjson", `${events}\n`, "utf8");
-        await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle)), "utf8");
+        await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle, undefined, status)), "utf8");
     };
     const snapshot = async (bundle) => {
         await writeBundleFiles(bundle, undefined, async () => { });

package/dist/run/stats.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { runDisplay, runDisplayLabel } from "./display.js";
 import { readRunIndex } from "./run-index.js";
 import { addCostTotals, emptyCostTotals, readCostTotals, } from "./costs.js";
+import { runEstimateUsd } from "./run-cost.js";
 import { round6 } from "./pricing.js";
 import { plural } from "./text.js";
 const STATS_SCHEMA = "humanish.stats.v2";
@@ -27,17 +28,6 @@ function addParticipants(into, entry) {
     into.reachedGoal += entry.participants.reachedGoal;
     into.reportedFriction += entry.participants.reportedFriction ?? 0;
 }
-/**
- * A run's participant and desktop estimate: its recorded figure, or $0 for a dry run that records
- * none, since a dry run makes no model request and creates no desktop. Undefined when the cost is
- * unknown, including a dry run that records an unknown (null) figure.
- */
-function runEstimateUsd(entry) {
-    const usd = entry.estimatedCostUsd;
-    if (typeof usd === "number" && Number.isFinite(usd) && usd >= 0)
-        return usd;
-    return usd === undefined && entry.mode === "dry-run" ? 0 : undefined;
-}
 function entryTime(entry) {
     return entry.startedAt ?? entry.completedAt ?? entry.updatedAt;
 }
@@ -175,7 +165,7 @@ export async function computeStats(cwdInput, options = {}) {
             totals.dryRun += 1;
         if (entry.liveness === "running")
             totals.running += 1;
-        const runUsd = runEstimateUsd(entry);
+        const runUsd = runEstimateUsd(entry) ?? undefined;
         if (runUsd === undefined)
             totals.unpricedRuns += 1;
         else

package/dist/run/transient-comms-secrets.d.ts

@@ -4,7 +4,12 @@ export declare function registerTransientCommsSecrets(values: string[]): void;
 /** Literal, longest-first replacement in one pass; replacement text is never matched recursively. */
 export declare function scrubTransientCommsText(text: string): string;
 /**
- * The scope's values as a scrubSecretValues scrub, which also finds them percent-encoded, escaped or
- * base64-encoded and returns decoded text. Outside a scope it changes nothing.
+ * A scrub for text a model writes: each scope value as written and in its encoded forms
+ * (percent-encoded, JSON-escaped, base64, base64url, hex), and where escapes split one. Text that
+ * holds an encoded value is returned decoded with each value replaced. Text without one keeps its
+ * original spelling, so an exact quote that holds an escape still matches its evidence. The literal
+ * scrub runs first, before decoding can rewrite a value that itself holds an escape, and last,
+ * because the encoded scrub leaves text inside marker-shaped spans alone. Outside a scope it
+ * changes nothing.
  */
-export declare function transientCommsEncodedScrub(): (text: string) => string;
+export declare function transientCommsKnownValueScrub(): (text: string) => string;

package/dist/run/transient-comms-secrets.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { decodeEscapes } from "../evidence/encoded-text.js";
 import { scrubSecretValues } from "../evidence/secret-scrub.js";
 import { escapeRegExp } from "./text.js";
 const scopes = new AsyncLocalStorage();
@@ -75,10 +76,29 @@ export function scrubTransientCommsText(text) {
  * The scope's values as a scrubSecretValues scrub, which also finds them percent-encoded, escaped or
  * base64-encoded and returns decoded text. Outside a scope it changes nothing.
  */
-export function transientCommsEncodedScrub() {
+function transientCommsEncodedScrub() {
     const scope = scopes.getStore();
     if (!scope)
         return (text) => text;
     usable(scope);
     return scrubSecretValues([...scope.values]);
 }
+const REDACTED = "[REDACTED_SECRET]";
+const markers = (text) => text.split(REDACTED).length - 1;
+/**
+ * A scrub for text a model writes: each scope value as written and in its encoded forms
+ * (percent-encoded, JSON-escaped, base64, base64url, hex), and where escapes split one. Text that
+ * holds an encoded value is returned decoded with each value replaced. Text without one keeps its
+ * original spelling, so an exact quote that holds an escape still matches its evidence. The literal
+ * scrub runs first, before decoding can rewrite a value that itself holds an escape, and last,
+ * because the encoded scrub leaves text inside marker-shaped spans alone. Outside a scope it
+ * changes nothing.
+ */
+export function transientCommsKnownValueScrub() {
+    const encoded = transientCommsEncodedScrub();
+    return (text) => {
+        const literal = scrubTransientCommsText(text);
+        const found = encoded(literal);
+        return scrubTransientCommsText(markers(found) > markers(decodeEscapes(literal)) ? found : literal);
+    };
+}

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/keys.d.ts

@@ -168,6 +168,7 @@ export declare const EXECUTION: {
     terminal: {
         stdin: true;
         transport: true;
+        doNotTrack: true;
     };
     desktop: {
         template: true;

package/dist/study/keys.js

@@ -108,7 +108,7 @@ export const EXECUTION = {
     timeoutMs: true,
     completionTimeoutMs: true,
     egressAllow: true,
-    terminal: { stdin: true, transport: true },
+    terminal: { stdin: true, transport: true, doNotTrack: true },
     desktop: {
         template: true,
         browser: true,

package/dist/study/parse/execution.js

@@ -75,9 +75,15 @@ function parseTerminal(raw) {
         return { ok: true, value: undefined };
     }
     if (!isRecord(raw)) {
-        return invalid("`execution.terminal` must be an object ({ transport?, stdin? }).");
+        return invalid("`execution.terminal` must be an object ({ transport?, stdin?, doNotTrack? }).");
     }
     const terminal = {};
+    if (raw.doNotTrack !== undefined) {
+        if (typeof raw.doNotTrack !== "boolean") {
+            return invalid("`execution.terminal.doNotTrack` must be true or false (unquoted).");
+        }
+        terminal.doNotTrack = raw.doNotTrack;
+    }
     if (raw.transport !== undefined) {
         const transport = str(raw.transport);
         if (transport !== "exec-stream") {

package/dist/study/plan-types.d.ts

@@ -217,6 +217,7 @@ export type TerminalPlan = PlanBase & {
     readonly personaId?: string;
     readonly mission?: string;
     readonly runtime: {
+        readonly doNotTrack: boolean;
         readonly version?: string;
         /** Passed to Codex as `--model` on every run, so the bundle can name and price it. */
         readonly model: string;