humanish 0.144.0 → 0.146.0

package/dist/routes/terminal/live-sandbox.js

@@ -15,7 +15,7 @@ import { loadModalShellModule } from "../../substrates/modal/sandbox.js";
 import { e2bAccount } from "../../substrates/e2b/connection.js";
 import { E2BDesktopStartupError, loadE2BDesktopModule, } from "../../substrates/e2b/sdk.js";
 import { shellQuote } from "../../substrates/shell.js";
-import { buildOpenAiEgressNetwork } from "./runtime-auth.js";
+import { holdKeysInEgress } from "../../substrates/e2b/egress-keys.js";
 import { TERMINAL_RUNTIME_VERSION_TIMEOUT_MS, buildRuntimeExecPrefix, buildRuntimeVersionCommand, parseTerminalRuntimeVersion, } from "./runtime.js";
 import { runWithWallClock, teardownSandbox } from "./sandbox.js";
 import { DEFAULT_REQUEST_TIMEOUT_MS, PRODUCT_SETUP_TIMEOUT_MS, SANDBOX_WORKDIR, UPLOAD_MAX_BYTES, } from "./types.js";
@@ -73,7 +73,7 @@ export class LiveTerminalSandbox {
             ? undefined
             : { allowOut: [...egressAllow], denyOut: ["0.0.0.0/0"] };
         const network = runtimeEnv.mode === "openai-egress"
-            ? buildOpenAiEgressNetwork(runtimeEnv.keyValue, routing)
+            ? holdKeysInEgress({ OPENAI_API_KEY: runtimeEnv.keyValue }, { existing: routing }).network
             : routing;
         const options = {
             apiKey: e2bApiKey,

package/dist/routes/terminal/runtime-auth.d.ts

@@ -1,18 +1,6 @@
 import type { StudyRuntimeAuth } from "../../study/types.js";
-import type { E2BNetworkOptions } from "../../substrates/e2b/sdk.js";
 /**
  * The runtime auth a study gets when it declares none. A shell agent can read its own command env,
  * so the raw key stays in the host-side E2B request unless a study declares openai-env.
  */
 export declare const DEFAULT_RUNTIME_AUTH: StudyRuntimeAuth;
-/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
-export declare const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
-/** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */
-export declare const OPENAI_EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
-/**
- * Keep the runtime key in the host-side E2B request, outside sandbox env/files. The installed
- * E2B SDK declares that transform headers override existing request headers. This adds no routing
- * restrictions: every sandbox process can still spend via the provider proxy. Never log the
- * returned options. An adopter's existing exact-host rule must not be silently overwritten.
- */
-export declare function buildOpenAiEgressNetwork(keyValue: string, existing?: E2BNetworkOptions): E2BNetworkOptions;

package/dist/routes/terminal/runtime-auth.js

@@ -3,26 +3,3 @@
  * so the raw key stays in the host-side E2B request unless a study declares openai-env.
  */
 export const DEFAULT_RUNTIME_AUTH = "openai-egress";
-const OPENAI_EGRESS_HOST = "api.openai.com";
-/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
-export const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
-/** An inert nonsecret value satisfies Codex exec's auth prerequisite. E2B replaces the header. */
-export const OPENAI_EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
-/**
- * Keep the runtime key in the host-side E2B request, outside sandbox env/files. The installed
- * E2B SDK declares that transform headers override existing request headers. This adds no routing
- * restrictions: every sandbox process can still spend via the provider proxy. Never log the
- * returned options. An adopter's existing exact-host rule must not be silently overwritten.
- */
-export function buildOpenAiEgressNetwork(keyValue, existing) {
-    if (Object.keys(existing?.rules ?? {}).some((host) => host.toLowerCase().replace(/\.$/, "") === OPENAI_EGRESS_HOST)) {
-        throw new Error("openai-egress conflicts with an existing api.openai.com network rule; refusing to overwrite it.");
-    }
-    return {
-        ...existing,
-        rules: {
-            ...existing?.rules,
-            [OPENAI_EGRESS_HOST]: [{ transform: { headers: { Authorization: `Bearer ${keyValue}` } } }],
-        },
-    };
-}

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/dist/substrates/e2b/egress-keys.d.ts

@@ -0,0 +1,22 @@
+import type { E2BNetworkOptions } from "./sdk.js";
+/** An inert nonsecret value that satisfies a client's "key is set" check. E2B replaces the header. */
+export declare const EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
+/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
+export declare const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
+/**
+ * Hold every key in `keys` that travels as a header to a fixed host in an E2B header transform on
+ * `existing`, and give the env a placeholder for it. Other names pass through unchanged. The
+ * installed E2B SDK declares that transform headers override the request's own. The returned
+ * network carries the key values: never log or persist it. E2B's sandbox info endpoint returns
+ * the transforms as given, so a process that can call the E2B API for this sandbox can read them.
+ * An existing rule for a held key's host is refused, never overwritten.
+ */
+export declare function holdKeysInEgress(keys: Readonly<Record<string, string>>, options?: {
+    /** The account's E2B_DOMAIN; the E2B API host is `api.<domain>`. */
+    domain?: string | undefined;
+    existing?: E2BNetworkOptions | undefined;
+}): {
+    network: E2BNetworkOptions;
+    env: Record<string, string>;
+    held: string[];
+};

package/dist/substrates/e2b/egress-keys.js

@@ -0,0 +1,59 @@
+/** An inert nonsecret value that satisfies a client's "key is set" check. E2B replaces the header. */
+export const EGRESS_PLACEHOLDER = "humanish-egress-auth-placeholder";
+/** E2B envd installs the sandbox-specific proxy CA into this system bundle before routing. */
+export const E2B_SYSTEM_CA_BUNDLE = "/etc/ssl/certs/ca-certificates.crt";
+const GEMINI = {
+    host: "generativelanguage.googleapis.com",
+    header: "x-goog-api-key",
+    value: (key) => key,
+};
+/**
+ * Where each key name humanish sends as a header goes. Every host is fixed in the code that calls
+ * it: src/actors/openai-endpoint.ts, src/analysis/gemini-wire.ts, and the E2B SDK's
+ * `https://api.<E2B_DOMAIN>` with its `X-API-KEY` header.
+ */
+function headerKey(name, domain) {
+    if (name === "OPENAI_API_KEY")
+        return { host: "api.openai.com", header: "Authorization", value: (key) => `Bearer ${key}` };
+    if (name === "GEMINI_API_KEY" || name === "GOOGLE_API_KEY")
+        return GEMINI;
+    if (name === "E2B_API_KEY")
+        return { host: `api.${domain}`, header: "X-API-Key", value: (key) => key };
+    return undefined;
+}
+const sameHost = (a, b) => a.toLowerCase().replace(/\.$/, "") === b.toLowerCase().replace(/\.$/, "");
+/**
+ * Hold every key in `keys` that travels as a header to a fixed host in an E2B header transform on
+ * `existing`, and give the env a placeholder for it. Other names pass through unchanged. The
+ * installed E2B SDK declares that transform headers override the request's own. The returned
+ * network carries the key values: never log or persist it. E2B's sandbox info endpoint returns
+ * the transforms as given, so a process that can call the E2B API for this sandbox can read them.
+ * An existing rule for a held key's host is refused, never overwritten.
+ */
+export function holdKeysInEgress(keys, options = {}) {
+    const { existing } = options;
+    const domain = options.domain?.trim() || "e2b.app";
+    const rules = {};
+    const env = {};
+    const held = [];
+    for (const [name, value] of Object.entries(keys)) {
+        const placed = headerKey(name, domain);
+        if (placed === undefined) {
+            env[name] = value;
+            continue;
+        }
+        const taken = [...Object.keys(existing?.rules ?? {}), ...Object.keys(rules)].some((host) => sameHost(host, placed.host));
+        if (taken)
+            throw new Error(`${name} would be held in a header transform on ${placed.host}, which already has a network rule; refusing to overwrite it.`);
+        rules[placed.host] = [{ transform: { headers: { [placed.header]: placed.value(value) } } }];
+        env[name] = EGRESS_PLACEHOLDER;
+        held.push(name);
+    }
+    if (held.length === 0)
+        return { network: { ...existing }, env, held };
+    return {
+        network: { ...existing, rules: { ...existing?.rules, ...rules } },
+        env,
+        held: held.sort(),
+    };
+}

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
@@ -461,6 +514,19 @@ that screen is a strong design finding. Validation is unchanged. A design findin
 least one cited capture, so an impression plus the capture of its screen makes a design finding,
 and an impression alone supports only a finding about what the participant said.
 
+## Participant statement citations
+
+An observation with basis `participant_statement` must cite at least one quote-eligible entry
+(`analysis_validation_failed_statement_source_invalid` otherwise). It may also cite captures or
+actions, as an `action` observation may cite more than its one required action. The prompt still
+asks for statements that cite only quote-eligible entries; validation accepts an analyst that adds
+the capture the participant spoke about. Validation does not check that the observation's wording
+matches the quote. Entries of kind `reasoning` are quote-eligible, so a claim drawn from a
+participant's private reasoning also passes as a statement. Before this rule, any non-quote
+citation failed the whole analysis, which caused nearly all `gpt-6-luna` rejections on the
+2026-10-22 benchmark recordings
+([participant statements that cite captures](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/benchmark/2026-10-22-statement-rule.md)).
+
 ## Durable records
 
 The `humanish.observer-data.v3` schema is unchanged by analysis. A companion

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.144.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:"

package/skills/humanish/SKILL.md

@@ -560,7 +560,8 @@ SIGTERM stops the run: humanish marks it interrupted and stops its sandboxes.
   If its terminal closes, the command exits 129 with `HUMANISH_REMOTE_DETACHED` and the run goes
   on; `observe --run <id>` copies it back. `--local` keeps one run on this machine,
   `execution.remote: false` every run of a study. The JSON result's `remote.keys` names the keys
-  the runner received.
+  the run used. On E2B the OpenAI, Gemini and E2B keys stay in E2B's egress proxy and the runner
+  holds placeholders; a Modal runner receives them as environment variables.
 - Start a study that can outlive your shell call in tmux, for example
   `tmux new -d -s study 'npx humanish run <study> --json --no-open > run-result.json 2> run.log'`.
   `--detach` only skips the Observer server at the end; it does not move the run to the background.