humanish 0.145.0 → 0.146.0

package/dist/substrates/e2b/cdp-probe.d.ts

@@ -30,8 +30,11 @@ export interface ChromeCdpProbeArgs {
      * pausing it; it applies `emulation` (how a participant keeps the overrides for its whole life,
      * with a reload on each page) and `network` capture, either or both. "fidelity": read
      * back what the page reports about itself (UA, DPR, viewport, touch), the proof for the bundle.
+     * "load": poll the page until it has loaded and painted, or until `deadlineMs`.
      */
-    mode: "state" | "geometry" | "port" | "emulate" | "hold" | "fidelity";
+    mode: "state" | "geometry" | "port" | "emulate" | "hold" | "fidelity" | "load";
+    /** For "load": how long to poll before reporting the page as not loaded. */
+    deadlineMs?: number;
     /** For "emulate" and "hold": what to apply. */
     emulation?: ChromeMobileEmulationRequest;
     /** For "hold": capture each held page's requests to a sandbox file. */
@@ -41,6 +44,16 @@ export interface ChromeCdpProbeArgs {
 export interface ChromeMobileEmulationRequest extends MobileEmulationRequest {
     platform?: string;
 }
+/**
+ * What the "load" mode saw. `loaded` is true once the page reports document.readyState complete,
+ * is visible and has a first contentful paint. `seen` describes the last read in words that name
+ * no URL.
+ */
+export interface ChromePageLoad {
+    loaded: boolean;
+    waitedMs: number;
+    seen: string;
+}
 /** What the page reports after emulation: the proof, never copied from the request. */
 interface ChromeFidelityRead {
     userAgent: string;
@@ -80,6 +93,8 @@ export interface ChromeCdpProbeResult {
     } | {
         unavailable: string;
     };
+    /** "load": whether the page loaded and painted before the deadline, and what the last read saw. */
+    load?: ChromePageLoad;
     /**
      * Seconds since the epoch on the sandbox clock when the probe printed, on every answer including
      * an unavailable one. It is the clock CDP `wallTime` uses, so a turn mark compares with request

package/dist/substrates/e2b/cdp-probe.js

@@ -213,6 +213,10 @@ GEOMETRY_EXPRESSION = (
     "({ browserWindow: { x: window.screenX, y: window.screenY, width: window.outerWidth, height: window.outerHeight }, "
     "viewport: { width: window.innerWidth, height: window.innerHeight, deviceScaleFactor: window.devicePixelRatio } })"
 )
+LOAD_EXPRESSION = (
+    "({ readyState: document.readyState, visible: document.visibilityState === 'visible', "
+    "painted: performance.getEntriesByType('paint').some(function (entry) { return entry.name === 'first-contentful-paint'; }) })"
+)
 FIDELITY_EXPRESSION = (
     "({ userAgent: navigator.userAgent, devicePixelRatio: window.devicePixelRatio, "
     "innerWidth: window.innerWidth, innerHeight: window.innerHeight, "
@@ -405,6 +409,50 @@ def follow_targets(ws, launch_id, request, log):
         if params.get("waitingForDebugger"):
             ws.send("Runtime.runIfWaitingForDebugger", {}, new_session)
 
+def page_ws_url(port, page):
+    # Chrome omits webSocketDebuggerUrl from /json while another DevTools client is attached to the
+    # page, or for a moment after one detaches; the page socket URL is still /devtools/page/<id>.
+    return page.get("webSocketDebuggerUrl") or (
+        "ws://127.0.0.1:%d/devtools/page/%s" % (port, page.get("id")) if page.get("id") else None
+    )
+
+def wait_for_load(port, args):
+    """Poll the page until document.readyState is complete, the page is visible and Chrome has
+    recorded its first contentful paint: the page has loaded and something of it is drawn. Stops at
+    deadlineMs and reports what the last read saw."""
+    started = time.monotonic()
+    deadline_ms = int(args.get("deadlineMs") or 0)
+    seen = "no http page yet"
+    page = None
+    loaded = False
+    while True:
+        try:
+            page = select_page(list_pages(port), args)
+            seen = "no http page yet" if page is None else seen
+        except Exception as error:
+            page, seen = None, "the DevTools endpoint did not answer (%s)" % type(error).__name__
+        ws_url = page_ws_url(port, page) if page is not None else None
+        state = evaluate(ws_url, LOAD_EXPRESSION) if ws_url else None
+        if isinstance(state, dict):
+            ready = str(state.get("readyState") or "unknown")
+            seen = "document.readyState %s, %s, %s" % (
+                ready,
+                "visible" if state.get("visible") else "hidden",
+                "first contentful paint recorded" if state.get("painted") else "no first contentful paint yet",
+            )
+            loaded = ready == "complete" and bool(state.get("visible")) and bool(state.get("painted"))
+            if loaded:
+                break
+        elif ws_url:
+            seen = "the page did not answer Runtime.evaluate"
+        if (time.monotonic() - started) * 1000 >= deadline_ms:
+            break
+        time.sleep(0.25)
+    answer = {"load": {"loaded": loaded, "waitedMs": int((time.monotonic() - started) * 1000), "seen": seen}}
+    if page is not None:
+        answer["targetId"] = str(page.get("id") or "")
+    emit(answer)
+
 def emit(answer):
     """Print one answer line stamped with this sandbox's clock. CDP wallTime uses the same clock, so
     a turn mark taken from it compares with request times without host skew, and the reading needs
@@ -419,6 +467,9 @@ def main():
     if mode == "port":
         emit({"cdpPort": port})
         return
+    if mode == "load":
+        wait_for_load(port, args)
+        return
     try:
         pages = list_pages(port)
     except Exception as error:
@@ -441,11 +492,7 @@ def main():
     if page is None:
         emit({"unavailable": "no http page among %d CDP targets on 127.0.0.1:%d" % (len(pages), port)})
         return
-    # Chrome omits webSocketDebuggerUrl from /json while another DevTools client is attached to the
-    # page, or for a moment after one detaches; the page socket URL is still /devtools/page/<id>.
-    ws_url = page.get("webSocketDebuggerUrl") or (
-        "ws://127.0.0.1:%d/devtools/page/%s" % (port, page.get("id")) if page.get("id") else None
-    )
+    ws_url = page_ws_url(port, page)
     if mode == "emulate":
         applied, failure = emulate(ws_url, args.get("emulation") or {}) if ws_url else (None, "the page has no socket")
         if failure is not None:
@@ -502,6 +549,8 @@ export function chromeCdpProbeCommand(args) {
         payload.emulation = args.emulation;
     if (args.network !== undefined)
         payload.network = args.network;
+    if (args.deadlineMs !== undefined)
+        payload.deadlineMs = args.deadlineMs;
     return `python3 -c ${shellQuote(CHROME_CDP_PROBE_PY)} ${shellQuote(JSON.stringify(payload))}`;
 }
 /**
@@ -529,6 +578,7 @@ export function parseChromeCdpProbeOutput(stdout) {
     const numberOr = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
     const now = numberOr(record.now);
     const network = networkOf(record.network);
+    const load = loadOf(record.load);
     if (typeof record.unavailable === "string") {
         return {
             unavailable: record.unavailable,
@@ -602,9 +652,21 @@ export function parseChromeCdpProbeOutput(stdout) {
         ...(browserWindow === undefined ? {} : { browserWindow }),
         ...(viewport === undefined ? {} : { viewport }),
         ...(network === undefined ? {} : { network }),
+        ...(load === undefined ? {} : { load }),
         ...(now === undefined ? {} : { now }),
     };
 }
+function loadOf(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const source = value;
+    if (typeof source.loaded !== "boolean" ||
+        typeof source.waitedMs !== "number" ||
+        !Number.isFinite(source.waitedMs) ||
+        typeof source.seen !== "string")
+        return undefined;
+    return { loaded: source.loaded, waitedMs: source.waitedMs, seen: source.seen };
+}
 function networkOf(value) {
     if (!value || typeof value !== "object")
         return undefined;

package/dist/substrates/e2b/desktop-browser.js

@@ -7,8 +7,10 @@ import { runDetachedStep } from "../detached.js";
 import { shellQuote } from "../shell.js";
 import { externalLinkHandlerSetup } from "./desktop-handoff.js";
 import { e2bShell } from "./shell.js";
-// Settle after opening the browser or the terminal, before the first screenshot: long enough for
-// a cold browser and page load to paint (2 s captured a blank desktop; the render needs 6-9 s).
+// The wait before the first screenshot. After a terminal opens, or a browser without a DevTools
+// read, it is a fixed sleep: long enough for a cold browser and page load to paint (2 s captured a
+// blank desktop; the render needs 6-9 s). A Chromium participant waits for its page to load and
+// paint (waitForChromePageLoad) and gives up after this long.
 export const DESKTOP_SETTLE_MS = 8_000;
 /** The DevTools port every Chromium participant launches with; see `chrome_debug_flags` below. */
 export const CHROME_DEVTOOLS_PORT = 9222;

package/dist/substrates/e2b/desktop-cdp.d.ts

@@ -1,5 +1,5 @@
 import type { ChromeNetworkCaptureRequest } from "./cdp-network-capture.js";
-import { type ChromeCdpProbeResult, type ChromeMobileEmulationRequest } from "./cdp-probe.js";
+import { type ChromeCdpProbeResult, type ChromeMobileEmulationRequest, type ChromePageLoad } from "./cdp-probe.js";
 import type { RunDesktopGeometry } from "../../run/streams.js";
 import type { E2BDesktopSandbox } from "./sdk.js";
 /**
@@ -85,6 +85,13 @@ export declare function applyMobileEmulation(desktop: E2BDesktopSandbox, request
     /** The holder's capture status, when `network` was passed and the holder said. */
     network?: ChromeCdpProbeResult["network"];
 }>;
+/**
+ * Wait until the participant's launch page has loaded and painted, read over DevTools in the
+ * sandbox, for at most `deadlineMs`. Resolves with what the wait saw, or undefined when it could
+ * not run (no python3, a failed command, output that is not the probe's), so the caller can fall
+ * back to a fixed wait.
+ */
+export declare function waitForChromePageLoad(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, deadlineMs: number): Promise<ChromePageLoad | undefined>;
 /**
  * Start a holder that records the launch page's requests, and every later tab's, to
  * `network.eventsPath`, for a participant without mobile emulation; applyMobileEmulation passes
@@ -94,7 +101,7 @@ export declare function applyMobileEmulation(desktop: E2BDesktopSandbox, request
 export declare function startNetworkCapture(desktop: E2BDesktopSandbox, requestTimeoutMs: number, endpoint: ChromeCdpEndpoint, network: ChromeNetworkCaptureRequest): Promise<string>;
 /**
  * What the capture holder announced: when capture started on the launch page, on the sandbox
- * clock, or why it did not. Reads the holder's log up to 6 times, half a second apart by
+ * clock, or why it did not. Reads the holder's log up to 22 times, half a second apart by
  * `desktop.wait`, and reports a holder that printed nothing as unavailable.
  */
 export declare function readNetworkCaptureStart(desktop: E2BDesktopSandbox, requestTimeoutMs: number, holderName: string): Promise<NonNullable<ChromeCdpProbeResult["network"]>>;

package/dist/substrates/e2b/desktop-cdp.js

@@ -213,10 +213,32 @@ export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint,
         ...capture,
     };
 }
+/**
+ * Wait until the participant's launch page has loaded and painted, read over DevTools in the
+ * sandbox, for at most `deadlineMs`. Resolves with what the wait saw, or undefined when it could
+ * not run (no python3, a failed command, output that is not the probe's), so the caller can fall
+ * back to a fixed wait.
+ */
+export async function waitForChromePageLoad(desktop, requestTimeoutMs, endpoint, deadlineMs) {
+    const result = await e2bShell(desktop)
+        .run(chromeCdpProbeCommand({ ...endpoint, prefer: "pinned", mode: "load", deadlineMs }), {
+        requestTimeoutMs,
+        // One poll can take 3.5 s past the deadline: a 2 s listing and a 1.5 s evaluate.
+        timeoutMs: deadlineMs + 10_000,
+    })
+        .catch(() => undefined);
+    if (result === undefined || result.exitCode !== 0)
+        return undefined;
+    return parseChromeCdpProbeOutput(result.stdout).load;
+}
 /** The holder stops writing its events file at 32 MiB, so a read stops there too. */
 const NETWORK_EVENTS_MAX_BYTES = 32 * 1024 * 1024;
-/** How many times the capture holder's log is read for its announce, and how far apart. */
-const NETWORK_ANNOUNCE_READS = 6;
+/**
+ * How many times the capture holder's log is read for its announce, and how far apart. The reads
+ * start after the page wait, which can end within a second of the holder's start, so they cover
+ * the 11 s a holder had when a fixed 8 s settle came before 3 s of reads.
+ */
+const NETWORK_ANNOUNCE_READS = 22;
 const NETWORK_ANNOUNCE_EVERY_MS = 500;
 /**
  * Start a holder that records the launch page's requests, and every later tab's, to
@@ -235,7 +257,7 @@ export async function startNetworkCapture(desktop, requestTimeoutMs, endpoint, n
 }
 /**
  * What the capture holder announced: when capture started on the launch page, on the sandbox
- * clock, or why it did not. Reads the holder's log up to 6 times, half a second apart by
+ * clock, or why it did not. Reads the holder's log up to 22 times, half a second apart by
  * `desktop.wait`, and reports a holder that printed nothing as unavailable.
  */
 export async function readNetworkCaptureStart(desktop, requestTimeoutMs, holderName) {
@@ -253,7 +275,7 @@ export async function readNetworkCaptureStart(desktop, requestTimeoutMs, holderN
         });
     }
     return {
-        unavailable: `the in-sandbox holder printed nothing within ${(NETWORK_ANNOUNCE_READS * NETWORK_ANNOUNCE_EVERY_MS) / 1000} s of the desktop settling`,
+        unavailable: `the in-sandbox holder printed nothing within ${(NETWORK_ANNOUNCE_READS * NETWORK_ANNOUNCE_EVERY_MS) / 1000} s of the page wait`,
     };
 }
 /**

package/docs/contracts/schemas.md

@@ -212,7 +212,7 @@ The rest of this section names keys by their v3 spelling:
   browser target; `entry` is a shared-world participant's same-origin path;
 - `participants[].files` (computer-use on `execution.target: e2b-desktop` only):
   1 to 20 `{ from, as }` entries, each a file copied onto that participant's desktop
-  before its browser opens. `from` is relative to the folder that holds the study file
+  before its session starts. `from` is relative to the folder that holds the study file
   (`cwd` for a library config); `as` is relative to the desktop user's home folder.
   The parser refuses an absolute path, a `.`, `..` or empty part, a backslash, an `as`
   that starts with `~`, lands in `subject/` or on a name starting with `.humanish`, looks

package/docs/contracts/study-analysis.md

@@ -27,8 +27,10 @@ cap; a refused dry run says why, and names the `--max-cost` that admits it.
 
 The default provider is `openai`; its default model is `gpt-6.1-sol`, at medium reasoning effort
 ([reasoning effort](#reasoning-effort)). A request sends selected retained text and
-captures to OpenAI, without tools, redirects, provider-side response storage, or
-automatic retries. `--question` adds a reviewer question; it never changes the
+captures to OpenAI, without tools, redirects or provider-side response storage. A request that
+runs out of output is sent once more while the cap admits it
+([a request that runs out of output](#a-request-that-runs-out-of-output)); no other failure is
+sent again. `--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 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.
@@ -60,12 +62,39 @@ 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 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,
-and the saved configuration, digest and automatic job bind the selected allowance.
-This selection never increases the spending limit or starts a retry.
+The default deadline is ten minutes for each request. With no explicit output-token limit,
+`src/analysis/output-limit.ts` sizes the allowance to the packet. An OpenAI analysis at none, low
+or medium effort of up to 16 participants gets 12,288 tokens plus 2,048 per participant, at most
+32,768: 14,336 for one participant and 18,432 for three. A high-effort analysis, a Gemini
+analysis and a run analysed in cohorts get 32,768. If admission refuses an allowance above
+16,384 under the declared budget, the analysis keeps 16,384. Explicit limits are never adjusted.
+Selection happens before dispatch; `admission.outputTokenAllowance` exposes it in dry-run, and
+the saved configuration, digest and automatic job bind the selected allowance. This selection
+never increases the spending limit.
+
+The sizes come from the finished reports on the 2026-10-22 and 2026-10-23 benchmark recordings:
+the Taskly analyses listed in `docs/evidence/benchmark/2026-10-2*.json`, one participant with 8 to
+14 captures, and the movie-game analyses of
+[analysis models on fixed recordings](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/benchmark/2026-10-22-analysis-models.md), three
+participants with 40 to 49 captures. Each analysis's output tokens are read from its retained
+artifact.
+
+| Analyst and effort   | One participant: passed, most output | Three participants: passed, most output |
+| -------------------- | ------------------------------------ | --------------------------------------- |
+| `gpt-6.1-sol` low    | 24, 4,308                            | 6, 6,391                                |
+| `gpt-6.1-sol` medium | 142, 5,659                           | 36, 9,000                               |
+| `gpt-6-luna` medium  | 27, 8,354                            | 2, 11,313                               |
+| `gpt-6.1-sol` high   | 22, 10,086                           | 6, 15,797                               |
+| `gpt-6-luna` high    | 78, 19,880                           | 9, 26,439                               |
+| `gemini-3.8-flash`   | 23, 29,739                           | 1, 26,154                               |
+
+At low and medium effort the sized limit is 1.7 times the most output of a finished report of
+one participant and 1.6 times that of three; for `gpt-6.1-sol` at medium it is 2.5 and 2.0 times.
+At high effort a finished `gpt-6-luna` report of three participants used 26,439 tokens, so 32,768
+has no room to lower. A `gpt-6.1-sol` analysis at medium that ran out of output on a
+one-participant run had used all 32,768 tokens in 374 seconds and cost $0.39; at 14,336 tokens the
+same request stops at 44% of that output.
+
 The configured wall-clock deadline covers the entire request, including waiting
 for response headers and reading the body. A request-scoped dispatcher prevents
 Node's separate fetch timeout from cutting a longer configured deadline short;
@@ -77,6 +106,29 @@ 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.
 
+## A request that runs out of output
+
+When an OpenAI or Gemini request ends with `output_incomplete`, humanish sends the same request
+once more, with a fresh deadline. It does so only when the spend so far, plus what admission
+holds for the attempt's requests still running and admission's figure for one more request (its
+expected cost plus 10%, or its worst case when that is lower), is within `maxCostUsd`. The spend
+so far counts every response of the attempt, the one that ran out included. When a response did
+not report its usage, the spend is unknown and the request is not sent again. A request is sent
+again at most once; when the second one also runs out, the attempt fails with
+`analysis_output_incomplete`. A cohort request and the merge request are each sent again the same
+way. Codex account analysis has no dollar cap to check and is never sent again. A timeout, an HTTP
+error and a rejected report are not sent again: a timed-out request has already used the
+ten-minute deadline.
+
+The attempt keeps one execution start, one receipt and one `analysis.json`. Their `usage` is the
+sum of every response, both requests of a retry included, and `estimatedCostUsd` prices each
+response as its own request. The schemas are unchanged. A warning in `warnings` (and in the human
+output of `analyze` and of a live run, under its `analysis:` line) names the request, the input
+and output tokens and the cost of the response that ran out, and says whether humanish sent it
+again; a refused retry gives the spend, the held amount and the cap. The result is partial with
+`analysis_admission_estimate_exceeded` only when the bill passes admission's worst case plus the
+worst case of each request sent again, or the cap.
+
 ## Runs with more than 16 participants
 
 One analysis covers up to 128 participants, the most streams it reads from a run
@@ -104,7 +156,8 @@ 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
+cohorts: 6,400 evidence items, 320 captures and 16 MiB. A cohort request or the merge request that
+runs out of output is sent once more under the rule above. 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

package/docs/product/automatic-analysis.md

@@ -16,15 +16,17 @@ expected cost and a 600-second timeout. A study or command that names a model bu
 that model at high; only the default analyst, with no model named, runs at medium. On the same
 recordings it matched `gpt-6-astra` at high, the earlier default, at about one seventh of the cost
 ([analysis models on fixed recordings](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/benchmark/2026-10-22-analysis-models.md)). When no output limit is specified,
-humanish selects 32,768 tokens if the exact input's expected cost still fits that
-cap; otherwise it keeps the established 16,384-token allowance. This preserves
-previously admitted studies without increasing their spending limit. To customize it:
+humanish sizes it to the analysis: at low or medium effort, 12,288 tokens plus 2,048 per
+participant (14,336 for one), and 32,768 at high effort, on Gemini and past 16 participants. An
+allowance above 16,384 that the cap would refuse falls back to 16,384, so a study its cap admitted
+before stays admitted ([output limit](../contracts/study-analysis.md#invocation)). A
+request that runs out of output is sent once more while the cap admits it. To customize it:
 
 ```yaml
 review:
   analysis:
     maxCostUsd: 10
-    # Optional overrides. Omit maxOutputTokens for budget-aware selection.
+    # Optional overrides. Omit maxOutputTokens for a limit sized to the analysis.
     # A named model without reasoningEffort runs at high.
     model: gpt-6.1-sol
     reasoningEffort: medium
@@ -57,8 +59,9 @@ effort; on 24 Taskly analyses `gpt-6.1-sol` at medium wrote a mean 3,747 and cos
 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
-includes reasoning as well as the report; exhausting it does not produce a usable
-report and never starts an automatic retry. Analysis
+includes reasoning as well as the report; a request that exhausts it has no usable report. It
+is sent once more when the spend so far and admission's figure for one more request fit the cap,
+and the CLI says so under the analysis line; the attempt's usage counts both requests. Analysis
 sends selected retained text and captures to OpenAI using `OPENAI_API_KEY`, or to Google with
 `provider: gemini`.
 Analysis runs in the humanish runner using its credentials. This setting adds no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.145.0",
+  "version": "0.146.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -120,13 +120,13 @@
     "@types/pngjs": "^6.0.5",
     "axe-core": "4.14.0",
     "fast-check": "catalog:",
-    "knip": "6.41.0",
+    "knip": "6.42.1",
     "modal": "^0.11.1",
     "oxc-parser": "catalog:",
-    "oxfmt": "0.73.0",
-    "oxlint": "1.88.0",
+    "oxfmt": "0.74.0",
+    "oxlint": "1.89.0",
     "oxlint-tsgolint": "7.0.2004",
-    "skills": "1.7.2",
+    "skills": "1.7.4",
     "tsx": "^4.23.15",
     "typescript": "catalog:",
     "vitest": "catalog:"