humanish 0.128.0 → 0.130.0

package/CHANGELOG.md

@@ -8,6 +8,30 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.130.0: Analysis reads traces up to 32 MiB one at a time and names what it refused; the bundle estimate counts the mission (2026-10-13)
+
+humanish 0.130.0 lets analysis read long runs that 0.129.0 refused. Analysis reads each
+participant's trace up to 32 MiB, as verify and the Observer do, one trace at a time, and keeps of
+each only what selection can use. `humanish analyze` names the file it refused and why. The bundle
+estimate counts the study's mission in run.json, so its run.json warning can fire. This is a minor
+release because a run.json past 16 MiB is now refused as `ANALYSIS_SOURCE_TOO_LARGE` where it was
+`ANALYSIS_SOURCE_UNAVAILABLE`.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.130.0)
+
+## 0.129.0: Analysis reads long runs past 100,000 items; traces past 32 MiB get their own advice; shared-world skips counted apart (2026-10-13)
+
+humanish 0.129.0 fixes three things long studies reach. Analysis no longer refuses a run by how
+many events, trace items or screenshot frames it holds; it still reads each file only up to 16
+MiB. A trace or live file past 32 MiB, the most the trace loader reads, is refused with advice
+that fits, a running participant whose live file passes 32 MiB keeps the items the Observer page
+already shows, and the Observer server reads run.json under that limit. Shared-world runs count a
+participant skipped before its session apart from those that used the app, and no longer count a
+skip as overlap. This is a minor release because a shared-world `skippedReason` is now a sentence
+where it was `handoff-timeout` or `host-ended-before-handoff`.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.129.0)
+
 ## 0.128.0: Run bundle v4 keeps per-request lists in trace files; the study budget is checked before each request (2026-10-13)
 
 humanish 0.128.0 keeps run.json small in long studies. Run bundles are now

package/dist/actors/stop-cause.d.ts

@@ -6,4 +6,4 @@ export interface ActorEnding {
 /** Shared wording for consumers that already hold a validated, finite stop cause. */
 export declare function actorStopCauseLabel(cause: ActorEnding["cause"]): string;
 /** Project recorded control evidence, never participant prose. Leave the actor untouched. */
-export declare function actorEnding(actor: ActorTrace | undefined): ActorEnding | undefined;
+export declare function actorEnding(actor: Pick<ActorTrace, "stopCause" | "items" | "completionReason"> | undefined): ActorEnding | undefined;

package/dist/analysis/automatic.js

@@ -1,6 +1,5 @@
 import path from "node:path";
 import { resolveRunPath } from "../run/locate.js";
-import {} from "../run/bundle.js";
 import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalysisRun, } from "./service.js";
 import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
 import { captureEvidence } from "./evidence.js";

package/dist/analysis/evidence-sources.d.ts

@@ -1,10 +1,16 @@
-import type { RunBundle } from "../run/bundle.js";
-import type { RunStream } from "../run/streams.js";
+import type { StoredRunBundle } from "../run/bundle.js";
+import type { RunStream, StoredRunStream } from "../run/streams.js";
 import { type AnalysisParticipantInput, type CaptureVersion } from "./types.js";
 export declare function hasUnmappedCaptures(stream: RunStream): boolean;
 export declare function boundedText(value: string, maxBytes: number): string;
-export declare function participantAssignment(stream: RunStream, captureVersion?: CaptureVersion): string | null;
+export declare function participantAssignment(stream: StoredRunStream, captureVersion?: CaptureVersion): string | null;
 export declare function participantSource(stream: RunStream, captureVersion?: CaptureVersion): AnalysisParticipantInput;
+/**
+ * How many entries sourceEntries gives of run.json's `stream` once its trace is loaded, counted
+ * before the trace is read: the trace loader refuses a trace that does not hold the item count its
+ * index records.
+ */
+export declare function sourceEntryCount(bundle: StoredRunBundle, stream: StoredRunStream, captureVersion: CaptureVersion): number;
 export interface SourceEntry {
     eventId: string;
     kind: string;
@@ -17,9 +23,40 @@ export interface SourceEntry {
     captureDeclared: boolean;
     failed: boolean;
 }
-export declare function sourceEntries(bundle: RunBundle, stream: RunStream, captureVersion?: CaptureVersion): SourceEntry[];
+export declare function sourceEntries(bundle: StoredRunBundle, stream: RunStream, captureVersion?: CaptureVersion): SourceEntry[];
 /** Max-min allocation; stable ID order breaks a remainder tie by at most one slot. */
 export declare function fairShares(budget: number, capacities: number[]): number[];
-/** The trace messages that carry a participant's closing impressions. */
-export declare function impressionEventIds(stream: RunStream): ReadonlySet<string>;
-export declare function sourceOrder(entries: SourceEntry[], capturesOnly: boolean, impressions?: ReadonlySet<string>): SourceEntry[];
+/**
+ * What selection reads of one participant, taken while its trace is loaded so the trace can be
+ * dropped: the counts of its source entries and captures, and only the entries selection can
+ * reach. Selection admits at most `evidenceShare` entries, in `textOrder`, and reads captures in
+ * `captureOrder`.
+ */
+export interface ParticipantSources {
+    /** run.json's stream, which holds no trace items from run bundle v2. */
+    readonly stream: StoredRunStream;
+    readonly participant: AnalysisParticipantInput;
+    /** hasUnmappedCaptures of the loaded stream. */
+    readonly unmappedCaptures: boolean;
+    /** Whether an entry declares a capture that has no local path. */
+    readonly unresolvedCaptures: boolean;
+    readonly entryCount: number;
+    /** The entries with a local capture path. */
+    readonly captureCount: number;
+    /** The participant's part of its cohort's evidence limit. */
+    readonly evidenceShare: number;
+    /** The first evidenceShare entries in admission order, the participant's impressions first. */
+    readonly textOrder: readonly SourceEntry[];
+    /** The first captures in the order selection reads them. */
+    readonly captureOrder: readonly SourceEntry[];
+    /** The entries of textOrder and captureOrder, in source order. */
+    readonly entries: readonly SourceEntry[];
+}
+/**
+ * ParticipantSources of `loaded`, the stream `stored` with its trace loaded, keeping the first
+ * `reach.evidenceShare` entries in admission order and the first `reach.captures` captures.
+ */
+export declare function participantSources(bundle: StoredRunBundle, stored: StoredRunStream, loaded: RunStream, captureVersion: CaptureVersion, reach: {
+    readonly evidenceShare: number;
+    readonly captures: number;
+}): ParticipantSources;

package/dist/analysis/evidence-sources.js

@@ -6,8 +6,9 @@ import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { decodesToPlainRelativePath, isEvidencePath } from "../run/evidence-files.js";
 // How a run bundle becomes analysis sources: each participant's recorded provenance and assignment,
 // the evidence entries its trace offers, and the order in which entries are admitted under the
-// count and byte budgets. captureEvidence selects from these, and validateAnalysisEvidence
-// re-derives them to check a stored analysis against its run.
+// count and byte budgets. captureEvidence selects from these, taking each participant's while its
+// trace is loaded (participantSources), and validateAnalysisEvidence re-derives them to check a
+// stored analysis against its run.
 const stamp = (value) => typeof value === "string" && Number.isFinite(Date.parse(value))
     ? new Date(value).toISOString()
     : null;
@@ -96,6 +97,18 @@ export function participantSource(stream, captureVersion) {
         },
     };
 }
+const runEventsOf = (bundle, stream) => bundle.events.filter((entry) => entry.streamId === stream.id ||
+    (entry.streamId === undefined && eventRecordIdOf(entry) === recordIdOf(stream)));
+/**
+ * How many entries sourceEntries gives of run.json's `stream` once its trace is loaded, counted
+ * before the trace is read: the trace loader refuses a trace that does not hold the item count its
+ * index records.
+ */
+export function sourceEntryCount(bundle, stream, captureVersion) {
+    const comms = captureVersion === ACTION_CAPTURE_VERSION && bundle.commsReceiving ? 1 : 0;
+    const items = stream.trace?.items ?? stream.actor?.items?.length ?? 0;
+    return comms + items + runEventsOf(bundle, stream).length;
+}
 export function sourceEntries(bundle, stream, captureVersion) {
     const items = itemsFor(stream);
     // Absent version retains the exact legacy mapping used by saved 0.89.1 analyses.
@@ -151,8 +164,7 @@ export function sourceEntries(bundle, stream, captureVersion) {
         });
     }
     const runEventIds = new Set();
-    for (const event of bundle.events.filter((entry) => entry.streamId === stream.id ||
-        (entry.streamId === undefined && eventRecordIdOf(entry) === recordIdOf(stream)))) {
+    for (const event of runEventsOf(bundle, stream)) {
         if (runEventIds.has(event.id))
             throw new Error("ANALYSIS_SOURCE_EVENT_DUPLICATE");
         runEventIds.add(event.id);
@@ -205,11 +217,11 @@ function spreadOrder(entries) {
     return result;
 }
 /** The trace messages that carry a participant's closing impressions. */
-export function impressionEventIds(stream) {
+function impressionEventIds(stream) {
     const impressions = stream.actor?.impressions;
     return new Set(impressions?.status === "collected" ? impressions.items.map((item) => item.messageId) : []);
 }
-export function sourceOrder(entries, capturesOnly, impressions = new Set()) {
+function sourceOrder(entries, capturesOnly, impressions = new Set()) {
     const candidates = capturesOnly ? entries.filter((entry) => entry.capturePath !== null) : entries;
     const ordered = new Set();
     const admit = (entry) => {
@@ -258,3 +270,25 @@ export function sourceOrder(entries, capturesOnly, impressions = new Set()) {
         admit(entry);
     return [...ordered];
 }
+/**
+ * ParticipantSources of `loaded`, the stream `stored` with its trace loaded, keeping the first
+ * `reach.evidenceShare` entries in admission order and the first `reach.captures` captures.
+ */
+export function participantSources(bundle, stored, loaded, captureVersion, reach) {
+    const all = sourceEntries(bundle, loaded, captureVersion);
+    const textOrder = sourceOrder(all, false, impressionEventIds(loaded)).slice(0, reach.evidenceShare);
+    const captureOrder = sourceOrder(all, true).slice(0, reach.captures);
+    const reachable = new Set([...textOrder, ...captureOrder]);
+    return {
+        stream: stored,
+        participant: participantSource(loaded, captureVersion),
+        unmappedCaptures: hasUnmappedCaptures(loaded),
+        unresolvedCaptures: all.some((entry) => entry.captureDeclared && entry.capturePath === null),
+        entryCount: all.length,
+        captureCount: all.filter((entry) => entry.capturePath !== null).length,
+        evidenceShare: reach.evidenceShare,
+        textOrder,
+        captureOrder,
+        entries: all.filter((entry) => reachable.has(entry)),
+    };
+}

package/dist/analysis/evidence.js

@@ -1,15 +1,13 @@
-import { isCommsReceivingEvidence } from "../comms/receiving-evidence.js";
 import { createHash } from "node:crypto";
 import { screenshotEvidenceError } from "../evidence/image.js";
-import { runIdOf } from "../run/paths.js";
-import { isRecord } from "../run/type-guards.js";
-import { isReadRunBundleSchema, RUN_BUNDLE_FILE } from "../run/bundle.js";
-import { loadStreamTraces } from "../run/stream-trace.js";
+import {} from "../run/paths.js";
+import { RUN_BUNDLE_FILE } from "../run/bundle.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { digestAnalysisInput, hashAnalysisValue, validateAnalysisInputMetadata, } from "./validation.js";
-import { boundedText, fairShares, hasUnmappedCaptures, participantAssignment, participantSource, sourceEntries, sourceOrder, impressionEventIds, } from "./evidence-sources.js";
+import { boundedText, fairShares, hasUnmappedCaptures, participantAssignment, participantSource, participantSources, sourceEntries, sourceEntryCount, } from "./evidence-sources.js";
 import { readBoundedFile, readBoundedFileResult } from "../run/evidence-files.js";
 import { analysisCohortCount, analysisCohorts, EVIDENCE_LIMITS } from "./analysis-limits.js";
+import { parseAnalysisSource, readParticipantTraces, runFileTooLarge } from "./source.js";
 export { EVIDENCE_LIMITS };
 // A second guard for direct callers. The analysis service already requires every stream to be in
 // TERMINAL_SIMULATION_STATUSES; this refuses only statuses that mean still running, so a dry-run
@@ -25,78 +23,6 @@ const UNFINISHED_STREAM_STATUSES = new Set([
     "suspended",
 ]);
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
-function parseSource(prepared, bytes) {
-    if (bytes.length > EVIDENCE_LIMITS.sourceBytes)
-        throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
-    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
-    if (!isRecord(value) ||
-        !isReadRunBundleSchema(value.schema) ||
-        value.runId !== runIdOf(prepared) ||
-        !Array.isArray(value.streams) ||
-        value.streams.length > EVIDENCE_LIMITS.participants ||
-        !Array.isArray(value.events) ||
-        value.events.length > 100000 ||
-        (value.commsReceiving !== undefined && !isCommsReceivingEvidence(value.commsReceiving)))
-        throw new Error("ANALYSIS_SOURCE_INVALID");
-    const ids = new Set();
-    for (const stream of value.streams) {
-        if (!isRecord(stream) ||
-            typeof stream.id !== "string" ||
-            stream.id.length === 0 ||
-            stream.id.length > 256 ||
-            ids.has(stream.id) ||
-            typeof stream.label !== "string" ||
-            typeof stream.status !== "string") {
-            throw new Error("ANALYSIS_SOURCE_INVALID");
-        }
-        ids.add(stream.id);
-        if (stream.actor !== undefined && !isRecord(stream.actor))
-            throw new Error("ANALYSIS_SOURCE_INVALID");
-    }
-    for (const event of value.events) {
-        if (!isRecord(event) ||
-            typeof event.id !== "string" ||
-            typeof event.message !== "string" ||
-            typeof event.type !== "string")
-            throw new Error("ANALYSIS_SOURCE_INVALID");
-    }
-    return value;
-}
-/**
- * run.json's bundle with each stream's trace loaded. The source limit applies to each trace file
- * as it does to run.json; run.json's digest, which the analysis record binds, binds each trace's
- * sha256.
- */
-async function readSource(prepared, bytes, traceBytes) {
-    const stored = parseSource(prepared, bytes);
-    if (stored.streams.some((stream) => (stream.trace?.bytes ?? 0) > traceBytes))
-        throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
-    const loaded = await loadStreamTraces(prepared, stored, { maxBytes: traceBytes });
-    if (loaded.refused.length > 0)
-        throw new Error("ANALYSIS_SOURCE_INVALID");
-    for (const stream of loaded.bundle.streams)
-        validateTraceItems(stream.actor);
-    return loaded.bundle;
-}
-function validateTraceItems(actor) {
-    if (actor !== undefined &&
-        (!isRecord(actor) || !Array.isArray(actor.items) || actor.items.length > 100000)) {
-        throw new Error("ANALYSIS_SOURCE_INVALID");
-    }
-    const eventIds = new Set();
-    for (const item of isRecord(actor) ? actor.items : []) {
-        if (!isRecord(item) ||
-            typeof item.id !== "string" ||
-            item.id.length === 0 ||
-            item.id.length > 256 ||
-            eventIds.has(item.id) ||
-            typeof item.kind !== "string" ||
-            typeof item.title !== "string" ||
-            (item.text !== undefined && typeof item.text !== "string"))
-            throw new Error("ANALYSIS_SOURCE_INVALID");
-        eventIds.add(item.id);
-    }
-}
 /** Select once from retained source. Models receive no filesystem or network resolver. */
 export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     const limits = { ...EVIDENCE_LIMITS, ...requested };
@@ -108,22 +34,33 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
         }
     }
     if (bundleBytes.length > limits.sourceBytes)
-        throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
+        throw runFileTooLarge(bundleBytes.length, limits.sourceBytes);
     const current = await readBoundedFile(prepared, RUN_BUNDLE_FILE, limits.sourceBytes);
     if (!current || !current.equals(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
-    const bundle = await readSource(prepared, bundleBytes, limits.sourceBytes);
+    const bundle = parseAnalysisSource(prepared, bundleBytes);
     const captureVersion = ACTION_CAPTURE_VERSION;
     if (bundle.streams.some((stream) => stream.liveActor !== undefined || UNFINISHED_STREAM_STATUSES.has(stream.status))) {
         throw new Error("ANALYSIS_RUN_UNFINISHED");
     }
-    const selected = bundle.streams.slice(0, limits.participants);
+    // Admission stops at a participant's evidence share. The shares come from run.json's counts, so
+    // only the first share of each participant's entries in admission order is kept of its trace.
+    const shares = evidenceShares(bundle, limits, captureVersion);
+    // A participant past limits.participants has its trace read and checked by the loader, and gives
+    // no entries, so nothing in its run events or items can refuse the participants that are kept.
+    const sources = await readParticipantTraces(prepared, bundle, (stream, index) => index < limits.participants
+        ? participantSources(bundle, bundle.streams[index], stream, captureVersion, {
+            evidenceShare: shares[index],
+            captures: maxCaptureReads(limits),
+        })
+        : null);
+    const selected = sources.filter((source) => source !== null);
     const evidence = [];
     const images = [];
     const omissions = new Set();
     const contextBytes = new Map();
-    const participants = selected.map((stream) => {
-        const participant = participantSource(stream, captureVersion);
+    const participants = selected.map((sources) => {
+        const { participant, stream } = sources;
         const assignment = participantAssignment(stream, captureVersion);
         if (assignment === null || assignment.trim() === "")
             omissions.add("Some participants have no recorded assignment.");
@@ -131,22 +68,21 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
             participant.assignment !== assignment ||
             participant.recordedReason !== (stream.actor?.reason ?? null))
             omissions.add("Participant context exceeded the text limit.");
-        contextBytes.set(stream, Buffer.byteLength(JSON.stringify(participant)));
+        contextBytes.set(sources, Buffer.byteLength(JSON.stringify(participant)));
         return participant;
     });
     // Each cohort is one request's packet, selected under the full limits on its own.
     const packings = [];
     const textByEntry = new Map();
     for (const cohort of analysisCohorts(selected)) {
-        const textBytes = cohort.reduce((total, stream) => total + contextBytes.get(stream), 0);
+        const textBytes = cohort.reduce((total, sources) => total + contextBytes.get(sources), 0);
         if (textBytes > limits.textBytes)
             throw new Error("ANALYSIS_PARTICIPANT_CONTEXT_TOO_LARGE");
         // Tie-breaking uses stable participant IDs, not the order of streams in a bundle.
         // The emitted packet still preserves participant and source event order.
         const cohortPackings = cohort
-            .map((stream) => ({
-            stream,
-            entries: sourceEntries(bundle, stream, captureVersion),
+            .map((sources) => ({
+            sources,
             captures: new Map(),
             admitted: new Set(),
             captureCursor: 0,
@@ -155,7 +91,7 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
             imageBytes: 0,
             reservationBlocked: false,
         }))
-            .sort((a, b) => (a.stream.id < b.stream.id ? -1 : a.stream.id > b.stream.id ? 1 : 0));
+            .sort((a, b) => byStreamId(a.sources.stream, b.sources.stream));
         const sel = planCaptureSelection(cohortPackings, limits);
         await selectCaptures(prepared, cohortPackings, sel, omissions);
         recordCaptureOmissions(cohortPackings, sel, omissions);
@@ -166,7 +102,7 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     packEvidence(selected, packings, textByEntry, evidence, images);
     const omittedStreamIds = bundle.streams.slice(limits.participants).map((stream) => stream.id);
     const coverage = {
-        includedStreamIds: selected.map((stream) => stream.id),
+        includedStreamIds: selected.map((sources) => sources.stream.id),
         omittedStreamIds,
         evidenceCount: evidence.length,
         captureCount: images.length,
@@ -190,22 +126,45 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     return result;
 }
+const byStreamId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+/**
+ * Each stream's part of its cohort's limits.evidence, by fairShares over the entries run.json
+ * gives it, in the stream id order selection breaks ties in. A stream past limits.participants
+ * gets none.
+ */
+function evidenceShares(bundle, limits, captureVersion) {
+    const shares = bundle.streams.map(() => 0);
+    const included = bundle.streams.slice(0, limits.participants).map((stream, index) => ({
+        stream,
+        index,
+    }));
+    for (const cohort of analysisCohorts(included)) {
+        cohort.sort((a, b) => byStreamId(a.stream, b.stream));
+        const cohortShares = fairShares(limits.evidence, cohort.map(({ stream }) => sourceEntryCount(bundle, stream, captureVersion)));
+        for (const [position, { index }] of cohort.entries())
+            shares[index] = cohortShares[position];
+    }
+    return shares;
+}
+/**
+ * The most capture reads one cohort's selection makes. Missing/invalid files cannot turn selection
+ * into an exhaustive file scan: at most 2 * captures bounded reads, each at most imageBytes;
+ * successfully returned bytes (including invalid PNGs) also stop at 2 * totalImageBytes. A read
+ * moves its participant's cursor at most one capture on: a reserved read that meets the byte limit
+ * leaves the cursor for a later pass. So no participant's reads pass this many captures.
+ */
+const maxCaptureReads = (limits) => 2 * limits.captures;
 function planCaptureSelection(packings, limits) {
-    // Missing/invalid files cannot turn selection into an exhaustive file scan.
-    // At most 2 * captures bounded reads, each at most imageBytes; successfully
-    // returned bytes (including invalid PNGs) also stop at 2 * totalImageBytes.
-    const maxAttempts = 2 * limits.captures;
+    const maxAttempts = maxCaptureReads(limits);
     const readBudget = 2 * limits.totalImageBytes;
-    const evidenceShares = fairShares(limits.evidence, packings.map((packing) => packing.entries.length));
-    const captureOrders = packings.map((packing) => sourceOrder(packing.entries, true));
-    const captureShares = fairShares(limits.captures, packings.map((_, index) => Math.min(evidenceShares[index], captureOrders[index].length)));
+    const evidenceShares = packings.map((packing) => packing.sources.evidenceShare);
+    const captureShares = fairShares(limits.captures, packings.map((packing, index) => Math.min(evidenceShares[index], packing.sources.captureCount)));
     const attemptShares = captureShares.map((share) => 2 * share);
     const readShares = fairShares(readBudget, attemptShares.map((share) => share * limits.imageBytes));
     const imageShares = fairShares(limits.totalImageBytes, captureShares.map((share) => share * limits.imageBytes));
     return {
         limits,
         evidenceShares,
-        captureOrders,
         captureShares,
         attemptShares,
         readShares,
@@ -229,7 +188,7 @@ async function selectCaptures(prepared, packings, sel, omissions) {
         for (const [index, packing] of packings.entries()) {
             if (packing.captures.size >= sel.captureShares[index] ||
                 packing.attempts >= sel.attemptShares[index] ||
-                packing.captureCursor >= sel.captureOrders[index].length ||
+                packing.captureCursor >= packing.sources.captureOrder.length ||
                 sel.attemptedReads >= sel.maxAttempts ||
                 (sel.reserved && packing.reservationBlocked))
                 continue;
@@ -249,7 +208,7 @@ async function selectCaptures(prepared, packings, sel, omissions) {
             attempted = true;
             packing.attempts++;
             sel.attemptedReads++;
-            const source = sel.captureOrders[index][packing.captureCursor];
+            const source = packing.sources.captureOrder[packing.captureCursor];
             const result = await readBoundedFileResult(prepared, source.capturePath, allowance);
             if (result.state === "limit" &&
                 result.size <= BigInt(limits.imageBytes) &&
@@ -296,8 +255,10 @@ function reclaimCaptureSlots(packings, sel) {
         if (share === 0 && sel.evidenceShares[index] > 0)
             sel.attemptShares[index] = 2;
     });
+    // A pass reads only the captures in captureOrder. A slot granted past them is one no pass uses,
+    // and selectCaptures would reclaim it again forever.
     const available = packings.map((packing, index) => packing.attempts < sel.attemptShares[index]
-        ? Math.min(sel.evidenceShares[index] - packing.captures.size, sel.captureOrders[index].length - packing.captureCursor, sel.attemptShares[index] - packing.attempts)
+        ? Math.min(sel.evidenceShares[index] - packing.captures.size, packing.sources.captureOrder.length - packing.captureCursor, sel.attemptShares[index] - packing.attempts)
         : 0);
     const extra = packings.map(() => 0);
     // Count earlier admissions when reclaiming slots: a byte-deferred participant
@@ -327,21 +288,22 @@ function reclaimCaptureSlots(packings, sel) {
 function recordCaptureOmissions(packings, sel, omissions) {
     const { limits } = sel;
     for (const [index, packing] of packings.entries()) {
-        if (!packing.stream.actor)
+        const { sources } = packing;
+        if (!sources.stream.actor)
             omissions.add("Some participants have no normalized recorded trace.");
-        if (hasUnmappedCaptures(packing.stream))
+        if (sources.unmappedCaptures)
             omissions.add("Some declared captures have no normalized trace reference.");
         for (const source of packing.captures.keys())
             packing.admitted.add(source);
-        for (const source of sourceOrder(packing.entries, false, impressionEventIds(packing.stream))) {
+        for (const source of sources.textOrder) {
             if (packing.admitted.size >= sel.evidenceShares[index])
                 break;
             packing.admitted.add(source);
         }
-        if (packing.admitted.size < packing.entries.length)
+        if (packing.admitted.size < sources.entryCount)
             omissions.add("Some evidence was omitted by the packet size limit.");
-        if (packing.entries.some((entry) => entry.capturePath !== null && !packing.captures.has(entry))) {
-            const pending = packing.captureCursor < sel.captureOrders[index].length;
+        if (sources.captureCount > packing.captures.size) {
+            const pending = packing.captureCursor < sources.captureCount;
             if (pending && sel.captureCount >= limits.captures)
                 omissions.add("Some captures were omitted by the capture count limit.");
             if (pending && sel.imageBytes >= limits.totalImageBytes)
@@ -355,9 +317,8 @@ function recordCaptureOmissions(packings, sel, omissions) {
             }
             omissions.add("Captures were sampled across participants and session boundaries; omitted moments may contain other issues.");
         }
-        if (packing.entries.some((entry) => entry.captureDeclared && entry.capturePath === null)) {
+        if (sources.unresolvedCaptures)
             omissions.add("Some screenshot references were absent or nonlocal.");
-        }
     }
 }
 function boundEvidenceText(packings, budget, omissions) {
@@ -376,9 +337,10 @@ function boundEvidenceText(packings, budget, omissions) {
     return textByEntry;
 }
 function packEvidence(selected, packings, textByEntry, evidence, images) {
-    for (const stream of selected) {
-        const packing = packings.find((candidate) => candidate.stream === stream);
-        for (const source of packing.entries.filter((entry) => packing.admitted.has(entry))) {
+    for (const sources of selected) {
+        const { stream } = sources;
+        const packing = packings.find((candidate) => candidate.sources === sources);
+        for (const source of sources.entries.filter((entry) => packing.admitted.has(entry))) {
             const id = `e${String(evidence.length + 1).padStart(6, "0")}`;
             const bytes = packing.captures.get(source);
             const capture = bytes
@@ -409,11 +371,27 @@ function packEvidence(selected, packings, textByEntry, evidence, images) {
         }
     }
 }
+const citation = (kind, eventId) => JSON.stringify([kind, eventId]);
 /** Validate exact source membership before any stored path may be read. */
 export async function validateAnalysisEvidence(prepared, artifact, bundleBytes) {
     if (artifact.captureVersion !== undefined && artifact.captureVersion !== ACTION_CAPTURE_VERSION)
         throw new Error("ANALYSIS_CAPTURE_VERSION_INVALID");
-    const bundle = await readSource(prepared, bundleBytes, EVIDENCE_LIMITS.sourceBytes);
+    const bundle = parseAnalysisSource(prepared, bundleBytes);
+    const citations = new Map();
+    for (const entry of artifact.evidence)
+        citations.set(entry.streamId, (citations.get(entry.streamId) ?? new Set()).add(citation(entry.kind, entry.eventId)));
+    const checked = new Map(await readParticipantTraces(prepared, bundle, (stream) => {
+        const entries = sourceEntries(bundle, stream, artifact.captureVersion);
+        const cited = new Map();
+        for (const entry of entries) {
+            const key = citation(entry.kind, entry.eventId);
+            if (citations.get(stream.id)?.has(key))
+                cited.set(key, [...(cited.get(key) ?? []), entry]);
+        }
+        const participant = participantSource(stream, artifact.captureVersion);
+        const unmappedCaptures = hasUnmappedCaptures(stream);
+        return [stream.id, { participant, unmappedCaptures, entryCount: entries.length, cited }];
+    }));
     if (artifact.runId !== bundle.runId || artifact.sourceRunSha256 !== sha256(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     const included = new Set(artifact.coverage.includedStreamIds);
@@ -421,18 +399,13 @@ export async function validateAnalysisEvidence(prepared, artifact, bundleBytes)
     if (bundle.streams.some((stream) => !included.has(stream.id) && !omitted.has(stream.id)) ||
         included.size + omitted.size !== bundle.streams.length)
         throw new Error("ANALYSIS_SOURCE_COVERAGE_INVALID");
-    const sourceByStream = new Map(bundle.streams.map((stream) => [
-        stream.id,
-        sourceEntries(bundle, stream, artifact.captureVersion),
-    ]));
     const context = new Map(artifact.participants.map((participant) => [participant.streamId, participant]));
     if (context.size !== included.size || artifact.participants.length !== included.size)
         throw new Error("ANALYSIS_PARTICIPANT_INPUT_INVALID");
     for (const stream of bundle.streams.filter((candidate) => included.has(candidate.id))) {
         const participant = context.get(stream.id);
-        if (!participant ||
-            hashAnalysisValue(participant) !==
-                hashAnalysisValue(participantSource(stream, artifact.captureVersion))) {
+        const source = checked.get(stream.id);
+        if (!participant || hashAnalysisValue(participant) !== hashAnalysisValue(source.participant)) {
             throw new Error("ANALYSIS_PARTICIPANT_INPUT_INVALID");
         }
         if (artifact.captureVersion === ACTION_CAPTURE_VERSION &&
@@ -441,7 +414,7 @@ export async function validateAnalysisEvidence(prepared, artifact, bundleBytes)
             throw new Error("ANALYSIS_COVERAGE_INCOMPLETE");
         if (artifact.captureVersion === ACTION_CAPTURE_VERSION &&
             artifact.coverage.complete &&
-            hasUnmappedCaptures(stream))
+            source.unmappedCaptures)
             throw new Error("ANALYSIS_COVERAGE_INCOMPLETE");
     }
     const sourceKeys = new Set();
@@ -450,9 +423,7 @@ export async function validateAnalysisEvidence(prepared, artifact, bundleBytes)
     const imageByteLimit = analysisCohortCount(included.size) * EVIDENCE_LIMITS.totalImageBytes;
     let checkedImageBytes = 0;
     for (const entry of artifact.evidence) {
-        const matches = sourceByStream
-            .get(entry.streamId)
-            ?.filter((source) => source.eventId === entry.eventId && source.kind === entry.kind) ?? [];
+        const matches = checked.get(entry.streamId)?.cited.get(citation(entry.kind, entry.eventId)) ?? [];
         const source = matches[0];
         const sourceKey = JSON.stringify([entry.streamId, entry.kind, entry.eventId]);
         if (sourceKeys.has(sourceKey))
@@ -495,7 +466,7 @@ export async function validateAnalysisEvidence(prepared, artifact, bundleBytes)
         }
     }
     if (artifact.coverage.complete &&
-        [...sourceByStream.values()].reduce((total, entries) => total + entries.length, 0) !==
+        [...checked.values()].reduce((total, stream) => total + stream.entryCount, 0) !==
             artifact.evidence.length) {
         throw new Error("ANALYSIS_COVERAGE_INCOMPLETE");
     }

package/dist/analysis/service.js

@@ -11,7 +11,8 @@ import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { physicalCwdOf, runIdOf, resolvePhysicalCwd, validatePreparedRunRootIdentity, } from "../run/paths.js";
 import { isRunStatusRecord, RUN_STATUS_FILE } from "../run/status.js";
 import { captureEvidence, EVIDENCE_LIMITS } from "./evidence.js";
-import { pathMissing, readBoundedFile } from "../run/evidence-files.js";
+import { AnalysisSourceRefusedError, runFileTooLarge } from "./source.js";
+import { pathMissing, readBoundedFile, readBoundedFileResult } from "../run/evidence-files.js";
 import { estimateAnalysisAdmission, preferLargerAnalysisOutput, runAnalysis, ANALYSIS_PROMPT_VERSION, } from "./execute.js";
 import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalyses, writeAnalysis, } from "./store.js";
 import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
@@ -47,7 +48,7 @@ const messages = {
     ANALYSIS_RUN_ACTIVE: "Analysis requires a completed recording. Wait for the study to finish.",
     ANALYSIS_NO_PARTICIPANTS: "This run contains no participant evidence to analyze.",
     ANALYSIS_REQUIRES_LIVE_RUN: "A dry run has no participant behavior to analyze. Select a completed live run.",
-    ANALYSIS_SOURCE_UNAVAILABLE: "The source recording is missing, unsafe, or exceeds the input limit.",
+    ANALYSIS_SOURCE_UNAVAILABLE: "The source recording is missing or unsafe.",
     ANALYSIS_SOURCE_CHANGED: "The source recording changed during analysis. The result cannot be published against different evidence.",
     ANALYSIS_BUSY: "Another analysis holds this run's .analysis-lock directory. If it was interrupted, confirm it has stopped before removing that empty directory.",
     ANALYSIS_HISTORY_UNAVAILABLE: "Analysis history is unavailable or full. No request was sent. Inspect this run's analysis and analysis-attempts storage before retrying.",
@@ -72,14 +73,14 @@ const codexRecovery = {
     analysis_codex_process_failed: "The Codex analyst process ended without a usable report. Inspect the retained attempt before retrying.",
     analysis_codex_cleanup_failed: "Codex analyst cleanup could not be confirmed. Inspect private codex-analysis-recovery markers in your user cache and humanish-codex-analysis-* directories in your system temp directory. Preserve any retained login state and run codex login before retrying.",
 };
-const fail = (run, dryRun, code) => ({
+const fail = (run, dryRun, code, message = messages[code] ?? messages.ANALYSIS_UNAVAILABLE) => ({
     schema: ANALYZE_RESULT_SCHEMA,
     ok: false,
     run,
     dryRun,
     reused: false,
     warnings: [],
-    error: { code, message: messages[code] ?? messages.ANALYSIS_UNAVAILABLE },
+    error: { code, message },
 });
 /**
  * A dry-run bundle cannot be analyzed under any configuration, so this refusal is checked before
@@ -145,9 +146,12 @@ export async function withAnalysisLock(prepared, action) {
 }
 /** The completion gate: the run verifies, is live and finished, and has participants. */
 export async function readCompletedAnalysisSource(cwd, prepared) {
-    const bytes = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
-    if (!bytes)
+    const read = await readBoundedFileResult(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+    if (read.state === "limit")
+        throw runFileTooLarge(read.size, EVIDENCE_LIMITS.sourceBytes);
+    if (read.state !== "read")
         throw new Error("ANALYSIS_SOURCE_UNAVAILABLE");
+    const bytes = read.bytes;
     const verified = await verifyRunPrepared(cwd, runIdOf(prepared), prepared);
     if (!verified.ok && verified.recordingOk !== true)
         throw new Error("ANALYSIS_VERIFY_FAILED");
@@ -381,6 +385,8 @@ export async function analyzeRun(cwdInput, run, options, deps = {}) {
         return dryRun ? await execute() : await withAnalysisLock(prepared, execute);
     }
     catch (error) {
+        if (error instanceof AnalysisSourceRefusedError)
+            return fail(run, dryRun, error.message, `${error.reason} No request was sent.`);
         const code = error instanceof Error && Object.hasOwn(messages, error.message)
             ? error.message
             : "ANALYSIS_UNAVAILABLE";