humanish 0.133.0 → 0.134.0

package/dist/run/stream-trace.d.ts

@@ -11,10 +11,16 @@ export declare class StreamTraceRefusedError extends Error {
     constructor(streamId: string, detail: string, advice?: string);
 }
 /**
- * A trace or live file whose index records more than the loader reads of one file. The loader reads
- * no file past the limit, so a copy of the file is refused too.
+ * A trace or live file whose index records more than the loader reads of one file, `maxBytes`. The
+ * loader reads no file past the limit, so a copy of the file is refused too.
  */
 export declare class StreamTraceTooLargeError extends StreamTraceRefusedError {
+    /** The file's run-relative path, as its index records it. */
+    readonly file: string;
+    constructor(streamId: string, index: {
+        path: string;
+        bytes: number;
+    }, maxBytes: number);
 }
 /** `trace` without the per-request lists; every other field as it is. */
 export declare function withoutRequestLists<T extends object>(trace: T): WithoutRequestLists<T>;

package/dist/run/stream-trace.js

@@ -28,13 +28,17 @@ export class StreamTraceRefusedError extends Error {
 /** Why the loader reads no trace or live file whose index records more than `maxBytes`. */
 const pastLimitDetail = (index, maxBytes) => `run.json records ${index.path} at ${index.bytes} bytes, more than the ${maxBytes} bytes humanish reads of one file`;
 /**
- * A trace or live file whose index records more than the loader reads of one file. The loader reads
- * no file past the limit, so a copy of the file is refused too.
+ * A trace or live file whose index records more than the loader reads of one file, `maxBytes`. The
+ * loader reads no file past the limit, so a copy of the file is refused too.
  */
 export class StreamTraceTooLargeError extends StreamTraceRefusedError {
+    /** The file's run-relative path, as its index records it. */
+    file;
+    constructor(streamId, index, maxBytes) {
+        super(streamId, pastLimitDetail(index, maxBytes), "Restoring a copy does not help; open the file with another tool, such as jq, to read its items.");
+        this.file = index.path;
+    }
 }
-/** The refusal of a trace or live file whose index records more than `maxBytes`. */
-const tooLarge = (streamId, index, maxBytes) => new StreamTraceTooLargeError(streamId, pastLimitDetail(index, maxBytes), "Restoring a copy does not help; open the file with another tool, such as jq, to read its items.");
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 const isScreenshot = (artifact) => artifact.kind === "screenshot";
 /**
@@ -139,7 +143,9 @@ export function splitStreamTraces(bundle) {
             throw new Error(`Two participants' traces would both be written to ${filePath}.`);
         claimed.add(traceFileKey(filePath));
         const screenshots = stream.artifacts.filter(isScreenshot);
-        const bytes = Buffer.from(`${JSON.stringify({ ...actor, artifacts: screenshots }, null, 2)}\n`);
+        // Compact: every reader refuses a file past RUN_ARTIFACT_MAX_BYTES, and indenting made a
+        // trace 1.36 times its compact size on 236 recorded computer-use traces.
+        const bytes = Buffer.from(`${JSON.stringify({ ...actor, artifacts: screenshots })}\n`);
         files.push({ path: filePath, bytes });
         const { items, ...summary } = actor;
         return {
@@ -274,7 +280,7 @@ async function readLiveItems(read, stream, maxBytes, liveAfter) {
     const after = liveAfter?.(index);
     if (index.bytes > maxBytes) {
         if (after === undefined || !cursorFits(index, after))
-            throw tooLarge(stream.id, index, maxBytes);
+            throw new StreamTraceTooLargeError(stream.id, index, maxBytes);
         // The caller keeps the prefix it holds, read when the file was under the limit.
         return {
             stream: { ...stream, liveActor: { ...summary, items: [] } },
@@ -343,7 +349,7 @@ async function readStreamTrace(read, stream, maxBytes, liveAfter) {
     if (stream.trace !== undefined) {
         assertIndex(stream);
         if (stream.trace.bytes > maxBytes)
-            throw tooLarge(stream.id, stream.trace, maxBytes);
+            throw new StreamTraceTooLargeError(stream.id, stream.trace, maxBytes);
         const file = await read(stream.trace.path, maxBytes);
         if ("refused" in file)
             throw new StreamTraceRefusedError(stream.id, file.refused);

package/dist/study/bundle-estimate.d.ts

@@ -16,10 +16,7 @@ export interface BundleEstimate {
     readonly runFileBytes: number;
     /** The largest participant trace file, which analysis also reads whole. */
     readonly largestTraceBytes: number;
-    /**
-     * Every participant's trace file together, whose items the run writer and the Observer page join
-     * in one string.
-     */
+    /** Every participant's trace file together, whose items the Observer page joins in one string. */
     readonly tracesBytes: number;
     /** observer/index.html, which verify reads whole. */
     readonly observerPageBytes: number;

package/dist/study/bundle-estimate.js

@@ -17,11 +17,11 @@
 // runs measured, so it passes 32 MiB only after run.json passes 16 MiB, and the estimate does not
 // check it.
 // The Observer page and the Observer server join every participant's items in one string before
-// gzip. On a hosted desktop the sandbox id scrub (publicSandboxView) does too, on every write of
-// run.json and on a bundle export of the loaded run, which its 25 MiB default --max-bytes refuses
-// first. V8's longest string is 536,870,888 characters
-// on Node 24. A trace file's bytes are at least the characters of its items as compact JSON, so the
-// estimate compares the traces' bytes and may warn a little early.
+// gzip. A bundle export renders the Observer page, so it fails there too once --max-bytes is
+// raised past its 25 MiB default, which refuses such a run first. Writing run.json joins none: the
+// sandbox id scrub (publicSandboxView) works one participant at a time. V8's longest string is
+// 536,870,888 characters on Node 24. A trace file's bytes are at least the characters of its
+// items as compact JSON, so the estimate compares the traces' bytes and may warn a little early.
 import { constants } from "node:buffer";
 import { EVIDENCE_LIMITS } from "../analysis/analysis-limits.js";
 import { RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
@@ -32,9 +32,15 @@ import { runEntryLimit } from "../verify/scan-limit.js";
 // the 0.125.0 smoke test and the 2026-10-12 live checks, 10 participants with 1 to 28 turns and 137
 // model requests. Dry: runs of 1, 2, 24 and 100 participants, for the Observer app and the run's
 // own files. Pace, session length and screenshots: the live computer-use runs kept on the
-// maintainer's machine. A trace's rate a turn on the public site/public/runs/lobby-0927 run
-// (8 participants, 20 to 78 turns) was 1,579 bytes plus 91 for the page, under the live fit.
-// The run.json and page data rates were measured again on those runs written as v4.
+// maintainer's machine. The run.json and page data rates were measured again on those runs
+// written as v4.
+// The trace rates were measured on trace files written indented. The writer now writes them as
+// compact JSON, so each trace rate below is the indented figure divided by 1.36, the ratio of
+// indented to compact bytes over 236 kept computer-use traces (1.17 to 1.49 each), and the page's
+// share of the traces is multiplied by it. A trace's rate a turn on the public
+// site/public/runs/lobby-0927 run (8 participants, 20 to 78 turns) was 1,579 bytes plus 91 for the
+// page indented, under the live fit. Its participant of 78 turns writes a trace of 149,637 bytes
+// indented and 107,897 compact.
 const RATES = Object.freeze({
     /** run.json bytes for the run itself: its header, study, review and cost. Live fit: 4,381. */
     runBytes: 4_400,
@@ -44,21 +50,21 @@ const RATES = Object.freeze({
      * bytes and those of two 30,647 to 38,948, beside 20,900 and 37,400 at these rates.
      */
     participantBytes: 16_500,
-    /** A trace file's bytes before its turns: the actor summary. Live fit: 5,378. */
-    participantTraceBytes: 5_400,
+    /** A trace file's bytes before its turns: the actor summary. Live fit: 5,378 indented. */
+    participantTraceBytes: 4_000,
     /**
      * Trace bytes a model turn adds: its items, its screenshot entry and its request's usage, plus 91
-     * for the `page` each screenshot item now carries. Live fit: 1,965 a turn. Participants with 4
-     * or more turns ranged from 1,140 to 4,532; the busiest made 311 items in 15 turns, most of them
-     * UI actions. Analysis refuses the whole run when one trace passes its limit, so each trace is
-     * counted at the busiest participant's rate.
+     * for the `page` each screenshot item now carries, all indented. Live fit: 1,965 a turn.
+     * Participants with 4 or more turns ranged from 1,140 to 4,532; the busiest made 311 items in 15
+     * turns, most of them UI actions. Analysis refuses the whole run when one trace passes its limit,
+     * so each trace is counted at the busiest participant's rate, 4,700 indented.
      */
-    turnTraceBytes: 4_700,
+    turnTraceBytes: 3_500,
     /**
      * Trace bytes a dwell frame adds: 395 for its item and entry on the kept runs with dwell frames,
-     * plus 91 for the page.
+     * plus 91 for the page, indented.
      */
-    frameTraceBytes: 500,
+    frameTraceBytes: 400,
     /**
      * Seconds between model turns: the median of the 27 of 185 kept live participants that worked 5
      * minutes or more was 10.4.
@@ -83,12 +89,12 @@ const RATES = Object.freeze({
      */
     observerPageDataShare: 0.85,
     /**
-     * The page's gzipped base64 items, as a share of all the traces' bytes: 0.087 to 0.114 on the
-     * live runs of two participants, 0.097 for the busiest participant alone (about 475 bytes a
-     * turn), 0.142 to 0.184 on runs of one participant and 4 to 11 turns, and 0.095 on 0.124.0's
-     * synthetic 8-hour run.
+     * The page's gzipped base64 items, as a share of all the traces' bytes indented: 0.087 to 0.114
+     * on the live runs of two participants, 0.097 for the busiest participant alone (about 475 bytes
+     * a turn), 0.142 to 0.184 on runs of one participant and 4 to 11 turns, and 0.095 on 0.124.0's
+     * synthetic 8-hour run. The estimate counted 0.12 of indented traces.
      */
-    observerPageItemsShare: 0.12,
+    observerPageItemsShare: 0.16,
     /** A desktop screenshot: the median of 3,990 kept live PNG frames was 107,895 bytes. */
     screenshotBytes: 110_000,
     /**
@@ -206,7 +212,7 @@ export function bundleLimitReason(estimate) {
             : []),
         ...(joined
             ? [
-                `All participants' traces together may grow to about ${mib(estimate.tracesBytes)}, past the ${mib(constants.MAX_STRING_LENGTH)} that fits in one string. On a hosted desktop, writing run.json puts them in one string, and so does a bundle export allowed past its 25 MiB default; the Observer page always does. run.json may then stop updating, that export would fail and the page would not build.`,
+                `All participants' traces together may grow to about ${mib(estimate.tracesBytes)}, past the ${mib(constants.MAX_STRING_LENGTH)} that fits in one string. The Observer page puts all their items in one string, so the page would not build. A bundle export allowed past its 25 MiB default renders that page, so it would fail too.`,
             ]
             : []),
         ...(entries

package/dist/verify/artifacts.d.ts

@@ -22,7 +22,13 @@ export interface UnscannedArtifacts {
  * and where it stopped, each in its own sentence. Undefined when the scan read everything.
  */
 export declare function unscannedMessage(unscanned: UnscannedArtifacts): string | undefined;
-export declare function missingLocalEvidenceArtifacts(runPaths: PreparedRunArtifactPaths, bundle: RunBundle): Promise<string[]>;
+/**
+ * Why each local evidence path the bundle requires is missing or unusable. A path in
+ * `pastReadLimit` is a trace verify found larger than it reads, which verify lists as unscanned so
+ * the run grades local_only. It meets a requirement only while it is still past the limit when
+ * this check reads it, and never a screenshot or recording requirement.
+ */
+export declare function missingLocalEvidenceArtifacts(runPaths: PreparedRunArtifactPaths, bundle: RunBundle, pastReadLimit: ReadonlySet<string>): Promise<string[]>;
 /**
  * The PNG frames that actor traces register as stream screenshots, relative to the run root.
  * RAW_SCREENSHOTS grades these, so the public-safety scan does not report them as unread. Only

package/dist/verify/artifacts.js

@@ -47,7 +47,13 @@ function listed(paths) {
     const more = paths.length - MAX_LISTED_UNSCANNED;
     return `${paths.slice(0, MAX_LISTED_UNSCANNED).join(", ")}${more > 0 ? ` and ${more} more` : ""}`;
 }
-export async function missingLocalEvidenceArtifacts(runPaths, bundle) {
+/**
+ * Why each local evidence path the bundle requires is missing or unusable. A path in
+ * `pastReadLimit` is a trace verify found larger than it reads, which verify lists as unscanned so
+ * the run grades local_only. It meets a requirement only while it is still past the limit when
+ * this check reads it, and never a screenshot or recording requirement.
+ */
+export async function missingLocalEvidenceArtifacts(runPaths, bundle, pastReadLimit) {
     const recordings = new Map(bundle.streams.flatMap((stream) => stream.recording ? [[stream.recording.path, stream.recording]] : []));
     const requiredPaths = new Map();
     const addRequiredPath = (artifactPath, options = {}) => {
@@ -110,12 +116,15 @@ export async function missingLocalEvidenceArtifacts(runPaths, bundle) {
         }
     }
     // Reads overlap, so one frame's file system calls run while another frame's PNG is checked.
-    const found = await mapWithConcurrency([...requiredPaths], EVIDENCE_READ_CONCURRENCY, ([artifactPath, requirements]) => missingArtifact(runPaths, artifactPath, requirements, recordings.get(artifactPath)));
+    const found = await mapWithConcurrency([...requiredPaths], EVIDENCE_READ_CONCURRENCY, ([artifactPath, requirements]) => missingArtifact(runPaths, artifactPath, { ...requirements, pastReadLimit: pastReadLimit.has(artifactPath) }, recordings.get(artifactPath)));
     return found.filter((entry) => entry !== null);
 }
 // Evidence files verify reads at once. Each read holds at most RUN_ARTIFACT_MAX_BYTES.
 const EVIDENCE_READ_CONCURRENCY = 8;
-/** Why one required path fails its requirements, or null when it meets them. */
+/**
+ * Why one required path fails its requirements, or null when it meets them. `pastReadLimit` says
+ * verify listed the path as a trace past the read limit, so a file still past it is present.
+ */
 async function missingArtifact(runPaths, artifactPath, requirements, recording) {
     if (recording) {
         const handle = await openContainedRegularFile(runPaths, artifactPath);
@@ -136,7 +145,9 @@ async function missingArtifact(runPaths, artifactPath, requirements, recording)
         ? await readScreenshot(runPaths, artifactPath)
         : await readSafeRunArtifact(runPaths, artifactPath);
     if (read.state === "limit")
-        return `${artifactPath} (larger than the ${RUN_ARTIFACT_MAX_BYTES} bytes verify reads)`;
+        return requirements.pastReadLimit && !requirements.screenshot
+            ? null
+            : `${artifactPath} (larger than the ${RUN_ARTIFACT_MAX_BYTES} bytes verify reads)`;
     if (read.state === "unavailable" ||
         (("size" in read ? read.size : read.bytes.length) === 0 && !requirements.allowEmpty))
         return artifactPath;

package/dist/verify/verify.js

@@ -7,9 +7,9 @@ import { containsSensitiveJson } from "../evidence/sensitive-json.js";
 import { keyedSandboxIds, readRunSandboxIds } from "../run/sandbox-ids.js";
 import { validatePreparedRunArtifactPaths } from "../run/paths.js";
 import { isReadRunBundleSchema, RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, RUN_BUNDLE_V2_SCHEMA, RUN_BUNDLE_V3_SCHEMA, } from "../run/bundle.js";
-import { ContainedReadRefusedError, refusalText } from "../run/contained-output.js";
+import { ContainedReadRefusedError, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "../run/contained-output.js";
 import { isCleanupResult, isRunBundle } from "../run/bundle-shape.js";
-import { loadStreamTraces } from "../run/stream-trace.js";
+import { loadStreamTraces, StreamTraceTooLargeError } from "../run/stream-trace.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";
@@ -79,7 +79,8 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
     const bundleRead = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
     // Every check below reads the streams with their traces loaded; a trace that does not match its
-    // index fails the evidence-artifacts check and its stream is checked without its items.
+    // index fails the evidence-artifacts check, and its stream, like one past the read limit, is
+    // checked without its items.
     const traces = await loadTraces(runPaths, runJsonValue(bundleRead));
     const { bundle, recorded, refusedTraces } = traces;
     const cleanupRead = await readRunJsonIfExists(runPaths, "cleanup.json");
@@ -102,9 +103,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         unscannedArtifacts.files.push(SANDBOX_RECEIPTS_ARTIFACT);
     }
     const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
-        recordingPaths: new Set(bundle
-            ? bundle.streams.flatMap((stream) => (stream.recording ? [stream.recording.path] : []))
-            : []),
+        recordingPaths: recordingPaths(bundle),
         screenshotPaths: bundle ? streamScreenshotPaths(bundle) : new Set(),
         // A run from before 0.110 with no receipts still names its ids in run.json.
         sandboxIds: [...new Set([...journaledSandboxIds, ...keyedSandboxIds(recorded)])],
@@ -127,7 +126,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
             : `public-safety findings: ${publicSafetyFindings.slice(0, 5).join(", ")}`,
     });
     const missingEvidenceArtifacts = bundle
-        ? await missingLocalEvidenceArtifacts(runPaths, bundle)
+        ? await missingLocalEvidenceArtifacts(runPaths, bundle, traces.pastReadLimit)
         : [];
     const redactedShapeFrames = bundle
         ? await redactedShapeFramePaths(runPaths, bundle)
@@ -155,6 +154,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         : { warnings: [], unfinished: undefined };
     const warnings = bundle
         ? [
+            ...traces.unreadTraces,
             ...rawScreenshotPostureWarnings(bundle, redactedShapeFrames),
             ...undeclaredSubjectStateWarnings(bundle),
             ...desktopGeometryWarnings(bundle),
@@ -238,6 +238,8 @@ async function loadTraces(runPaths, stored) {
             recorded: stored,
             refusedTraces: [],
             refusedStreams: new Set(),
+            unreadTraces: [],
+            pastReadLimit: new Set(),
             ...scanned,
             pages: [],
         };
@@ -250,15 +252,34 @@ async function loadTraces(runPaths, stored) {
                 scanned[scan === "sensitive" ? "sensitive" : "opaque"].push(file);
         },
     });
+    // A file whose index records more than the read limit is not read. One past the limit on disk
+    // too is listed as unscanned, so its run grades local_only; one under it does not match its index.
+    const unread = [];
+    for (const error of refused)
+        if (error instanceof StreamTraceTooLargeError && (await pastReadLimit(runPaths, error.file))) {
+            unread.push(error);
+            scanned.opaque.push(error.file);
+        }
     return {
         bundle,
         recorded: bundle,
-        refusedTraces: refused.map((error) => error.message),
+        refusedTraces: refused
+            .filter((error) => !unread.some((past) => past === error))
+            .map((error) => error.message),
         refusedStreams: new Set(refused.map((error) => error.streamId)),
+        unreadTraces: unread.map((error) => error.message),
+        pastReadLimit: new Set(unread.map((error) => error.file)),
         ...scanned,
         pages: pageFindings(bundle),
     };
 }
+/** Whether the run file at `file` holds more than RUN_ARTIFACT_MAX_BYTES, read only when it does not. */
+async function pastReadLimit(runPaths, file) {
+    const read = await readContainedRegularFile(runPaths, file, RUN_ARTIFACT_MAX_BYTES);
+    return read.status === "refused" && read.reason === "too-large";
+}
+/** The continuous recordings the bundle registers, which CONTINUOUS_MEDIA grades. */
+const recordingPaths = (bundle) => new Set(bundle?.streams.flatMap((stream) => (stream.recording ? [stream.recording.path] : [])) ?? []);
 /** The trace scan's results, beside the walk's: each file named once, then each page finding. */
 function addTraceScan(traces, findings, unscanned) {
     for (const file of traces.sensitive)

package/docs/architecture/actor-contract.md

@@ -168,7 +168,9 @@ export interface ActorTraceItem {
   screenshotRef?: { path: string; redaction: "blurred" | "ocr_scrubbed" | "none" };
   text?: string; // redacted
   page?: { origin: string; path: string }; // computer-use screenshot items; redacted, no query
-  // computer-use: the wait ui_action during which a watch of a turn that only waited ended
+  // computer-use: the wait ui_action during which a watch of a turn that only waited ended, or a
+  // "watched the screen" notice for a watch no wait carries (a held participant's turn of only
+  // screenshots, or the watch after its repeated action past the no-progress limit)
   watch?: {
     limitMs: number;
     askedMs: number; // what the turn's waits asked for; above limitMs past the watch's growth cap

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

@@ -100,10 +100,13 @@ action**, not a fatal error:
   `budget_reached` after material progress), a `CuaAbortError` as `harness_error`,
   and any genuine non-`CommandExitError` adapter fault as `actor_error`.
 - **No infinite loop.** A skipped action changes nothing on screen, so it is not
-  progress. A run that keeps failing every action makes no progress and still
-  terminates through the existing idle / no-progress backstop
-  (`gave_up`). The resilience only converts a _single flaky command_ from fatal
-  to survivable; it never masks a genuinely stuck run.
+  progress. A run that keeps repeating a failing action makes no progress and
+  ends through the no-progress backstop (`gave_up`) at 20 such turns in a row.
+  A participant held to its scheduled end keeps its session through repeats on
+  an unchanged screen, which is how it waits on a page that changes only on
+  reload, but 20 repeats in a row that never reached the desktop end it the
+  same way. The resilience only converts a _single flaky command_ from fatal
+  to survivable.
 
 Public-safety: the notice text carries only the substrate's own stderr (tailed +
 whitespace-collapsed) and a numeric exit code, and is still run through the loop's

package/docs/contracts/run-bundle.md

@@ -20,7 +20,7 @@ writer (`src/run/run.ts`, through `splitStreamTraces` in `src/run/stream-trace.t
 each stream with an `actor`:
 
 - the trace file: the actor trace (`humanish.actor-trace.v1`) with every item, plus `artifacts`,
-  the stream's screenshot entries. Its path is the stream's actor trace artifact (`actor.json` for
+  the stream's screenshot entries, as one line of compact JSON. Its path is the stream's actor trace artifact (`actor.json` for
   one participant, `actors/<stream>.json` for more, `actor-<surface>.json` on the scripted route),
   or `actors/<n>.json`, `n` its position in `streams[]` (from 1), for a stream with none or whose
   trace artifact an earlier stream claimed. Names of that form are never reused as a stream's own
@@ -65,7 +65,12 @@ names, is refused before any file is read. The writer claims names the same way.
 must have an index: an actor with no index, with
 or without inline `items`, is refused, and so is one with both an index and inline `items`.
 verify reports a refused trace in the `local evidence artifacts exist` check, so the run is
-`blocked`. verify also scans the bytes of each trace it loaded with the public-safety text scan,
+`blocked`. A trace or live file whose index records more than the limit is reported that way too,
+unless the file on disk is a single-link regular file verify can open that holds more than 32 MiB.
+verify lists such a file under `UNSCANNED_ARTIFACT`, so the run is `local_only`. It adds the
+refusal to its warnings and checks that participant without its items. Where the run cites the
+file as evidence, verify counts it as present if it is still past 32 MiB when that check reads it;
+a citation as a screenshot or recording is still checked as one, so the run is `blocked`. verify also scans the bytes of each trace it loaded with the public-safety text scan,
 apart from its walk of the run folder, so no path exemption the walk makes applies to a trace.
 run.json's digest, which an analysis record binds, covers each index and so each trace.
 
@@ -371,6 +376,12 @@ An Observer that does not render is an `evidence` failure known only after
 show the run without it. Messages pass the same redaction and sandbox id scrub
 as the rest of the bundle.
 
+After that write, `Run.finish` replaces each raw sandbox id `sandbox-receipts.ndjson` names in the
+run's other text files with its label (`scrubRunSandboxIds` in `src/run/sandbox-ids.ts`). A file
+the sweep cannot read, such as a trace past the 32 MiB read limit, may still name a sandbox. The run
+still finishes: `Run.finish` writes `run.json` again with a `sandbox-ids.unresolved` warn event that
+names each such file and why.
+
 When a signal stops a live run, the handler writes `interrupted` into the last
 flushed `run.json`, and every later write of that run keeps it. A run stopped
 before its first flush has no `run.json`; its `status.json` is the record.

package/docs/contracts/study-analysis.md

@@ -194,8 +194,10 @@ item's text. A run.json past 16 MiB is refused as `ANALYSIS_SOURCE_TOO_LARGE`, a
 a run.json or trace without the fields analysis reads as `ANALYSIS_SOURCE_INVALID`;
 each message names the file, says why, and says no request was sent. Analysis
 verifies the run before it reads a trace, so a trace that does not match its
-index in run.json, or whose index records more than 32 MiB, fails verify and
-`humanish analyze` reports `ANALYSIS_VERIFY_FAILED`. Count and text budgets are
+index in run.json fails verify and `humanish analyze` reports
+`ANALYSIS_VERIFY_FAILED`. A trace past 32 MiB leaves the run `local_only`, and
+analysis refuses it as `ANALYSIS_SOURCE_TOO_LARGE`, naming the participant and
+the file. Count and text budgets are
 distributed across included participants, with unused capacity from short
 sessions available to longer ones. Reclaimed capture slots go first to eligible
 participants with fewer admitted images, including those deferred by their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.133.0",
+  "version": "0.134.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",