humanish 0.117.0 → 0.119.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/contracts/run-bundle.md

@@ -65,7 +65,7 @@ scenario:
   goal: "<scenario goal>"
   source: "<scenario source>"
   sourceDigest: "<sha256>"
-simulations: [] # simCount entries, each paired with its streams
+simulations: [] # simCount entries, each paired with its streams; `arrival` when the study declares starts
 streams: []
 events: []
 artifacts:
@@ -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

@@ -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`;
@@ -214,11 +215,26 @@ The rest of this section names keys by their v3 spelling:
   `<id>-01` … `<id>-NN`, even when n is 1, before the engine runs (`viewer-01`,
   `viewer-02`, ...), so the runtime and run bundle keep one normalized participant
   shape. Ids are checked for collisions after expansion;
+- `participants[].startAfterMs` (computer-use and shared-world): when the participant
+  starts, in whole milliseconds after the run starts its participants, from 0 to 86,400,000
+  (24 hours). A `count` group's `startEveryMs` gives member k the start
+  `startAfterMs + (k - 1) * startEveryMs`, expanded at parse time like the ids. Refused: an
+  interval without `count`, a member past 24 hours, a start on a study of one participant, and a
+  later start for the external-public `host`. Participants start in order of their starts, each
+  at its time or when a slot frees under `execution.concurrency` and the E2B plan's limit,
+  whichever is later (`runOnSchedule` in `src/study/arrivals.ts`). Each participant's desktop is
+  created when it starts. The plan (`arrivals`, `planArrivals`) reports the first and last start
+  and the most participants at once with every session at its full budget, and the provisioned
+  shared world's subject sandbox serves until the last session can end, which the plan checks
+  against the sandbox ceiling. A rerun starts its selected participants together;
 - `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
@@ -512,7 +528,13 @@ Core-owned fields:
 - `artifactRoot`
 - `source.git`
 - `lifecycle`
-- `simulations`
+- `simulations`: one record per participant. On the computer-use and shared-world routes, a
+  study that declares `participants[].startAfterMs` gives each record `arrival:
+  { startAfterMs, scheduledAt?, startedAt? }`: the participant's offset (0 when its entry declares
+  none), the moment the run started its participants plus that offset, and when its desktop was
+  requested, which is later than `scheduledAt` when it waited for a free slot. A dry run records
+  only the offset, and a participant that never started has no `startedAt`. The record's own
+  `startedAt` is the run's creation time.
 - `streams`
 - `events`
 - `redaction`
@@ -529,7 +551,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 +563,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
@@ -1676,7 +1700,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.
@@ -37,17 +37,27 @@ The estimate counts the instructions, evidence packet and result schema at 3
 UTF-8 bytes per input token, adds 2,048 framing tokens and each capture's
 high-detail image tokens, and prices input at the model's highest input rate.
 The expected output is 12,000 tokens plus 1,000 per participant, at most the
-output allowance; the worst case spends the whole allowance. `admission` in
+output allowance; the worst case spends the whole allowance. A run with more than
+16 participants sends one request per cohort and a merge request
+([runs with more than 16 participants](#runs-with-more-than-16-participants)),
+and the estimate is their sum, each request priced on its own long-context tier.
+The merge request's input is its instructions, packet and schema, counted the same
+way, plus each cohort's report at that request's whole output allowance; it is
+expected to write what one request covering every participant would. `admission` in
 `--json` output has `estimatedCostUsd` (the expected cost), `worstCaseCostUsd`,
 `admittedCostUsd` (the figure compared with the cap: the expected cost plus 10%,
 or the worst case when that is lower), `maxCostUsd`, `inputTokenAllowance` (the
-input tokens priced) and `outputTokenAllowance`. On 148 billed gpt-6-astra
+input tokens priced), `outputTokenAllowance` (each request's) and `requests` (the
+requests the costs cover: 1, or each cohort's and the merge request; null when the
+input or configuration was refused). The dry run's worst case for more than one
+request says every request writes its whole allowance and names the cohort and merge
+requests, in the words the plan's analysis line uses. On 148 billed gpt-6-astra
 analyses the expected cost was 1.08 to 7.3 times the bill, and 1.08 to 1.32
 times for those billed $1 or more.
 A refusal's message gives the expected cost, the worst case, the cap, and
 `humanish analyze --run <id> --max-cost <n>` with `n` the worst case rounded up.
 
-The default deadline is ten minutes. With no explicit output-token limit, analysis
+The default deadline is ten minutes for each request. With no explicit output-token limit, analysis
 uses 32,768 tokens if admission fits the declared budget, or retains the prior
 16,384-token allowance otherwise. Explicit limits are never adjusted. Selection
 happens before dispatch; `admission.outputTokenAllowance` exposes it in dry-run,
@@ -64,6 +74,48 @@ success. Findings keep reported concerns and observed recovery distinct across
 participants. Other supported models can be selected explicitly, but evidence
 reference validation does not certify their interpretation of small visual details.
 
+## Runs with more than 16 participants
+
+One analysis covers up to 128 participants, the most streams it reads from a run
+bundle. A request covers at most 16 (`EVIDENCE_LIMITS.cohortParticipants` in
+`src/analysis/analysis-limits.ts`). A run with more is split into the fewest
+cohorts of at most 16, with participants dealt in roster order: 17 participants
+make cohorts of 9 and 8, 24 make two of 12, 40 make 14, 13 and 13, and 100 make
+seven. Each cohort's packet is selected under the packet limits below on its own,
+so each participant keeps at least the evidence a 16-participant run gives it.
+Evidence IDs are numbered across the whole run, so they stay unique.
+
+Each cohort request uses the standard instructions, schema and validation, with
+only its own participants' evidence and captures. Up to four run at once for
+OpenAI, which keeps four requests at the packet limits under the lowest paid
+tier's gpt-6-astra rate limit of 1,000,000 tokens a minute; Codex runs one at a
+time. Then one merge request reads the cohort reports, never the evidence or the
+captures. It writes the summary, findings, design findings, concern reviews and
+limitations for the whole run; the participant reviews are the cohorts' own.
+Its findings, design findings and concern reviews may cite only evidence that a
+cohort report cites in its own findings, design findings or concern reviews
+(`analysis_validation_failed_merge_reference_invalid` otherwise), and the merged
+report passes the same reference, membership and basis checks against the run's
+whole packet as a single request's report does.
+
+The attempt has one execution start, one receipt and one `analysis.json`, with the
+run's participants, coverage and evidence and the summed usage of every request
+sent. The artifact schema is unchanged. Its stored limits grew to hold eight
+cohorts: 6,400 evidence items, 320 captures and 16 MiB. If a cohort request fails
+or is rejected, no further request starts, requests already sent finish, no merge
+request is sent and the attempt fails with that request's code, with no findings;
+a warning names the cohort's size. A failed merge request fails the attempt the same way. The usage
+still counts every request sent. Findings from part of the participants are not
+kept as a report on the run.
+
+The first live cohort analysis, on a 24-participant computer-use run, sent two
+cohort requests of 12 participants and the merge request in 5 minutes 6 seconds.
+Its expected cost was $6.08, 2.3 times its $2.65 bill, and each of its 447
+citations resolved in the run's packet. A second analysis of the same run, with
+the current merge instructions, billed $1.92, most of its input served from the
+provider's prompt cache, and each of its 466 citations resolved. Two runs do not
+calibrate the merge request's estimate.
+
 ## Explicit Codex account analysis
 
 An existing completed recording can use a separate restricted Codex analyst:
@@ -85,8 +137,9 @@ converted to API authentication.
 Omit `--max-cost` and `--max-output-tokens` for Codex. Numeric declarations are
 rejected because this transport does not enforce them. `maxCostUsd` and
 `maxOutputTokens` are stored as null. The existing evidence bounds, one analyst
-turn, bounded response bytes and whole-operation timeout still apply. One turn
-is not a claim of one upstream billed request; account limits apply. Reported
+turn per request (one per cohort, and the merge request), bounded response bytes
+and whole-operation timeout still apply. One turn is not a claim of one upstream
+billed request; account limits apply. Reported
 tokens remain inspectable, but dollar estimates, admission dollars and rate dates
 remain null. Interrupted token observations remain explicitly incomplete.
 
@@ -128,7 +181,7 @@ stopped, an operator can remove the empty lock directory and retry.
 
 ## Evidence and findings
 
-The packet currently admits up to 16 participants, 800 evidence items, 40 PNG
+Each request's packet admits up to 16 participants, 800 evidence items, 40 PNG
 captures, 160 KiB of text and 20 MiB of images. Individual source files, image
 dimensions and result sizes have separate limits. Count and text budgets are
 distributed across included participants, with unused capacity from short

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

@@ -87,20 +87,20 @@ Right most of the time, overridable with declared friction (an explicit config f
 env gate, a warning in the run output). Overriding a default is a supported use case;
 silently drifting from one is not.
 
-| Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Dry-run                                     | Spend safety (the live-spend rule sets the floor; dry-run keeps it far away)                                                                                                                                                                                        | `mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 cap on its expected cost is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `route: shared-world`: N participants against one mutable plane for scenarios that are about interaction between participants. Every participant runs at once: `execution.concurrency` must be two or more, and an omitted value fills to the number of participants. The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
-| External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| 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)                                                                                                                                                                                                                                                                                                                                                 |
-| 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                                                                                                                                                                                                                       |
-| Generous wall-clock safety cap              | `execution.timeoutMs` bounds runaway spend, not a goal; ~30 min is reasonable for open-ended "watch it play"                                                                                                                                                        | A session that reaches the cap after productive activity is recorded as `budget_reached` (status `passed`, a non-failure completion, exit `0`), distinct from a zero-progress `timed_out` (a failure, exit `2`). Goal-directed studies set a tight `timeoutMs` and read `completionReason` to confirm the goal, not the cap                                                                                                                                                                                                                                                                                                                                                                                |
+| Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dry-run                                     | Spend safety (the live-spend rule sets the floor; dry-run keeps it far away)                                                                                                                                                                                        | `mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 cap on its expected cost is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `route: shared-world`: N participants against one mutable plane for scenarios that are about interaction between participants. Participants run at once, as many as `execution.concurrency` (two or more) and the E2B plan's limit allow, unless the study declares when each one starts (`participants[].startAfterMs`). The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
+| External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| 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, 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                                                                                                                                                                                                                                                                           |
+| Generous wall-clock safety cap              | `execution.timeoutMs` bounds runaway spend, not a goal; ~30 min is reasonable for open-ended "watch it play"                                                                                                                                                        | A session that reaches the cap after productive activity is recorded as `budget_reached` (status `passed`, a non-failure completion, exit `0`), distinct from a zero-progress `timed_out` (a failure, exit `2`). Goal-directed studies set a tight `timeoutMs` and read `completionReason` to confirm the goal, not the cap                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 ## The placement rule (worked example)
 

package/docs/product/automatic-analysis.md

@@ -23,12 +23,19 @@ 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. A study of more than 16 participants is
+analysed in cohorts of at most 16, one request each, and one more request merges their reports;
+the range covers every request and the analysis line names them (see
+[runs with more than 16 participants](../contracts/study-analysis.md#runs-with-more-than-16-participants)).
+The default $3 cap refuses the analysis of 17 participants even for a run that keeps no evidence,
+so a default analysis of more than 16 participants is skipped with
+`AUTOMATIC_ANALYSIS_ADMISSION_REFUSED` unless `review.analysis.maxCostUsd` admits it. 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.117.0",
+  "version": "0.119.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",