humanish 0.115.0 → 0.117.0

package/dist/verify/artifacts.d.ts

@@ -2,6 +2,11 @@ import { type PreparedRunArtifactPaths } from "../run/paths.js";
 import type { RunBundle } from "../run/bundle.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export declare const MAX_REPORTED_FINDINGS = 50;
+/**
+ * The most entries, files and directories, the public-safety scan visits in one run. Bundle export
+ * 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;
 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.
@@ -44,8 +49,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), or cannot read at
- * all, goes to `unscanned`, so the caller can keep the run from grading share_ready.
+ * 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.
  */
 export declare function scanRunPublicSafetyArtifacts(runPaths: PreparedRunArtifactPaths, derivedFindings: string[], media: RegisteredStreamMedia, unscanned: string[]): Promise<string[]>;
 export {};

package/dist/verify/artifacts.js

@@ -6,15 +6,20 @@ import { scanEncodedTextCached } from "../evidence/encoded-text.js";
 import { readPlainText } from "../evidence/plain-text.js";
 import { containsSensitive } from "../evidence/redaction.js";
 import { isLocalEvidenceArtifactPath, isRiskyPublicArtifactPath, validatePreparedRunArtifactPaths, } from "../run/paths.js";
-import { openContainedRegularFile } from "../run/contained-output.js";
+import { openContainedRegularFile, RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
 import { holdsKeyedSandboxId } from "../run/sandbox-ids.js";
 import { SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
-import { readSafeRunArtifactBytes, readSafeRunArtifactJson } from "../run/locate.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 { isZeroEventTerminalTrace } from "./actor.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export const MAX_REPORTED_FINDINGS = 50;
+/**
+ * The most entries, files and directories, the public-safety scan visits in one run. Bundle export
+ * 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;
 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();
@@ -97,13 +102,18 @@ export async function missingLocalEvidenceArtifacts(runPaths, bundle) {
             }
             continue;
         }
-        const bytes = await readSafeRunArtifactBytes(runPaths, artifactPath);
-        if (!bytes || (bytes.length === 0 && !requirements.allowEmpty)) {
+        const artifact = await readSafeRunArtifact(runPaths, artifactPath);
+        if (artifact.state === "limit") {
+            missing.push(`${artifactPath} (larger than the ${RUN_ARTIFACT_MAX_BYTES} bytes verify reads)`);
+            continue;
+        }
+        if (artifact.state === "unavailable" ||
+            (artifact.bytes.length === 0 && !requirements.allowEmpty)) {
             missing.push(artifactPath);
             continue;
         }
         if (requirements.screenshot) {
-            const imageError = screenshotEvidenceError(artifactPath, bytes);
+            const imageError = screenshotEvidenceError(artifactPath, artifact.bytes);
             if (imageError) {
                 missing.push(`${artifactPath} (${imageError})`);
             }
@@ -280,17 +290,21 @@ 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), or cannot read at
- * all, goes to `unscanned`, so the caller can keep the run from grading share_ready.
+ * 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.
  */
 export async function scanRunPublicSafetyArtifacts(runPaths, derivedFindings, media, unscanned) {
     const findings = [];
     await validatePreparedRunArtifactPaths(runPaths);
-    await scanRunPublicSafetyDirectory(runPaths, "", findings, derivedFindings, media, unscanned);
+    await scanRunPublicSafetyDirectory(runPaths, "", findings, derivedFindings, media, unscanned, {
+        entries: 0,
+    });
     await validatePreparedRunArtifactPaths(runPaths);
     return findings;
 }
-async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, findings, derivedFindings, media, unscanned) {
+async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, findings, derivedFindings, media, unscanned, walk) {
     // Each authority has its own finding budget. Derived files must never consume
     // the source scan's budget and make an unscanned recording appear verified.
     if (findings.length >= MAX_REPORTED_FINDINGS && derivedFindings.length >= MAX_REPORTED_FINDINGS) {
@@ -299,8 +313,18 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
     const current = relativeDirectory
         ? path.join(runPaths.physicalRunRoot, ...relativeDirectory.split("/"))
         : runPaths.physicalRunRoot;
-    const entries = await readdir(current).catch(() => []);
+    const entries = await readdir(current).catch(() => null);
+    if (entries === null) {
+        unscanned.push(`${relativeDirectory || "."}/ (could not be listed)`);
+        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)`);
+            return;
+        }
         const relativePath = relativeDirectory ? `${relativeDirectory}/${entryName}` : entryName;
         const stats = await lstat(path.join(current, entryName), { bigint: true }).catch(() => null);
         const selectedFindings = !stats?.isDirectory() &&
@@ -328,7 +352,7 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
         if (stats.isDirectory()) {
             // A directory named analysis.json is not an owned record. Its children
             // can contain source evidence even after derived findings are saturated.
-            await scanRunPublicSafetyDirectory(runPaths, relativePath, findings, derivedFindings, media, unscanned);
+            await scanRunPublicSafetyDirectory(runPaths, relativePath, findings, derivedFindings, media, unscanned, walk);
             continue;
         }
         if (selectedFindings.length >= MAX_REPORTED_FINDINGS)
@@ -342,8 +366,8 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
         if (media.recordingPaths.has(relativePath) || media.screenshotPaths.has(relativePath)) {
             continue;
         }
-        // The scan reads a file by its bytes, not its name. A file that is not text, or that could
-        // not be read at all, holds bytes the scan never saw.
+        // The scan reads a file by its bytes, not its name. A file that is not text, that could not
+        // be read, or that is over the read limit holds bytes the scan never saw.
         const bytes = await readSafeRunArtifactBytes(runPaths, relativePath).catch(() => null);
         const decoded = bytes === null ? undefined : readPlainText(bytes);
         if (decoded === undefined || !decoded.ok) {

package/dist/verify/liveness.js

@@ -4,7 +4,8 @@
 // `ok: true` is not read as "the run finished" or "its sandboxes stopped". It never flips `ok`.
 import { sandboxIdDigest } from "../evidence/redaction.js";
 import path from "node:path";
-import { readRunJsonIfExists, readRunTextIfExists } from "../run/locate.js";
+import { refusalText } from "../run/contained-output.js";
+import { readRunJsonIfExists, readRunTextIfExists, runJsonValue } from "../run/locate.js";
 import { isRecord } from "../run/type-guards.js";
 import { RECLAIM_RECEIPT_ARTIFACT } from "../run/reclaim.js";
 import { runLiveness } from "../run/liveness.js";
@@ -22,7 +23,8 @@ const GONE_STATES = new Set(["killed", "already-gone"]);
  */
 export async function runNotFinished(runPaths, bundle, nowMs = Date.now()) {
     const runId = path.basename(runPaths.absoluteRunRoot);
-    const status = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    // A status.json it refuses is no usable status, as a missing one is: the bundle decides.
+    const status = runJsonValue(await readRunJsonIfExists(runPaths, RUN_STATUS_FILE));
     const { liveness, record } = runLiveness(runId, status, bundle, nowMs);
     if (liveness === "finished")
         return { warnings: [] };
@@ -56,11 +58,23 @@ export async function runNotFinished(runPaths, bundle, nowMs = Date.now()) {
 /** What the reclaim receipt says about this run's sandboxes, and what to run. */
 async function reclaimState(runPaths, runId) {
     const journal = await readRunTextIfExists(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
+    const command = `\`${cli(`reclaim --run ${runId}`)}\``;
+    // A journal it cannot read hides which sandboxes the run made, so no receipt can cover them.
+    if (journal.status === "refused")
+        return {
+            sandboxes: "unconfirmed",
+            text: `Sandboxes unconfirmed: ${refusalText(SANDBOX_RECEIPTS_ARTIFACT, journal)}, so the sandboxes it journaled are not known; check the file, then run ${command}.`,
+        };
     // Matched by digest: a reclaim receipt names each sandbox by digest, and one written before it
     // did holds the raw id, which is digested here.
-    const journaled = new Set((journal === null ? [] : parseSandboxReceipts(journal)).map((receipt) => sandboxIdDigest(receipt.sandboxId)));
-    const command = `\`${cli(`reclaim --run ${runId}`)}\``;
-    const receipt = reclaimReceipt(await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT), runId);
+    const journaled = new Set((journal.status === "missing" ? [] : parseSandboxReceipts(journal.text)).map((receipt) => sandboxIdDigest(receipt.sandboxId)));
+    const receiptRead = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+    if (receiptRead.status === "refused")
+        return {
+            sandboxes: "unknown",
+            text: `Sandboxes unknown: ${refusalText(RECLAIM_RECEIPT_ARTIFACT, receiptRead)}, and the run journaled ${plural(journaled.size, "sandbox", "sandboxes")}; check the file, then run ${command}.`,
+        };
+    const receipt = reclaimReceipt(runJsonValue(receiptRead), runId);
     if (receipt === undefined)
         return {
             sandboxes: "unknown",

package/dist/verify/verify.js

@@ -6,8 +6,10 @@ import { containsSensitive, REDACTED_SANDBOX_ID } from "../evidence/redaction.js
 import { keyedSandboxIds, readRunSandboxIds } from "../run/sandbox-ids.js";
 import { validatePreparedRunArtifactPaths } from "../run/paths.js";
 import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA } from "../run/bundle.js";
+import { ContainedReadRefusedError, refusalText } from "../run/contained-output.js";
 import { isCleanupResult, isRunBundle } from "../run/bundle-shape.js";
-import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath } from "../run/locate.js";
+import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath, runJsonValue, } from "../run/locate.js";
+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";
@@ -75,26 +77,34 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         };
     }
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
-    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
-    const cleanupJson = await readRunJsonIfExists(runPaths, "cleanup.json");
-    const reviewJson = await readRunJsonIfExists(runPaths, "review.json");
-    const reviewMarkdown = await readRunTextIfExists(runPaths, "review.md");
-    checks.push(...bundlePresenceChecks(bundle, {
-        json: reviewJson !== null,
-        markdown: reviewMarkdown !== null,
-    }));
+    const bundleRead = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const bundle = runJsonValue(bundleRead);
+    const cleanupRead = await readRunJsonIfExists(runPaths, "cleanup.json");
+    const review = {
+        json: await readRunJsonIfExists(runPaths, "review.json"),
+        markdown: await readRunTextIfExists(runPaths, "review.md"),
+    };
+    checks.push(...bundlePresenceChecks(bundleRead, review));
     const derivedPublicSafetyFindings = [];
     const unscannedArtifacts = [];
     const sandboxIdFiles = [];
+    let journaledSandboxIds = [];
+    try {
+        journaledSandboxIds = await readRunSandboxIds(runPaths);
+    }
+    catch (error) {
+        if (!(error instanceof ContainedReadRefusedError))
+            throw error;
+        // Without the journal's ids, verify cannot clear any file of naming one.
+        unscannedArtifacts.push(SANDBOX_RECEIPTS_ARTIFACT);
+    }
     const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
         recordingPaths: new Set(isRunBundle(bundle)
             ? bundle.streams.flatMap((stream) => (stream.recording ? [stream.recording.path] : []))
             : []),
         screenshotPaths: isRunBundle(bundle) ? streamScreenshotPaths(bundle) : new Set(),
         // A run from before 0.110 with no receipts still names its ids in run.json.
-        sandboxIds: [
-            ...new Set([...(await readRunSandboxIds(runPaths)), ...keyedSandboxIds(bundle)]),
-        ],
+        sandboxIds: [...new Set([...journaledSandboxIds, ...keyedSandboxIds(bundle)])],
         sandboxIdFiles,
     }, unscannedArtifacts);
     // JSON escapes can hide a sensitive value from the byte scan while the
@@ -129,7 +139,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
                 ? `invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`
                 : `missing local evidence artifacts: ${missingEvidenceArtifacts.join(", ")}`,
     });
-    checks.push(...(await evidenceChecks(runPaths, bundle, cleanupJson)));
+    checks.push(...(await evidenceChecks(runPaths, bundle, cleanupRead)));
     const recordingOk = checks.every((check) => check.ok);
     if (derivedPublicSafetyFindings.length > 0)
         checks.push({
@@ -219,7 +229,8 @@ const REQUIRED_SECTIONS = [
  * Whether run.json, its schema, shape and redaction, and the review artifacts are present. Each
  * check says what it found, so a failing row never prints the rule it enforces.
  */
-function bundlePresenceChecks(bundle, review) {
+function bundlePresenceChecks(bundleRead, review) {
+    const bundle = runJsonValue(bundleRead);
     const record = isRecord(bundle) ? bundle : undefined;
     const schema = record?.schema;
     const schemaOk = schema === RUN_BUNDLE_SCHEMA;
@@ -227,14 +238,26 @@ function bundlePresenceChecks(bundle, review) {
     const redaction = isRecord(redactionRecord) ? redactionRecord.status : undefined;
     const missingSections = REQUIRED_SECTIONS.filter((key) => record?.[key] === undefined);
     const missingReview = [
-        ...(review.json ? [] : ["review.json is missing or not valid JSON"]),
-        ...(review.markdown ? [] : ["review.md is missing"]),
+        ...(review.json.status === "refused"
+            ? [refusalText("review.json", review.json)]
+            : runJsonValue(review.json) === null
+                ? ["review.json is missing or not valid JSON"]
+                : []),
+        ...(review.markdown.status === "refused"
+            ? [refusalText("review.md", review.markdown)]
+            : review.markdown.status === "missing"
+                ? ["review.md is missing"]
+                : []),
     ];
     return [
         {
             name: "run.json exists",
             ok: bundle !== null,
-            message: bundle === null ? "run.json is missing or not valid JSON" : "run.json is present",
+            message: bundleRead.status === "refused"
+                ? refusalText(RUN_BUNDLE_FILE, bundleRead)
+                : bundle === null
+                    ? "run.json is missing or not valid JSON"
+                    : "run.json is present",
         },
         {
             name: "run schema",
@@ -310,7 +333,8 @@ function findingsCheck(name, findings, okMessage, failLabel) {
  */
 const SHAPE_UNCHECKED = "not checked, because run.json failed the shape check";
 /** The bundle-content checks, in report order. A bundle that fails its shape guard has no findings. */
-async function evidenceChecks(runPaths, bundle, cleanupJson) {
+async function evidenceChecks(runPaths, bundle, cleanupRead) {
+    const cleanupJson = runJsonValue(cleanupRead);
     const valid = isRunBundle(bundle) ? bundle : null;
     const pass = (message) => (valid ? message : SHAPE_UNCHECKED);
     const checks = [
@@ -322,14 +346,17 @@ async function evidenceChecks(runPaths, bundle, cleanupJson) {
         findingsCheck("shared-world evidence", valid ? sharedWorldEvidenceFindings(valid) : [], pass("live shared-world evidence is well formed for its mode, with single-plane provenance, digest-only checkpoints and attributionLimits, or the run has none"), "shared-world findings"),
         {
             name: "cleanup receipt",
-            ok: cleanupJson === null || (isCleanupResult(cleanupJson) && cleanupJson.ok),
-            message: cleanupJson === null
-                ? "no cleanup.json; cleanup was not requested"
-                : !isCleanupResult(cleanupJson)
-                    ? "cleanup.json is malformed"
-                    : cleanupJson.ok
-                        ? "cleanup.json records a successful cleanup"
-                        : "cleanup.json records a failed cleanup",
+            ok: cleanupRead.status !== "refused" &&
+                (cleanupJson === null || (isCleanupResult(cleanupJson) && cleanupJson.ok)),
+            message: cleanupRead.status === "refused"
+                ? `${refusalText("cleanup.json", cleanupRead)}, so verify cannot say how cleanup went`
+                : cleanupJson === null
+                    ? "no cleanup.json; cleanup was not requested"
+                    : !isCleanupResult(cleanupJson)
+                        ? "cleanup.json is malformed"
+                        : cleanupJson.ok
+                            ? "cleanup.json records a successful cleanup"
+                            : "cleanup.json records a failed cleanup",
         },
         findingsCheck("rerun lineage", valid ? rerunLineageFindings(valid) : [], pass("rerun participants link to their prior status and a fan-out rerun event, or this run is not a rerun"), "rerun lineage findings"),
         // Cost is advisory on magnitude and fail-closed on labeling/provenance (claims match mechanism).
@@ -371,7 +398,7 @@ function buildShareSafety(args) {
         });
     }
     if (args.unscannedArtifacts.length > 0) {
-        const paths = [...args.unscannedArtifacts].sort();
+        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({

package/docs/architecture/browser-control.md

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

package/docs/architecture/guest-desktop.md

@@ -18,8 +18,13 @@ Progress detection uses the same coarse frame signature as the hosted desktop.
 The actor receives the existing finite action union. Native tool paths, display,
 Xauthority and guest temporary directory come from the owner. Key names map to a
 closed list before reaching xdotool, whose own command syntax must never receive
-arbitrary participant strings. A native wheel step is not an exact pixel-scroll
-promise; one action permits at most 100 wheel steps. The entire drag is checked
+arbitrary participant strings. The list is `src/guest/desktop-keys.ts`, and the hosted
+E2B desktop translates through it too, so a key name works on both desktops or is
+refused on both. It holds OpenAI's computer-use key names, the names `@e2b/desktop`'s
+`press()` mapped, and every printable ASCII punctuation character as its keysym
+(`?` is `question`). A refused name reaches the participant as a rejected action.
+A native wheel step is not an exact pixel-scroll promise; one action permits at most
+100 wheel steps. The entire drag is checked
 before its first input. A pointer action's held keys must be modifiers (Shift,
 Ctrl, Alt, Super). They go down with one `keydown` before the action and up with
 one `keyup` after it. When an input fails, the `keyup` is still sent once, unless

package/docs/architecture/state-driven-executor.md

@@ -75,10 +75,12 @@ graphically dense (pixel-art) UI. `stableProgressKey(appState)`:
 ## A single desktop command failure is a recoverable skipped action
 
 `execute(action)` runs against a real substrate, and the real `@e2b/desktop`
-Sandbox **throws** `CommandExitError` on **any** non-zero exit. A `press`,
+Sandbox **throws** `CommandExitError` on **any** non-zero exit. A keypress,
 `scroll`, `drag`, `moveMouse`, or `click` can exit non-zero for reasons that have
 nothing to do with the run's health (a `Ctrl+Minus` zoom keypress exiting `2` was
-the reproduced case). The loop treats one such failure as a **recoverable skipped
+the reproduced case). xdotool also skips a key name it cannot resolve with a `No such
+key name` warning and exits `0`; the E2B executor turns that warning into an error with
+exit code `0` and xdotool's stderr. The loop treats one such failure as a **recoverable skipped
 action**, not a fatal error:
 
 - The per-action `execute()` call is wrapped at the loop boundary, in `runActionBatch`

package/docs/contracts/run-bundle.md

@@ -305,14 +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 three sources (`clone`, `app-url`,
-`local-tree`), and the `humanish verify` checks that guard it are the schema doc's
+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
 [`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), and `app-url` carries
-no code pin at all. No path, basename, or other host-machine string ever
-enters this field; identity is digests, a sha, a boolean, and counts.
+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
+enters this field; identity is digests, a sha, a boolean, counts and the declared product name.
 
 ## Cost Estimate (advisory)
 
@@ -723,11 +725,17 @@ a file for secret and path patterns only when the bytes are strict UTF-8 with no
 control bytes other than tab, line feed and carriage return, the rule bundle
 export uses for text. `RAW_SCREENSHOTS` and `CONTINUOUS_MEDIA` grade the stream
 screenshots that actor traces reference under `screenshots/`, where the harness
-writes every frame, and the recordings `streams[].recording` registers. Every other file the scan cannot read as text, or cannot read at all,
-contributes `UNSCANNED_ARTIFACT`. The reason's message lists the paths, and it keeps
-otherwise valid evidence `local_only`. This includes images that only feedback
-candidates, adapter artifacts or stream artifact entries cite, and a PNG an actor
-trace references outside `screenshots/`. An unregistered
+writes every frame, and the recordings `streams[].recording` registers. Every
+other file the scan cannot read as text, cannot read at all, or that is larger
+than 32 MiB (verify reads at most that much of one file) contributes
+`UNSCANNED_ARTIFACT`. So does a folder the scan cannot list, and the rest of a
+run past its first 10,000 files and folders, the most `export --format bundle`
+takes. The reason's message lists the paths, and it keeps otherwise valid
+evidence `local_only`. This includes images that only feedback candidates,
+adapter artifacts or stream artifact entries cite, and a PNG an actor trace
+references outside `screenshots/`. An adapter artifact larger than 32 MiB grades
+the run `local_only` when nothing cites it, and `blocked` when the bundle cites
+it as evidence, because the evidence check cannot read it. An unregistered
 `.mp4`, and a file or directory whose name contains `\`, are public-safety
 findings and block the run.
 

package/docs/contracts/schemas.md

@@ -76,17 +76,17 @@ map each one to its v3 key.
 A study declares its route and composes code primitives; it is not a hardcoded kind. The
 top-level keys:
 
-| Key                                                               | Meaning                                                                                                                                            |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schema`, `id`, `title`, `description`                            | the document's identity                                                                                                                            |
-| `route`                                                           | required: `preview`, `computer-use`, `shared-world`, `terminal` or `scripted`                                                                      |
-| `mode`                                                            | `dry-run` (the default) or `live`                                                                                                                  |
-| `actor`                                                           | who drives it, one object: `type`, `model`, `localAgent`, `persona`, `mission`, `tasks`, `maxOutputTokens`, `reasoningEffort`, `stopWhen`, `dwell` |
-| `participants`                                                    | a count, a homogeneous `{ count, instruction }`, or a list of entries (below)                                                                      |
-| `surfaces`                                                        | scripted only: `[desktop]` or `[desktop, mobile]`                                                                                                  |
-| `caps`                                                            | the route's budget (below)                                                                                                                         |
-| `scenario`                                                        | scripted only: a committed scenario id or path                                                                                                     |
-| `subject`, `execution`, `policies`, `review`, `defaults`, `comms` | as below                                                                                                                                           |
+| Key                                                               | Meaning                                                                                                                                                                       |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`, `id`, `title`, `description`                            | the document's identity                                                                                                                                                       |
+| `route`                                                           | required: `preview`, `computer-use`, `shared-world`, `terminal` or `scripted`                                                                                                 |
+| `mode`                                                            | `dry-run` (the default) or `live`                                                                                                                                             |
+| `actor`                                                           | who drives it, one object: `type`, `model`, `localAgent`, `persona`, `mission`, `tasks`, `maxOutputTokens`, `maxWaitMs`, `idleWaitMs`, `reasoningEffort`, `stopWhen`, `dwell` |
+| `participants`                                                    | a count, a homogeneous `{ count, instruction }`, or a list of entries (below)                                                                                                 |
+| `surfaces`                                                        | scripted only: `[desktop]` or `[desktop, mobile]`                                                                                                                             |
+| `caps`                                                            | the route's budget (below)                                                                                                                                                    |
+| `scenario`                                                        | scripted only: a committed scenario id or path                                                                                                                                |
+| `subject`, `execution`, `policies`, `review`, `defaults`, `comms` | as below                                                                                                                                                                      |
 
 The parser reads only the declared route's keys. A key that route never reads is an error that
 names the route, such as "route: computer-use does not read scenario. Remove it.", and an
@@ -317,9 +317,9 @@ The rest of this section names keys by their v3 spelling:
   fail-closed cap in force. `maxMinutes` is the
   wall-clock kill; `maxUsd`/`maxJobs` are enforced fail-closed against the cost
   ledger after the session (a run whose known spend exceeds the cap fails closed,
-  `HUMANISH_TERMINAL_CAPS_EXCEEDED`). Core records Codex provider spend as
-  unpriced tokens and measures no product, media or payment spend, so no line can trip a
-  positive `maxUsd`: a live run refuses `maxUsd > 0` before creating a sandbox
+  `HUMANISH_TERMINAL_CAPS_EXCEEDED`). Core prices the Codex participant's tokens as an
+  estimate that the cap does not count, and measures no product, media or payment spend, so no
+  line can trip a positive `maxUsd`: a live run refuses `maxUsd > 0` before creating a sandbox
   (`HUMANISH_TERMINAL_UNPRICED_CAP`). A terminal `maxUsd` cap has no adopter cost source
   until [issue 347](https://github.com/danielgwilson/humanish/issues/347) lands;
   `StudyDeps.costProbe` is a test seam. The sandbox's server-side timeout is the steps before the
@@ -529,8 +529,8 @@ 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, repo?, commit?, archiveSha256?,
-  dirty?, envNames?, state }` where `state` is `{ provenance: seeded |
+  `{ source: clone | app-url | local-tree | desktop-cli, 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?
   }`. Emitted by the computer-use and shared-world routes and the clone
@@ -538,7 +538,10 @@ Core-owned fields:
   (64-hex sha256, the local-tree provenance pin) and `dirty` (host git
   porcelain status at pack time) are local-tree-route fields, additive under
   `humanish.run-bundle.v1`: a dirty working tree cannot be commit-pinned, so
-  the archive content digest stands in for it. `commandDigest` is the
+  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
   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
@@ -982,6 +985,14 @@ Core-owned fields:
   “provider reply cut off by the output limit; asking again” notice. A second
   cut-off reply to the same request ends the session with
   `stopCause: provider_output_limit`.
+- optional `waitSettings`: the wait lengths a computer-use participant's session
+  applied, in milliseconds, defaults included. `maxWaitMs` is the longest one
+  wait action lasts (`actor.maxWaitMs`); a longer wait is shortened to it.
+  `idleWaitMs` is how long a wait that names no duration lasts in a turn that
+  only waits or takes screenshots (`actor.idleWaitMs`), and `settleWaitMs` how
+  long such a wait lasts after an action in the same turn. Each `ui_action` for
+  a wait is titled with the length it lasted. Absent on other routes and on
+  earlier bundles
 - optional `conversation`: how the first-party OpenAI computer-use provider
   carried the conversation between requests. `mode` is `threaded` (the server
   kept it through `previous_response_id`) or `explicit_context` (the server kept
@@ -1142,15 +1153,20 @@ discipline** that distinguishes three states and never conflates them:
 
 `knownTotalUsd` sums only the non-null lines (a `null` line contributes nothing
 and is never coerced to `0`); `fullyMeasured` is true only when no line is null.
-Core meters only the `provider` line, populated from the actor trace's
-`tokenUsage.costUsd` when present (else `null`); `product`/`media`/`payment`
+Core meters only the `provider` line, from the actor trace's `tokenUsage.costUsd` when present
+(the Codex usage records the terminal route reads carry none today); `product`/`media`/`payment`
 remain `null`, because no adopter can supply those signals until
-[issue 347](https://github.com/danielgwilson/humanish/issues/347) lands. The terminal route records the model as `codex` and does not pin Codex's
-model, so a measured token count stays `usd: null` with `source: unpriced-token-usage`, and
-`knownTotalUsd: 0` with `fullyMeasured: false` means no line of this ledger was priced. E2B
-time for the terminal sandbox is not a line of this ledger, whose lines are checked against
-`caps.maxUsd`. The run bundle's `cost` summary prices it as a `desktop-minutes`
-line (see Run Cost Summary And Estimated Actor Cost below).
+[issue 347](https://github.com/danielgwilson/humanish/issues/347) lands. Without a measured
+charge the `provider` line keeps `usd: null` and counts the participant's tokens. The route
+passes Codex a model and prices the tokens once from it (the actor trace's `estimatedCost`); the
+line carries that price as `estimatedUsd` with `source: estimated-token-usage`, the same figure as
+the run bundle's `model-tokens` cost line. The estimate is not part of `knownTotalUsd`, so
+`caps.maxUsd` and the no-spend proof do not count it. Tokens of a model with no rate stay
+`source: unpriced-token-usage` with the model named in the note, and a run whose output had no
+usage record has `source: unmeasured`. `knownTotalUsd: 0` with `fullyMeasured: false` means no
+line of this ledger was measured. E2B time for the terminal sandbox is not a line of this ledger,
+whose lines are checked against `caps.maxUsd`. The run bundle's `cost` summary prices it as a
+`desktop-minutes` line (see Run Cost Summary And Estimated Actor Cost below).
 
 ```yaml
 schema: humanish.terminal-cost-ledger.v1
@@ -1159,7 +1175,8 @@ lines:
   product: { usd: null, count: null, source: unmeasured, note: "…no signal yet…" }
   media: { usd: null, count: null, source: unmeasured, note: "…no signal yet…" }
   payment: { usd: null, count: null, source: unmeasured, note: "…no signal yet…" }
-  provider: { usd: null, source: unmeasured, note: "…no tokenUsage.costUsd this run…" }
+  provider:
+    { usd: null, estimatedUsd: 0.37157, source: estimated-token-usage, note: "…estimated at…" }
 knownTotalUsd: 0
 fullyMeasured: false
 ```
@@ -1171,9 +1188,9 @@ it explicitly cannot vouch for). `satisfied` is true only when every known line
 is within `maxUsd` (for a no-spend run, `maxUsd: 0` ⇒ every known line is `0`).
 Unmeasured lines never break it, so a ledger whose lines are all `null` is
 `satisfied` with nothing proven. The `statement` says which case applies: it
-names the measured lines and their dollars, provider tokens that were counted
-but unpriced (with the counts), and the lines with no signal; when no line was
-measured it says the proof was not established. A proof never claims zero on a
+names the measured lines and their dollars, the provider tokens that were counted
+(with the counts, and their estimate or that they are unpriced), and the lines with
+no signal; when no line was measured it says the proof was not established. A proof never claims zero on a
 `null` line; verification fails closed if it does.
 
 ```yaml

package/docs/contracts/study-analysis.md

@@ -205,7 +205,16 @@ analysis, and treats an analysis that breaks them as unavailable.
 
 The narrative scrub removes a run's known transient values, such as a received one-time code or
 link, from every generated text field. It finds each value as written and in its encoded forms:
-percent-encoded, JSON-escaped, base64, base64url and hex, and where escapes split it. A field
+percent-encoded, JSON-escaped, base64, base64url and hex, and where escapes split it. Base64 and
+hex forms are searched from 6 characters. A value of 4 bytes, such as the code `7439`, is found
+in base64 written whole (`NzQzOQ` or `NzQzOQ==`) and not inside a longer base64 run, where 4 or 5
+characters of its encoding do not depend on the bytes around it;
+`tests/evidence/secret-scrub.test.ts` records the case. The cost of the short forms is
+over-redaction: an identifier that holds a short value's base64 loses that part, as
+`aMTIzNAz` becomes `a[REDACTED_SECRET]z` while the code `1234` (`MTIzNA`) is registered, since a
+match cannot tell whether the identifier came from the value. In the text of 9 real runs, no 6-
+or 7-character form of any 4-, 5- or 6-digit code occurred. Run evidence is scrubbed for the same
+forms. A field
 with a value is stored decoded with the value replaced; a field without one keeps its spelling. A
 value inside a bracketed span, such as `[REDACTED_373433393231]`, is found too: only the markers
 humanish writes (`[REDACTED_SECRET]`, `[REDACTED_LOCAL_PATH]`, `[REDACTED_RUNTIME_PATH]`,

package/docs/product/automatic-analysis.md

@@ -102,7 +102,9 @@ accepted. Known usage is retained; missing usage remains unknown.
 
 The CLI's JSON keeps `runOk` for the route's own result, `automaticAnalysis`
 for post-run analysis, and `ok` for the overall request. Failed, cancelled or
-unknown analysis produces exit code 2 without discarding the recording. A missing
+unknown analysis produces exit code 2 without discarding the recording. When the
+run's own result is ok, the first line of the human output reads
+`humanish run <study>: live run finished; the analysis did not complete`. A missing
 `OPENAI_API_KEY` skips default analysis and preserves a successful run exit;
 `automaticAnalysisTrigger: "default"` distinguishes that case in JSON. So does a
 default analysis whose expected cost, plus the margin, is over the default $3 cap:
@@ -144,5 +146,9 @@ outcomes and the deterministic review verdict are never rewritten by analysis.
 | `AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE` | `unknown`                 | A cancellation could not be recorded                                  |
 | `AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN`          | `unknown`                 | The outcome could not be determined                                   |
 
+A run refused before it was created (`run: not-created`) prints no `analysis:` line, since there
+is no run to analyze and the refusal says why. Its JSON keeps the record, with
+`AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE`, or `AUTOMATIC_ANALYSIS_DRY_RUN` for a dry run.
+
 See the [analysis contract](../contracts/study-analysis.md) for selection limits,
 evidence validation, actual usage, corrections and share-safe export behavior.