humanish 0.128.0 → 0.130.0

package/dist/run/stream-trace.js

@@ -13,15 +13,28 @@ import { isLiveItemsIndex, LIVE_ACTOR_SCHEMA, LIVE_ACTOR_V1_SCHEMA, liveItemsAft
 import { estimateActorCostForExecution } from "./pricing.js";
 import { isRunStreamArtifact, isStreamTraceIndex, isStreamTracePath } from "./stream-shape.js";
 import { isRecord } from "./type-guards.js";
-/** A trace that does not match its index, or cannot be read. The message names the stream. */
+/**
+ * A trace that does not match its index, or cannot be read. The message names the stream, and ends
+ * with `advice`: by default, restore the run folder from a copy.
+ */
 export class StreamTraceRefusedError extends Error {
     streamId;
-    constructor(streamId, detail) {
-        super(`Participant ${streamId}'s trace was not read: ${detail}. A trace file must stay as the run wrote it; restore the run folder from a copy.`);
+    constructor(streamId, detail, advice = "A trace file must stay as the run wrote it; restore the run folder from a copy.") {
+        super(`Participant ${streamId}'s trace was not read: ${detail}. ${advice}`);
         this.streamId = streamId;
         this.name = "StreamTraceRefusedError";
     }
 }
+/** 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.
+ */
+export class StreamTraceTooLargeError extends StreamTraceRefusedError {
+}
+/** 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";
 /**
@@ -226,6 +239,13 @@ function assertIndex(stream) {
     if (stream.actor.items !== undefined)
         throw new StreamTraceRefusedError(stream.id, "run.json holds items beside its trace index");
 }
+/**
+ * A stream of run.json typed as a loaded one, for the streams the loader joins no trace into: one
+ * without an index, which v1 wrote with its actor's lists, and a refused one, kept as run.json
+ * holds it. From v4 a refused stream's actor has none of the lists, and its `conversation` lacks
+ * the `requests` ActorTrace declares; the loader's `refused` names each such stream.
+ */
+const unjoined = (stream) => stream;
 /** A live actor whose items run.json holds inline: humanish.live-actor.v1, or one with no schema. */
 const isInlineLiveActor = (live) => live.schema === LIVE_ACTOR_V1_SCHEMA || live.schema === undefined;
 /** A live file that could not be read, which a writer that moved on may have removed. */
@@ -250,10 +270,22 @@ async function readLiveItems(read, stream, maxBytes, liveAfter) {
         return refuse("run.json records a malformed live items index");
     if (live.items !== undefined)
         refuse("run.json holds in-progress items beside their live file");
-    if (index.bytes > maxBytes)
-        refuse(`${index.path} is indexed at ${index.bytes} bytes, more than the ${maxBytes} read`);
     const { itemsFile: _index, ...summary } = live;
     const after = liveAfter?.(index);
+    if (index.bytes > maxBytes) {
+        if (after === undefined || !cursorFits(index, after))
+            throw tooLarge(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: [] } },
+            read: {
+                streamId: stream.id,
+                index,
+                after,
+                stopped: `Participant ${stream.id}'s items past ${after.items} were not read: ${pastLimitDetail(index, maxBytes)}. The items read before stay shown; open the file with another tool, such as jq, to read the rest.`,
+            },
+        };
+    }
     const tail = after === undefined ? undefined : await readLiveTail(read, stream, index, after);
     if (tail !== undefined)
         return {
@@ -274,6 +306,15 @@ async function readLiveItems(read, stream, maxBytes, liveAfter) {
         read: { streamId: stream.id, index },
     };
 }
+/**
+ * Whether `after` can be a prefix of the file `index` describes: some bytes, no more items or bytes
+ * than the index, and at its end in both counts or in neither. Whether it ends on a line end is
+ * checked only when the tail is read.
+ */
+const cursorFits = (index, after) => after.bytes > 0 &&
+    after.items <= index.items &&
+    after.bytes <= index.bytes &&
+    (after.items === index.items) === (after.bytes === index.bytes);
 /**
  * The items of the live file `index` describes past `after`, and the bytes they were read from;
  * undefined when the cursor does not fit the index or the file's lines, so the caller reads the
@@ -281,10 +322,7 @@ async function readLiveItems(read, stream, maxBytes, liveAfter) {
  * LiveFileUnreadableError, as a whole read does.
  */
 async function readLiveTail(read, stream, index, after) {
-    if (after.bytes === 0 ||
-        after.items > index.items ||
-        after.bytes > index.bytes ||
-        (after.items === index.items) !== (after.bytes === index.bytes))
+    if (!cursorFits(index, after))
         return undefined;
     if (after.bytes === index.bytes)
         return { items: [], bytes: Buffer.alloc(0) };
@@ -301,9 +339,11 @@ async function readLiveTail(read, stream, index, after) {
  */
 async function readStreamTrace(read, stream, maxBytes, liveAfter) {
     const files = [];
-    let joined = stream;
+    let joined = unjoined(stream);
     if (stream.trace !== undefined) {
         assertIndex(stream);
+        if (stream.trace.bytes > maxBytes)
+            throw tooLarge(stream.id, stream.trace, maxBytes);
         const file = await read(stream.trace.path, maxBytes);
         if ("refused" in file)
             throw new StreamTraceRefusedError(stream.id, file.refused);
@@ -320,7 +360,8 @@ async function readStreamTrace(read, stream, maxBytes, liveAfter) {
  * stream without an index is returned as it is (a v1 stream, or one with no actor). An indexed
  * stream's file must have a trace file name (isStreamTracePath); it is read under `maxBytes` and
  * checked against the index's byte count, sha256, item count and screenshot count, and any
- * difference throws StreamTraceRefusedError. The rules that need the whole bundle (an unindexed v2
+ * difference throws StreamTraceRefusedError. An index that records more than `maxBytes` throws
+ * before the file is read. The rules that need the whole bundle (an unindexed v2
  * actor, two participants indexing one file) are loadStreamTraces'.
  */
 export async function loadStreamTrace(runPaths, stream, maxBytes = RUN_ARTIFACT_MAX_BYTES) {
@@ -387,7 +428,9 @@ function bundleRefusal(bundle, stream, owners) {
  * `liveAfter` names, for a live file's index, the prefix the caller holds already (the Observer
  * feed's cursor). The loader then reads and joins only the items past it, checked by liveItemsAfter
  * without the indexed sha256, and `live` records the cursor; a cursor past the index or off the
- * file's lines gets the whole prefix, checked as always.
+ * file's lines gets the whole prefix, checked as always. A live file whose index records more than
+ * `maxBytes` is not read: for a cursor that fits the index the stream gets no items past it and
+ * `live` records `stopped`, and without one the stream is refused.
  *
  * A live file that cannot be read may have been removed by the writer after `bundle` was read: it
  * removes a superseded generation once run.json names the next one, and every live file once the
@@ -420,20 +463,25 @@ async function rereadBundle(read, runId) {
         return undefined;
     }
 }
-async function loadEveryStream(read, bundle, maxBytes, liveAfter) {
+/** bundleRefusal for each stream of `bundle`, with the streams that index each file counted once. */
+function bundleRefusals(bundle) {
     const owners = new Map();
     for (const stream of bundle.streams)
         if (isRecord(stream.trace)) {
             const key = traceFileKey(String(stream.trace.path));
             owners.set(key, [...(owners.get(key) ?? []), stream.id]);
         }
+    return (stream) => bundleRefusal(bundle, stream, owners);
+}
+async function loadEveryStream(read, bundle, maxBytes, liveAfter) {
+    const refusal = bundleRefusals(bundle);
     const streams = [];
     const refused = [];
     const files = [];
     const live = [];
     for (const stream of bundle.streams) {
         try {
-            const reason = bundleRefusal(bundle, stream, owners);
+            const reason = refusal(stream);
             if (reason !== undefined)
                 throw new StreamTraceRefusedError(stream.id, reason);
             const loaded = await readStreamTrace(read, stream, maxBytes, liveAfter);
@@ -446,7 +494,7 @@ async function loadEveryStream(read, bundle, maxBytes, liveAfter) {
             if (!(error instanceof StreamTraceRefusedError))
                 throw error;
             refused.push(error);
-            streams.push(stream);
+            streams.push(unjoined(stream));
         }
     }
     return { bundle: { ...bundle, streams }, refused, files, live };
@@ -456,23 +504,25 @@ async function loadEveryStream(read, bundle, maxBytes, liveAfter) {
  * summary, shows none of the items or per-request lists run.json or a file supplied for it (its
  * actor's items and lists, its in-progress items, its screenshot entries), and carries
  * `traceUnavailable` with the reason; a warn event on its timeline says the same. A reader that
- * shows the run then never prices or checks rows the loader refused.
+ * shows the run then never prices or checks rows the loader refused. A live file the loader
+ * stopped reading (LiveItemsRead's `stopped`) gives its stream a `live-items.not-read` warn event.
  */
 export function displayedTraces(loaded) {
     const reasons = new Map(loaded.refused.map((error) => [error.streamId, error.message]));
-    if (reasons.size === 0)
+    const stopped = (loaded.live ?? []).filter((read) => read.stopped !== undefined);
+    if (reasons.size === 0 && stopped.length === 0)
         return loaded.bundle;
     const streams = loaded.bundle.streams.map((stream) => {
         const reason = reasons.get(stream.id);
         if (reason === undefined)
             return stream;
         const { liveActor: _live, trace: _index, actor, ...rest } = stream;
-        return {
+        return unjoined({
             ...rest,
             ...(actor === undefined ? {} : { actor: { ...withoutRequestLists(actor), items: [] } }),
             artifacts: stream.artifacts.filter((artifact) => !isScreenshot(artifact)),
             traceUnavailable: reason,
-        };
+        });
     });
     const events = loaded.bundle.streams
         .filter((stream) => reasons.has(stream.id))
@@ -484,7 +534,38 @@ export function displayedTraces(loaded) {
         message: reasons.get(stream.id),
         streamId: stream.id,
     }));
-    return { ...loaded.bundle, streams, events: [...loaded.bundle.events, ...events] };
+    const notRead = stopped.map((read) => ({
+        id: `event-live-items-not-read-${read.streamId}`,
+        at: loaded.bundle.streams.find((stream) => stream.id === read.streamId)?.updatedAt ?? "",
+        level: "warn",
+        type: "live-items.not-read",
+        message: read.stopped,
+        streamId: read.streamId,
+    }));
+    return {
+        ...loaded.bundle,
+        streams,
+        events: [...loaded.bundle.events, ...events, ...notRead],
+    };
+}
+/**
+ * What `reduce` returns for each stream of the bundle, loaded as loadRunTraces loads it, in stream
+ * order; the first refusal throws. Streams are loaded one at a time and nothing of a stream's files
+ * is kept past its `reduce` call, so a caller that keeps part of each trace holds one trace at a
+ * time where loadRunTraces holds them all. Unlike loadStreamTraces it does not read run.json again
+ * when a live file cannot be read, so it suits a run whose participants have finished.
+ */
+export async function reduceRunTraces(runPaths, bundle, reduce) {
+    const read = containedReader(runPaths);
+    const refusal = bundleRefusals(bundle);
+    const kept = [];
+    for (const [index, stream] of bundle.streams.entries()) {
+        const reason = refusal(stream);
+        if (reason !== undefined)
+            throw new StreamTraceRefusedError(stream.id, reason);
+        kept.push(reduce((await readStreamTrace(read, stream, RUN_ARTIFACT_MAX_BYTES)).stream, index));
+    }
+    return kept;
 }
 /** The bundle with every stream loaded; the first refusal throws. */
 export async function loadRunTraces(source, bundle, maxBytes) {

package/dist/run/streams.d.ts

@@ -316,4 +316,22 @@ export interface RunStream {
         kind: "bundle" | "review" | "observer" | "events" | "screenshot" | "trace" | "log" | "filesystem" | "recording";
     }>;
 }
+/**
+ * `T` without a participant's per-request lists (REQUEST_LISTS in src/run/stream-trace.ts):
+ * `tokenUsage.turns`, `conversation.requests` and `providerRequests`. From run bundle v4 only the
+ * trace file holds them, so a reader of run.json or of the Observer's data has none to read.
+ */
+export type WithoutRequestLists<T> = Omit<T, "providerRequests" | "tokenUsage" | "conversation"> & {
+    [K in "tokenUsage" & keyof T]?: Omit<NonNullable<T[K]>, "turns"> | undefined;
+} & {
+    [K in "conversation" & keyof T]?: Omit<NonNullable<T[K]>, "requests"> | undefined;
+};
+/**
+ * A stream as run.json holds it, in any version: its actor and live actor WithoutRequestLists.
+ * loadStreamTraces joins the lists from the trace file.
+ */
+export type StoredRunStream = Omit<RunStream, "actor" | "liveActor"> & {
+    actor?: WithoutRequestLists<ActorTrace>;
+    liveActor?: WithoutRequestLists<NonNullable<RunStream["liveActor"]>>;
+};
 export {};

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

@@ -1,11 +1,14 @@
 import type { DwellWindow } from "../actors/stop-conditions.js";
 import type { ParticipantSchedule } from "./arrivals.js";
-/** One participant as the plan has it: its schedule and its dwell window. */
+/** One participant as the plan has it: its schedule, its dwell window and its mission. */
 export interface EstimatedParticipant {
     readonly schedule: ParticipantSchedule;
     readonly limits: {
         readonly dwell?: DwellWindow;
     };
+    readonly assignment: {
+        readonly mission?: string;
+    };
 }
 /** A run's estimated bundle, and the scan's limit for its participants. */
 export interface BundleEstimate {

package/dist/study/bundle-estimate.js

@@ -1,14 +1,18 @@
 // How large a computer-use run's bundle grows, estimated from its plan before anything runs, and
-// whether it would pass a limit a later command holds it to: analysis reads run.json and each
-// participant's trace up to EVIDENCE_LIMITS.sourceBytes each, verify reads no file larger than
-// RUN_ARTIFACT_MAX_BYTES, and the public-safety scan visits at most runEntryLimit(participants)
-// files and folders.
+// whether it would pass a limit a later command holds it to: analysis reads run.json up to
+// EVIDENCE_LIMITS.sourceBytes, analysis, verify and the Observer read each participant's trace up to
+// RUN_ARTIFACT_MAX_BYTES, verify reads no file larger than RUN_ARTIFACT_MAX_BYTES, and the
+// public-safety scan visits at most runEntryLimit(participants) files and folders.
 //
 // observer/index.html carries every participant's items gzipped, so with busy participants it
 // passes verify's 32 MiB long before run.json passes analysis's 16 MiB: at these rates, 20
 // participants working 8 hours. From run bundle v4 run.json grows by participant, not by model
-// request: each participant's per-request lists are only in its trace. run.json can still pass
-// 16 MiB, since a study's mission is not capped and each participant's stream copies it.
+// request: each participant's per-request lists are only in its trace. run.json holds the mission
+// once for the run, once in each participant's stream and once more in the feedback candidate of
+// each participant that reports friction or stops. The mission is not capped, and the estimate
+// counts that last copy for every participant, so it warns at 100 participants with a mission of
+// 75,238 bytes. On 2026-10-13 the longest mission on the live computer-use runs kept on the
+// maintainer's machine was 807 characters.
 // observer-data.json leaves the lists out too and was 0.94 to 1.12 of run.json's size on the live
 // runs measured, so it passes 32 MiB only after run.json passes 16 MiB, and the estimate does not
 // check it.
@@ -63,8 +67,12 @@ const RATES = Object.freeze({
     /** observer/index.html's app before any run data: 1,199,831 bytes on the dry runs. */
     observerAppBytes: 1_200_000,
     /**
-     * The page's compact copy of observer-data.json, as a share of run.json: 0.71 to 0.84 on the
-     * live runs written as v4, where neither carries the per-request lists.
+     * The page's compact copy of observer-data.json, as a share of run.json before the mission: 0.71
+     * to 0.84 on the live runs written as v4, where neither carries the per-request lists. The page
+     * holds the mission at its full size once for the run and once for each participant: dry runs of
+     * 1 and 4 participants grew the page by 2 and 5 copies, as run.json grew, and a 0.128.0 run of 2
+     * participants with 2 feedback candidates held 5 copies in run.json and 3 on the page. An
+     * analysis adds each participant's assignment, cut to 8,000 bytes.
      */
     observerPageDataShare: 0.85,
     /**
@@ -97,11 +105,13 @@ export function estimateBundle(participants, sessionMs) {
     let frames = 0;
     let traces = 0;
     let largestTrace = 0;
+    let missionBytes = 0;
+    let longestMission = 0;
     let longestWindowMs = 0;
     // The longest any participant without an end is counted, for the messages.
     let openMs = Math.min(sessionMs, RATES.openSessionMs);
     let scheduled = 0;
-    for (const { schedule, limits } of participants) {
+    for (const { schedule, limits, assignment } of participants) {
         const { end } = schedule;
         const budgetMs = end?.windowMs ?? sessionMs;
         let countedMs;
@@ -122,12 +132,26 @@ export function estimateBundle(participants, sessionMs) {
         frames += ownFrames;
         traces += trace;
         largestTrace = Math.max(largestTrace, trace);
+        // The mission's bytes as run.json stores them, a JSON string without its quotes.
+        const mission = assignment.mission === undefined
+            ? 0
+            : Buffer.byteLength(JSON.stringify(assignment.mission)) - 2;
+        missionBytes += mission;
+        longestMission = Math.max(longestMission, mission);
     }
     const count = participants.length;
-    const runFileBytes = RATES.runBytes + count * RATES.participantBytes;
+    const dataBytes = RATES.runBytes + count * RATES.participantBytes;
+    // run.json holds the mission in the run's scenario goal, in each participant's stream and in the
+    // feedback candidate of each participant that reports friction or stops, counted for every
+    // participant. The rates were fit on runs with short missions, so a short mission is counted
+    // twice.
+    const runFileBytes = dataBytes + longestMission + 2 * missionBytes;
     const screenshots = count + turns + frames;
+    // The page holds no feedback candidate's copy.
     const observerPageBytes = Math.round(RATES.observerAppBytes +
-        RATES.observerPageDataShare * runFileBytes +
+        RATES.observerPageDataShare * dataBytes +
+        longestMission +
+        missionBytes +
         RATES.observerPageItemsShare * traces);
     return {
         runFileBytes,
@@ -158,12 +182,12 @@ export function bundleLimitReason(estimate) {
     const passed = [
         ...(runFile
             ? [
-                `This study's run.json may grow to about ${mib(estimate.runFileBytes)}, past the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads.`,
+                `This study's run.json may grow to about ${mib(estimate.runFileBytes)}, past the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads. It holds the mission once for the run, once in each participant's stream and once more for each participant that reports friction or stops, and the estimate counts the last copy for every participant.`,
             ]
             : []),
-        ...(estimate.largestTraceBytes > EVIDENCE_LIMITS.sourceBytes
+        ...(estimate.largestTraceBytes > RUN_ARTIFACT_MAX_BYTES
             ? [
-                `One participant's trace may grow to about ${mib(estimate.largestTraceBytes)}, past the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads of each trace.`,
+                `One participant's trace may grow to about ${mib(estimate.largestTraceBytes)}, past the ${mib(RUN_ARTIFACT_MAX_BYTES)} humanish reads of each trace.`,
             ]
             : []),
         ...(page
@@ -195,6 +219,7 @@ export function bundleLimitReason(estimate) {
     const changes = [
         ...(scheduled > 0 ? ["shorten the longest windows (participants[].endAfterMs)"] : []),
         ...(dwell ? ["shorten the dwell window (dwell.ms) or capture less often (dwell.everyMs)"] : []),
+        ...(runFile ? ["shorten the mission (actor.mission)"] : []),
     ];
     // A trace is one participant's, so splitting the study helps only the run's own files.
     if (runFile || page || entries || changes.length === 0)
@@ -211,7 +236,7 @@ export function bundleLimitReason(estimate) {
 }
 /** The estimate beside the limits, for `study check`. */
 export function describeBundle(estimate) {
-    return `run.json about ${mib(estimate.runFileBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads; largest trace about ${mib(estimate.largestTraceBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads of each; Observer page about ${mib(estimate.observerPageBytes)} of the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads; about ${count(estimate.entries)} files and folders of the ${count(estimate.entryLimit)} the public-safety scan reads; about ${mib(estimate.totalBytes, 0)} in all. Participants with a declared end are counted for their whole window and the others for up to ${formatDuration(estimate.basis.openMs)}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)}.`;
+    return `run.json about ${mib(estimate.runFileBytes)} of the ${mib(EVIDENCE_LIMITS.sourceBytes)} analysis reads; largest trace about ${mib(estimate.largestTraceBytes)} of the ${mib(RUN_ARTIFACT_MAX_BYTES)} humanish reads of each; Observer page about ${mib(estimate.observerPageBytes)} of the ${mib(RUN_ARTIFACT_MAX_BYTES)} verify reads; about ${count(estimate.entries)} files and folders of the ${count(estimate.entryLimit)} the public-safety scan reads; about ${mib(estimate.totalBytes, 0)} in all. Participants with a declared end are counted for their whole window and the others for up to ${formatDuration(estimate.basis.openMs)}, at a model turn every ${formatDuration(RATES.secondsPerTurn * 1000)}.`;
 }
 /** Bytes in MiB to `digits` places, or two under 0.1 MiB, so a short study's trace does not read 0.0. */
 function mib(bytes, digits = 1) {

package/dist/verify/verify.js

@@ -80,7 +80,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
     // 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.
     const traces = await loadTraces(runPaths, runJsonValue(bundleRead));
-    const { bundle, refusedTraces } = traces;
+    const { bundle, recorded, refusedTraces } = traces;
     const cleanupRead = await readRunJsonIfExists(runPaths, "cleanup.json");
     const review = {
         json: await readRunJsonIfExists(runPaths, "review.json"),
@@ -101,20 +101,20 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         unscannedArtifacts.files.push(SANDBOX_RECEIPTS_ARTIFACT);
     }
     const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
-        recordingPaths: new Set(isRunBundle(bundle)
+        recordingPaths: new Set(bundle
             ? bundle.streams.flatMap((stream) => (stream.recording ? [stream.recording.path] : []))
             : []),
-        screenshotPaths: isRunBundle(bundle) ? streamScreenshotPaths(bundle) : new Set(),
+        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(bundle)])],
+        sandboxIds: [...new Set([...journaledSandboxIds, ...keyedSandboxIds(recorded)])],
         sandboxIdFiles,
-    }, unscannedArtifacts, isRunBundle(bundle) ? bundle.simulations.length : 0);
+    }, unscannedArtifacts, bundle ? bundle.simulations.length : 0);
     addTraceScan(traces, publicSafetyFindings, unscannedArtifacts);
     // JSON escapes can hide a sensitive value from the byte scan while the
     // decoded recording exposes it to Observer, feedback, or analysis input.
     if (publicSafetyFindings.length < MAX_REPORTED_FINDINGS &&
-        bundle !== null &&
-        containsSensitive(JSON.stringify(bundle))) {
+        recorded !== null &&
+        containsSensitive(JSON.stringify(recorded))) {
         publicSafetyFindings.push("sensitive decoded run.json");
     }
     checks.push({
@@ -124,14 +124,14 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
             ? "no run text artifact or public-proof path matches a known secret or browser-profile pattern"
             : `public-safety findings: ${publicSafetyFindings.slice(0, 5).join(", ")}`,
     });
-    const missingEvidenceArtifacts = isRunBundle(bundle)
+    const missingEvidenceArtifacts = bundle
         ? await missingLocalEvidenceArtifacts(runPaths, bundle)
         : [];
-    const redactedShapeFrames = isRunBundle(bundle)
+    const redactedShapeFrames = bundle
         ? await redactedShapeFramePaths(runPaths, bundle)
         : new Set();
-    const invalidEvidenceReferences = isRunBundle(bundle) ? invalidRunEvidenceReferences(bundle) : [];
-    checks.push(evidenceArtifactsCheck(isRunBundle(bundle), [
+    const invalidEvidenceReferences = bundle ? invalidRunEvidenceReferences(bundle) : [];
+    checks.push(evidenceArtifactsCheck(bundle !== undefined, [
         ...refusedTraces,
         ...(invalidEvidenceReferences.length > 0
             ? [`invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`]
@@ -148,10 +148,10 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
             message: "Derived analysis contains sensitive text or unsafe artifact paths; sharing is blocked, original recording remains independently verifiable.",
         });
     const ok = checks.every((check) => check.ok);
-    const notFinished = isRunBundle(bundle)
+    const notFinished = bundle
         ? await runNotFinished(runPaths, bundle)
         : { warnings: [], unfinished: undefined };
-    const warnings = isRunBundle(bundle)
+    const warnings = bundle
         ? [
             ...rawScreenshotPostureWarnings(bundle, redactedShapeFrames),
             ...undeclaredSubjectStateWarnings(bundle),
@@ -160,7 +160,7 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
             ...notFinished.warnings,
         ]
         : [];
-    const shareSafety = isRunBundle(bundle)
+    const shareSafety = bundle
         ? buildShareSafety({
             ok,
             bundle,
@@ -226,12 +226,19 @@ function evidenceArtifactsCheck(shaped, problems) {
 /**
  * run.json with each stream's trace loaded, one file at a time, and the refusal of each trace that
  * does not match its index, with the ids of those streams. A run.json that fails the shape guard
- * is returned as it is.
+ * gives no bundle. `recorded` is the loaded bundle, or run.json as parsed when it has none.
  */
 async function loadTraces(runPaths, stored) {
     const scanned = { sensitive: [], opaque: [] };
     if (!isRunBundle(stored))
-        return { bundle: stored, refusedTraces: [], refusedStreams: new Set(), ...scanned, pages: [] };
+        return {
+            bundle: undefined,
+            recorded: stored,
+            refusedTraces: [],
+            refusedStreams: new Set(),
+            ...scanned,
+            pages: [],
+        };
     // Each trace is source evidence: scanned by the bytes it was joined from, apart from the
     // directory walk and any path exemption the walk makes.
     const { bundle, refused } = await loadStreamTraces(runPaths, stored, {
@@ -243,6 +250,7 @@ async function loadTraces(runPaths, stored) {
     });
     return {
         bundle,
+        recorded: bundle,
         refusedTraces: refused.map((error) => error.message),
         refusedStreams: new Set(refused.map((error) => error.streamId)),
         ...scanned,
@@ -381,13 +389,12 @@ 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.
- * `refusedStreams` names the streams whose traces the loader refused, which the evidence-artifacts
- * check reports.
+ * The bundle-content checks of the loaded bundle `valid`, in report order. Without one (run.json
+ * failed its shape guard) no check has findings. `refusedStreams` names the streams whose traces
+ * the loader refused, which the evidence-artifacts check reports.
  */
-async function evidenceChecks(runPaths, bundle, cleanupRead, refusedStreams) {
+async function evidenceChecks(runPaths, valid, cleanupRead, refusedStreams) {
     const cleanupJson = runJsonValue(cleanupRead);
-    const valid = isRunBundle(bundle) ? bundle : null;
     const pass = (message) => (valid ? message : SHAPE_UNCHECKED);
     const checks = [
         findingsCheck("terminal-product evidence", valid ? await validateTerminalProductEvidence(runPaths, valid) : [], pass("live terminal-product evidence is complete (ledgers, redacted output, proven teardown, known spend within the cap), or the run has none"), "terminal-product findings"),

package/docs/architecture/observer.md

@@ -97,6 +97,19 @@ A page that cannot join a body sends no cursors with its next poll. Static
 operator path. Agents and CI should use `humanish watch --json --no-open` for
 the same fresh evidence without browser open or a long-running process.
 
+The feed reads no live file whose index passes the 32 MiB read limit
+(`RUN_ARTIFACT_MAX_BYTES`); a request for the file by its path still gets the whole file. A page
+that sends a cursor for it keeps the items it holds: the
+server answers with no items past the cursor, gives the page's cursor back as `live`, and adds a
+`live-items.not-read` warning to the participant's timeline, so later polls send the same cursor
+and get the same answer. A poll that sends no cursor for that file gets the participant's trace
+as unavailable, with the file's size and the limit, and the page drops any items it held. Such a
+poll comes from a page opened after the file passed the limit or after the writer started a new
+generation, from the poll after a body the page could not join, and from a page whose cursors
+pass 8,000 characters (`MAX_AFTER_CHARS` in `observer/lib/live.ts`), which sends none. When the
+run finishes, a trace file past the limit is refused too, and every page shows that trace as
+unavailable.
+
 ### Reopening a run
 
 The TUI's **Open in Observer** action opens an HTTP view of the selected run's saved

package/docs/contracts/run-bundle.md

@@ -52,9 +52,14 @@ a run id or `latest`: it returns run.json with every trace file and live file jo
 as below, for v1, v2, v3 and v4 bundles, with each participant's per-request lists, and throws an Error named `StreamTraceRefusedError` for a
 file that does not match its index. Inside humanish, readers load a stream through
 `loadStreamTrace(runPaths, stream)`. A v1 stream returns as it is.
-An indexed stream's file is read under the 32 MiB per-file limit (analysis uses its 16 MiB
-source limit for each trace) and refused unless its size, sha256, item count and screenshot count
-match the index. A trace file belongs to one participant: every stream whose index names a file
+An indexed stream's file is read under the 32 MiB per-file limit, by analysis as by every other
+reader, and refused unless its size, sha256, item count and screenshot count
+match the index. A trace or live file whose index records more than the limit is refused before it
+is read, and the refusal says the file is larger than humanish reads of one file and that
+restoring a copy does not help. A trace file whose index is under the limit and whose bytes are
+over it changed after the run wrote it, and its refusal says to restore the run folder from a copy.
+A live file may hold bytes past its index while the writer appends; the loader reads only the
+indexed bytes. A trace file belongs to one participant: every stream whose index names a file
 another stream's index names, compared without case as a case-insensitive file system compares
 names, is refused before any file is read. The writer claims names the same way. In a v2 run.json every `actor`
 must have an index: an actor with no index, with
@@ -133,8 +138,9 @@ Readers that show a run (the Observer server, run detail and the TUI, the review
 provenance) load traces through the same loader and rules. A participant whose trace the loader
 refused shows none of the items run.json or a file supplied for it: its stream carries
 `traceUnavailable` with the reason, its Observer timeline a `trace.unavailable` warning, and its
-run-detail entry `evidenceUnavailable`. The Observer server reads the saved observer-data.json
-only while a run has no run.json at all; a run.json that is there and cannot be read, parsed or
+run-detail entry `evidenceUnavailable`. The Observer server reads run.json, and the saved
+observer-data.json, under the same 32 MiB limit; past it the server answers 404 with a reason
+naming the limit. It reads the saved observer-data.json only while a run has no run.json at all; a run.json that is there and cannot be read, parsed or
 used as a bundle answers 404 with the reason, never the saved projection. In safe serving
 (`observe --all --safe`) every read is checked against the files admitted with the run's
 share_ready verification, so a run.json changed after admission is refused and the admitted

package/docs/contracts/study-analysis.md

@@ -183,7 +183,19 @@ stopped, an operator can remove the empty lock directory and retry.
 
 Each request's packet admits up to 16 participants, 800 evidence items, 40 PNG
 captures, 160 KiB of text and 20 MiB of images. Individual source files, image
-dimensions and result sizes have separate limits. Count and text budgets are
+dimensions and result sizes have separate limits. Analysis reads run.json up to
+16 MiB and each participant's trace up to 32 MiB, as verify and the Observer do.
+It reads the traces one at a time and keeps of each only what selection can
+reach: the participant's share of its request's 800 evidence items, worked out
+from run.json before any trace is read, and the first 80 captures selection may
+read. Beside the one trace it is reading, analysis holds at most 800 entries for
+each request and 80 for each participant; their size grows with each trace
+item's text. A run.json past 16 MiB is refused as `ANALYSIS_SOURCE_TOO_LARGE`, and
+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
 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.128.0",
+  "version": "0.130.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",