humanish 0.116.0 → 0.118.0

package/dist/verify/artifacts.d.ts

@@ -7,6 +7,20 @@ export declare const MAX_REPORTED_FINDINGS = 50;
  * refuses a run with more, so the scan never passes a run whose files it did not all read.
  */
 export declare const MAX_RUN_ENTRIES = 10000;
+/** What the public-safety scan did not read. A run with any of it cannot grade share_ready. */
+export interface UnscannedArtifacts {
+    /** Run files it could not read as text, by run-relative path. */
+    readonly files: string[];
+    /** Folders it could not list, by run-relative path ("" is the run folder). */
+    readonly unlistedFolders: string[];
+    /** The folder it was listing when it reached MAX_RUN_ENTRIES. It read nothing listed after. */
+    stoppedIn?: string;
+}
+/**
+ * The UNSCANNED_ARTIFACT reason: the files the scan could not read, the folders it could not list
+ * and where it stopped, each in its own sentence. Undefined when the scan read everything.
+ */
+export declare function unscannedMessage(unscanned: UnscannedArtifacts): string | undefined;
 export declare function missingLocalEvidenceArtifacts(runPaths: PreparedRunArtifactPaths, bundle: RunBundle): Promise<string[]>;
 /**
  * The PNG frames that actor traces register as stream screenshots, relative to the run root.
@@ -50,9 +64,10 @@ interface RegisteredStreamMedia {
 /**
  * Scans every run file for secret and path patterns and returns the findings. A file that is not
  * registered stream media and that the scan cannot read as text (readPlainText), cannot read at
- * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned`, so the caller can keep
- * the run from grading share_ready. So does a directory it cannot list, and the rest of the run
- * after MAX_RUN_ENTRIES entries.
+ * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned.files`, so the caller can
+ * keep the run from grading share_ready. A directory it cannot list goes to
+ * `unscanned.unlistedFolders`, and the directory it was listing when it passed MAX_RUN_ENTRIES
+ * entries is `unscanned.stoppedIn`.
  */
-export declare function scanRunPublicSafetyArtifacts(runPaths: PreparedRunArtifactPaths, derivedFindings: string[], media: RegisteredStreamMedia, unscanned: string[]): Promise<string[]>;
+export declare function scanRunPublicSafetyArtifacts(runPaths: PreparedRunArtifactPaths, derivedFindings: string[], media: RegisteredStreamMedia, unscanned: UnscannedArtifacts): Promise<string[]>;
 export {};

package/dist/verify/artifacts.js

@@ -12,6 +12,7 @@ import { SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
 import { readSafeRunArtifact, readSafeRunArtifactBytes, readSafeRunArtifactJson, } from "../run/locate.js";
 import { isRecord } from "../run/type-guards.js";
 import { TERMINAL_EVENTS_ARTIFACT } from "../run/terminal-contract.js";
+import { plural } from "../run/text.js";
 import { isZeroEventTerminalTrace } from "./actor.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export const MAX_REPORTED_FINDINGS = 50;
@@ -20,6 +21,35 @@ export const MAX_REPORTED_FINDINGS = 50;
  * refuses a run with more, so the scan never passes a run whose files it did not all read.
  */
 export const MAX_RUN_ENTRIES = 10_000;
+// The UNSCANNED_ARTIFACT reason names this many paths of each kind and counts the rest.
+const MAX_LISTED_UNSCANNED = 10;
+/**
+ * The UNSCANNED_ARTIFACT reason: the files the scan could not read, the folders it could not list
+ * and where it stopped, each in its own sentence. Undefined when the scan read everything.
+ */
+export function unscannedMessage(unscanned) {
+    const files = [...new Set(unscanned.files)].sort();
+    const folders = [...new Set(unscanned.unlistedFolders)].sort().map(folderName);
+    const sentences = [];
+    if (files.length > 0)
+        sentences.push(`The public-safety scan cannot read ${plural(files.length, "file")} as text that ${files.length === 1 ? "is not a stream screenshot under screenshots/ or a registered recording" : "are not stream screenshots under screenshots/ or registered recordings"}: ${listed(files)}.`);
+    if (folders.length > 0)
+        sentences.push(`The public-safety scan could not list ${plural(folders.length, "folder")}, so it read none of the files in ${folders.length === 1 ? "it" : "them"}: ${listed(folders)}.`);
+    if (unscanned.stoppedIn !== undefined)
+        sentences.push(`The public-safety scan stopped at its limit of ${MAX_RUN_ENTRIES} files and folders while listing ${folderName(unscanned.stoppedIn)}, so it read nothing listed after that point.`);
+    if (sentences.length === 0)
+        return undefined;
+    const onlyFiles = folders.length === 0 && unscanned.stoppedIn === undefined;
+    sentences.push(onlyFiles ? "Review them before sharing." : "Review the run folder before sharing.");
+    return sentences.join(" ");
+}
+function folderName(relativeDirectory) {
+    return relativeDirectory === "" ? "the run folder" : `${relativeDirectory}/`;
+}
+function listed(paths) {
+    const more = paths.length - MAX_LISTED_UNSCANNED;
+    return `${paths.slice(0, MAX_LISTED_UNSCANNED).join(", ")}${more > 0 ? ` and ${more} more` : ""}`;
+}
 export async function missingLocalEvidenceArtifacts(runPaths, bundle) {
     const recordings = new Map(bundle.streams.flatMap((stream) => stream.recording ? [[stream.recording.path, stream.recording]] : []));
     const requiredPaths = new Map();
@@ -291,9 +321,10 @@ export function rawScreenshotStreamIds(bundle, redactedShapeFrames) {
 /**
  * Scans every run file for secret and path patterns and returns the findings. A file that is not
  * registered stream media and that the scan cannot read as text (readPlainText), cannot read at
- * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned`, so the caller can keep
- * the run from grading share_ready. So does a directory it cannot list, and the rest of the run
- * after MAX_RUN_ENTRIES entries.
+ * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned.files`, so the caller can
+ * keep the run from grading share_ready. A directory it cannot list goes to
+ * `unscanned.unlistedFolders`, and the directory it was listing when it passed MAX_RUN_ENTRIES
+ * entries is `unscanned.stoppedIn`.
  */
 export async function scanRunPublicSafetyArtifacts(runPaths, derivedFindings, media, unscanned) {
     const findings = [];
@@ -315,14 +346,14 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
         : runPaths.physicalRunRoot;
     const entries = await readdir(current).catch(() => null);
     if (entries === null) {
-        unscanned.push(`${relativeDirectory || "."}/ (could not be listed)`);
+        unscanned.unlistedFolders.push(relativeDirectory);
         return;
     }
     for (const entryName of entries) {
         walk.entries += 1;
         if (walk.entries > MAX_RUN_ENTRIES) {
-            if (walk.entries === MAX_RUN_ENTRIES + 1)
-                unscanned.push(`${relativeDirectory || "."}/ (the scan stops after ${MAX_RUN_ENTRIES} entries)`);
+            // Every directory the walk returns through comes here once more; the first one stopped it.
+            unscanned.stoppedIn ??= relativeDirectory;
             return;
         }
         const relativePath = relativeDirectory ? `${relativeDirectory}/${entryName}` : entryName;
@@ -371,7 +402,7 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
         const bytes = await readSafeRunArtifactBytes(runPaths, relativePath).catch(() => null);
         const decoded = bytes === null ? undefined : readPlainText(bytes);
         if (decoded === undefined || !decoded.ok) {
-            unscanned.push(relativePath);
+            unscanned.files.push(relativePath);
             continue;
         }
         // A receipt's id in any other file, or a raw id at a sandbox-id key, which an older run or
@@ -389,7 +420,7 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
             selectedFindings.push(`sensitive text ${relativePath}`);
         }
         else if (scan.opaque) {
-            unscanned.push(relativePath);
+            unscanned.files.push(relativePath);
         }
     }
 }

package/dist/verify/verify.js

@@ -13,18 +13,15 @@ import { SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
 import { isRecord } from "../run/type-guards.js";
 import { runNotFoundMessage } from "../run/run-not-found.js";
 import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
-import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, streamScreenshotPaths, } from "./artifacts.js";
+import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, streamScreenshotPaths, unscannedMessage, } from "./artifacts.js";
 import { flatContextWarnings } from "./context-growth.js";
 import { runNotFinished } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
 import { sharedWorldEvidenceFindings } from "./shared-world.js";
 import { subjectStateFindings, undeclaredSubjectStateWarnings } from "./subject.js";
-import { plural } from "../run/text.js";
 import { cli } from "../cli/invocation.js";
 export const VERIFY_SCHEMA = "humanish.verify-result.v1";
-// The UNSCANNED_ARTIFACT reason names this many paths and counts the rest.
-const MAX_LISTED_UNSCANNED = 10;
 export async function verifyRun(cwdInput, runInput) {
     const cwd = path.resolve(cwdInput);
     let runPaths;
@@ -86,7 +83,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
     };
     checks.push(...bundlePresenceChecks(bundleRead, review));
     const derivedPublicSafetyFindings = [];
-    const unscannedArtifacts = [];
+    const unscannedArtifacts = { files: [], unlistedFolders: [] };
     const sandboxIdFiles = [];
     let journaledSandboxIds = [];
     try {
@@ -96,7 +93,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         if (!(error instanceof ContainedReadRefusedError))
             throw error;
         // Without the journal's ids, verify cannot clear any file of naming one.
-        unscannedArtifacts.push(SANDBOX_RECEIPTS_ARTIFACT);
+        unscannedArtifacts.files.push(SANDBOX_RECEIPTS_ARTIFACT);
     }
     const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
         recordingPaths: new Set(isRunBundle(bundle)
@@ -397,15 +394,9 @@ function buildShareSafety(args) {
             message: "Continuous screen/audio recordings are retained for local review. Screenshot redaction does not redact this media.",
         });
     }
-    if (args.unscannedArtifacts.length > 0) {
-        const paths = [...new Set(args.unscannedArtifacts)].sort();
-        const shown = paths.slice(0, MAX_LISTED_UNSCANNED).join(", ");
-        const more = paths.length - MAX_LISTED_UNSCANNED;
-        reasons.push({
-            code: "UNSCANNED_ARTIFACT",
-            message: `The public-safety scan cannot read ${plural(paths.length, "file")} as text that ${paths.length === 1 ? "is not a stream screenshot under screenshots/ or a registered recording" : "are not stream screenshots under screenshots/ or registered recordings"}: ${shown}${more > 0 ? ` and ${more} more` : ""}. Review them before sharing.`,
-        });
-    }
+    const unscanned = unscannedMessage(args.unscannedArtifacts);
+    if (unscanned !== undefined)
+        reasons.push({ code: "UNSCANNED_ARTIFACT", message: unscanned });
     // Runs from 0.110 keep raw sandbox ids only in sandbox-receipts.ndjson. An earlier run records
     // them in run.json, and any file that names one is not share-ready as it is.
     const rawResources = (args.bundle.providerResources ?? []).some((resource) => resource.id !== REDACTED_SANDBOX_ID);

package/docs/architecture/browser-control.md

@@ -103,10 +103,16 @@ Observation requires a PNG and state signature. It may include bounded URL,
 title, text, fractional scroll position and heard speech; those remain
 runtime-only under the existing loop contract. Arbitrary `appState` is refused
 because v1 has no closed schema for it. The protocol does not truncate strings,
-round coordinates, or silently drop unsupported state. A Codex participant's
-`humanish_ui` call is checked before it reaches the protocol: a wait longer than 30 seconds is
-shortened to 30 seconds there, and the trace records a `wait shortened` notice with both
-durations.
+round coordinates, or silently drop unsupported state. A participant may ask for a
+longer wait than one request carries. The computer-use loop shortens it to the study's
+`actor.maxWaitMs` (by default two minutes, or 30 seconds on a desktop with speech, whose heard
+speech reaches the participant only with a screenshot), records a `wait shortened` notice with both
+durations when it does, and sends the rest as consecutive waits of at most 30 seconds. The Codex
+participant's `humanish_ui` schema leaves a wait's length open for that reason; the wire still
+refuses a single wait over 30 seconds. A wait that names no duration, as every OpenAI computer-use
+wait does, reaches the desktop with a length too: the study's `actor.idleWaitMs` (5 seconds by
+default) when the participant's turn only waits or takes screenshots, and 500 ms after an action in
+the same turn.
 
 Click, double-click, move, scroll and drag may carry `heldKeys`, which the
 OpenAI provider maps from its computer tool's `keys`. The Codex participant's

package/docs/contracts/run-bundle.md

@@ -305,15 +305,16 @@ exactly; this hosted-desktop rule does not change that contract.
 `subject` is an optional, additive top-level field: structured provenance for
 what the computer-use, shared-world or scripted route actually drove (code pin plus state story). It
 is absent on pre-existing bundles and on bundles from routes that have not
-adopted it. The field shape, its four sources (`clone`, `app-url`,
-`local-tree`, `desktop-cli`), and the `humanish verify` checks that guard it are the schema doc's
-job, not this one: see the `subject` entry under
+adopted it. The field shape, its five sources (`clone`, `app-url`,
+`local-tree`, `desktop-cli`, `local-app`), and the `humanish verify` checks that guard it are the
+schema doc's job, not this one: see the `subject` entry under
 [`schemas.md`](schemas.md#run-bundle). In short, `clone` carries a
 `repo`/`commit` pin, `local-tree` carries an `archiveSha256`/`dirty` pin
 instead (a dirty working tree cannot be commit-pinned), `desktop-cli` carries the
-declared `product` name, and `app-url` carries no code pin at all. A computer-use run
-of a desktop-cli study saved before `desktop-cli` was recorded says `app-url`, and
-readers accept it. No path, basename, or other host-machine string ever
+declared `product` name, and `app-url` and `local-app` (a running app the caller drives in
+process) carry no code pin at all. A computer-use run of a desktop-cli study saved before
+`desktop-cli` was recorded, or of a local-app study saved before `local-app` was recorded, says
+`app-url`, and readers accept it. No path, basename, or other host-machine string ever
 enters this field; identity is digests, a sha, a boolean, counts and the declared product name.
 
 ## Cost Estimate (advisory)

package/docs/contracts/schemas.md

@@ -76,17 +76,17 @@ map each one to its v3 key.
 A study declares its route and composes code primitives; it is not a hardcoded kind. The
 top-level keys:
 
-| Key                                                               | Meaning                                                                                                                                            |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schema`, `id`, `title`, `description`                            | the document's identity                                                                                                                            |
-| `route`                                                           | required: `preview`, `computer-use`, `shared-world`, `terminal` or `scripted`                                                                      |
-| `mode`                                                            | `dry-run` (the default) or `live`                                                                                                                  |
-| `actor`                                                           | who drives it, one object: `type`, `model`, `localAgent`, `persona`, `mission`, `tasks`, `maxOutputTokens`, `reasoningEffort`, `stopWhen`, `dwell` |
-| `participants`                                                    | a count, a homogeneous `{ count, instruction }`, or a list of entries (below)                                                                      |
-| `surfaces`                                                        | scripted only: `[desktop]` or `[desktop, mobile]`                                                                                                  |
-| `caps`                                                            | the route's budget (below)                                                                                                                         |
-| `scenario`                                                        | scripted only: a committed scenario id or path                                                                                                     |
-| `subject`, `execution`, `policies`, `review`, `defaults`, `comms` | as below                                                                                                                                           |
+| Key                                                               | Meaning                                                                                                                                                                       |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`, `id`, `title`, `description`                            | the document's identity                                                                                                                                                       |
+| `route`                                                           | required: `preview`, `computer-use`, `shared-world`, `terminal` or `scripted`                                                                                                 |
+| `mode`                                                            | `dry-run` (the default) or `live`                                                                                                                                             |
+| `actor`                                                           | who drives it, one object: `type`, `model`, `localAgent`, `persona`, `mission`, `tasks`, `maxOutputTokens`, `maxWaitMs`, `idleWaitMs`, `reasoningEffort`, `stopWhen`, `dwell` |
+| `participants`                                                    | a count, a homogeneous `{ count, instruction }`, or a list of entries (below)                                                                                                 |
+| `surfaces`                                                        | scripted only: `[desktop]` or `[desktop, mobile]`                                                                                                                             |
+| `caps`                                                            | the route's budget (below)                                                                                                                                                    |
+| `scenario`                                                        | scripted only: a committed scenario id or path                                                                                                                                |
+| `subject`, `execution`, `policies`, `review`, `defaults`, `comms` | as below                                                                                                                                                                      |
 
 The parser reads only the declared route's keys. A key that route never reads is an error that
 names the route, such as "route: computer-use does not read scenario. Remove it.", and an
@@ -183,7 +183,7 @@ The rest of this section names keys by their v3 spelling:
   owns the live sandbox, auth, cap, evidence, and cleanup lifecycle.
   A `participants` count is the preview route's participant count (simCount),
   and on the computer-use **E2B** route the homogeneous fan-out count (N
-  identical participants, each its own E2B desktop: separate worlds, cap 16).
+  identical participants, each its own E2B desktop: separate worlds, at most 100).
   The scripted route's `surfaces` is its surface list (`[desktop]`, the default,
   or `[desktop, mobile]`). The in-process/local-app computer-use route stays
   single participant (no E2B to fan out);
@@ -197,7 +197,8 @@ The rest of this section names keys by their v3 spelling:
   so `--count` does not apply to it, and each entry's `instruction` is the steer;
   an entry's `device` is XOR with a raw `execution.desktop.resolution`. Participant ids
   default `lane-01`..`lane-NN` (`role-01`..`role-NN` for shared-world participants), must be unique, and name per-participant evidence paths
-  (`actors/<streamId>.json`, `screenshots/<laneId>/`). Cap 16 participants. The other
+  (`actors/<streamId>.json`, `screenshots/<laneId>/`). At most 100 participants, on the
+  shared-world route too. The other
   routes refuse a list (table above). `subject.clone.fanout` is rejected on the
   computer-use, shared-world and scripted routes (declare fan-out with
   `participants`). No current route reads `clone.fanout`;
@@ -216,9 +217,12 @@ The rest of this section names keys by their v3 spelling:
   shape. Ids are checked for collisions after expansion;
 - `execution.concurrency` (computer-use E2B routes, including shared-world): a
   cap on participants in flight at once. When omitted, every participant runs
-  simultaneously: independent participants resolve it from the final participant count,
-  after any `--count` override, and the parser fills `concurrency = participantCount`
-  for multi-participant shared-world studies. Total sessions and spend are identical either way; only wall-clock
+  simultaneously: both routes resolve it when they plan, from the final participant count
+  after any `--count` override. On hosted desktops the plan runs at most
+  `HUMANISH_E2B_MAX_CONCURRENT_SANDBOXES` sandboxes at once (20 when unset; a provisioned
+  shared world's app sandbox counts against it), so a larger roster runs in waves and the plan
+  records a warning naming the setting. A declared value above that limit is refused at plan
+  time. Total sessions and spend are identical either way; only wall-clock
   and simultaneity differ. Declaring a value below the participant count runs participants in
   waves and emits a warning saying so, because a green waved run is otherwise
   indistinguishable from the all-live run the author meant. Shared-world studies
@@ -529,7 +533,7 @@ Core-owned fields:
   an older run, else `inferLegacyStudyId`, which reads the `persona.source` or `scenario.source`
   convention `study:<id>`, or `lab:<id>` from runs written before 0.108, and nothing else.
 - `subject` (optional, additive): structured subject provenance,
-  `{ source: clone | app-url | local-tree | desktop-cli, repo?, product?, commit?,
+  `{ source: clone | app-url | local-tree | desktop-cli | local-app, repo?, product?, commit?,
   archiveSha256?, dirty?, envNames?, state }` where `state` is `{ provenance: seeded |
   unpinned | declared-not-run | undeclared | external-public, seed?: [{ name, when,
   commandDigest, ok?, exitCode?, timedOut?, durationMs? }], externalEnvNames?
@@ -541,7 +545,9 @@ Core-owned fields:
   the archive content digest stands in for it. `product` is the desktop-cli field: the
   `subject.product.name` the study declares, with state `undeclared`. A computer-use
   run of a desktop-cli study saved before this field existed records `app-url` with no
-  `product`. `commandDigest` is the
+  `product`. `local-app` is an in-process run of a local-app study, the caller's running app
+  with no code pin and state `undeclared`; one saved before that value existed records
+  `app-url`. `commandDigest` is the
   sha256-16 of the exact seed command; command text and env values never
   appear. `humanish verify` fails closed when a live `local-tree` bundle carries
   no well-formed `archiveSha256`, in addition to the existing `subject state
@@ -985,6 +991,14 @@ Core-owned fields:
   “provider reply cut off by the output limit; asking again” notice. A second
   cut-off reply to the same request ends the session with
   `stopCause: provider_output_limit`.
+- optional `waitSettings`: the wait lengths a computer-use participant's session
+  applied, in milliseconds, defaults included. `maxWaitMs` is the longest one
+  wait action lasts (`actor.maxWaitMs`); a longer wait is shortened to it.
+  `idleWaitMs` is how long a wait that names no duration lasts in a turn that
+  only waits or takes screenshots (`actor.idleWaitMs`), and `settleWaitMs` how
+  long such a wait lasts after an action in the same turn. Each `ui_action` for
+  a wait is titled with the length it lasted. Absent on other routes and on
+  earlier bundles
 - optional `conversation`: how the first-party OpenAI computer-use provider
   carried the conversation between requests. `mode` is `threaded` (the server
   kept it through `previous_response_id`) or `explicit_context` (the server kept
@@ -1668,7 +1682,7 @@ of it fails.
 | `cuaLaneCount`                                                                                                                                 | the `plan` `StudyEvent`, which lists every participant                                                                                                                                                                                                                                                                                         |
 | `resolveSeatUrl`                                                                                                                               | `parseStudy`, which refuses a participant entry that is not same-origin loopback; build the URL with `new URL(entry, serveUrl)`                                                                                                                                                                                                                |
 | `cuaLaneValidationReason`, `sharedWorldValidationReason`, `concurrentSharedWorldValidationReason`, `externalPublicSharedWorldValidationReason` | `parseStudy`, which returns the same reason                                                                                                                                                                                                                                                                                                    |
-| `MAX_CUA_LANES`                                                                                                                                | none; `parseStudy` refuses a roster of more than 16 participants                                                                                                                                                                                                                                                                               |
+| `MAX_CUA_LANES`                                                                                                                                | none; `parseStudy` refuses a roster of more than 100 participants                                                                                                                                                                                                                                                                              |
 
 ## Product-Adapter Extension Seam
 

package/docs/contracts/study-analysis.md

@@ -27,8 +27,8 @@ The default provider is `openai`; its default model is `gpt-6-astra`, with high
 captures to OpenAI, without tools, redirects, provider-side response storage, or
 automatic retries. `--question` adds a reviewer question; it never changes the
 participant assignment. For OpenAI API analysis, `--max-cost` is required, including for dry-run
-admission. Admission compares the expected cost plus a 10% margin with it; the
-provider bill is not limited by it.
+admission. Admission refuses the request when both its worst case and its expected cost plus a
+10% margin are over it; the provider bill is not limited by it.
 `--timeout-ms` and `--max-output-tokens` bound the request. A bill above the
 worst case or the cap retains valid findings and usage but returns a partial
 result and a nonzero command exit, including when that version is reused.

package/docs/principles/invariants-and-defaults.md

@@ -96,7 +96,7 @@ silently drifting from one is not.
 | Loopback entry URLs                         | Public-safety: never drive third-party sites unbidden                                                                                                                                                                                                               | `policies.allowPublicTargets` for an owner-declared deployment/preview (a Vercel preview of your own app). Multi-participant public/preview fan-out needs explicit `participants[].target` for every participant, so the adapter-owned topology is declared rather than inferred. Provisioned clone subjects always serve in-sandbox on loopback                                                                                                                                                                                                                                                                                                                                                           |
 | Full-fidelity screenshots, local            | The common case is watching a run of your own app locally; blur destroys the deliverable. Raw frames live in gitignored `.humanish/` (this repo's CI adds a binary-asset commit scan; downstream projects rely on the scaffolded `.gitignore` and their own review) | `policies.redactScreenshots: true` blurs at capture; `export --format bundle --redact-screenshots` produces a separate verified copy of a completed run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | Synthetic, seeded state                     | Pinned provenance; no real user data in evidence paths                                                                                                                                                                                                              | Declared external state, recorded as unpinned in provenance                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| Single participant                          | Cost + evidence simplicity                                                                                                                                                                                                                                          | Declared fan-out where the route supports it: `participants: N` (homogeneous), an explicit `participants` list (differentiated persona/device/instruction), or list entries with a `count` that expand into one entry per participant on the computer-use E2B route (separate worlds, cap 16; `execution.concurrency` bounds concurrent paid participants)                                                                                                                                                                                                                                                                                                                                                 |
+| Single participant                          | Cost + evidence simplicity                                                                                                                                                                                                                                          | Declared fan-out where the route supports it: `participants: N` (homogeneous), an explicit `participants` list (differentiated persona/device/instruction), or list entries with a `count` that expand into one entry per participant on the computer-use E2B route (separate worlds, at most 100; `execution.concurrency` and the E2B plan bound concurrent paid participants)                                                                                                                                                                                                                                                                                                                            |
 | Stock `desktop` template                    | The stock E2B desktop image is right for most subjects; absent `execution.desktop.template` keeps `Sandbox.create(opts)` byte-stable                                                                                                                                | `execution.desktop.template` names a custom E2B desktop image (any name/id, no allowlist) for a subject needing baked-in runtimes the stock image lacks (e.g. node/bun/a local Postgres); it is threaded to `Sandbox.create(template, opts)` on every desktop-creating route and recorded in the bundle as `desktopTemplate` (public-safe)                                                                                                                                                                                                                                                                                                                                                                 |
 | Desktop default URL opener                  | Preserve the route/image's historical browser/default opener behavior when unset                                                                                                                                                                                    | `execution.desktop.browser` set to `chrome`, `chromium` or `firefox` makes the hosted CUA/shared-world browser choice explicit, fail-closed, and recorded as `desktopBrowser` in the run bundle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Loopback-only observer serving              | Run bundles are local by default (public-safety plank 3); the serve/watch surfaces bind `127.0.0.1` unconditionally, and exposing them is publishing-adjacent, so exposure is fail-closed and carries declared friction                                             | `humanish observe --all --expose` behind tunnel-edge auth (ngrok `--oauth google` with `--allow-email`/`--allow-domain` allow rules, or an operator `--public-url` you secure), or `--expose --safe` (open, gated on verify-`share_ready` runs only). `watch --expose` streams a live run behind edge auth (a live run is never `share_ready`, so `--safe` alone is refused). humanish carries no in-process auth; both print computed warnings naming exactly what became reachable                                                                                                                                                                                                                       |

package/docs/product/automatic-analysis.md

@@ -23,12 +23,13 @@ review:
 Omitting `review.analysis` uses these defaults. Set `review.analysis: false` to
 run participants without the additional analysis request. An explicit analysis
 mapping using the default OpenAI API provider requires `maxCostUsd`. Admission
-compares the expected cost plus a 10% margin with it; it does not limit the
-provider's final bill, and it is separate from participant spending limits. The
+refuses the request when both its worst case and its expected cost plus a 10% margin are over
+it; it does not limit the provider's final bill, and it is separate from participant spending limits. The
 estimate gives two numbers: the expected cost, and the worst case if the analyst
 spends its whole output allowance. `humanish study check` gives the expected cost
 range for the study's participant count, from a run that keeps no evidence to one
-at the evidence limits. Use `analyze --dry-run --max-cost <usd>` on retained
+that keeps the most evidence admission admits under the cap, at most the evidence limits. When
+the cap admits no analysis at all, it says so instead. Use `analyze --dry-run --max-cost <usd>` on retained
 evidence to inspect the expected cost, the worst case and the selected token
 allowance before deliberately choosing a larger budget. Explicit
 `maxOutputTokens` and `--max-output-tokens` limits are honored exactly. The output allowance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.116.0",
+  "version": "0.118.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -91,7 +91,7 @@
     "comms:agentmail:contract": "node --import tsx scripts/agentmail-contract-check.mjs",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "lint": "node scripts/check-lint-cap.mjs --max-warnings=436",
+    "lint": "node scripts/check-lint-cap.mjs --max-warnings=426",
     "knip": "knip",
     "prose:check": "node scripts/check-code-prose.mjs",
     "vocabulary:check": "tsx scripts/check-retired-words.ts",