humanish 0.122.0 → 0.124.0

package/dist/run/bundle-shape.js

@@ -1,6 +1,6 @@
 import { isCommsReceivingEvidence } from "../comms/receiving-evidence.js";
 import { isCapturedGitState } from "./git-state.js";
-import { PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA, } from "./bundle.js";
+import { PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "./bundle.js";
 import { CLEANUP_SCHEMA, } from "./results.js";
 import { isRunSimulationStatus, isRunStream, isRunStreamKind } from "./stream-shape.js";
 import { isLocalEvidenceArtifactPath } from "./paths.js";
@@ -10,7 +10,7 @@ import { isSharedWorldEvidence } from "./shared-world-shape.js";
 import { isNonNegativeSafeInteger, isPositiveSafeInteger, isRecord } from "./type-guards.js";
 export function isRunBundle(value) {
     return (isRecord(value) &&
-        value.schema === RUN_BUNDLE_SCHEMA &&
+        (value.schema === RUN_BUNDLE_SCHEMA || value.schema === RUN_BUNDLE_V1_SCHEMA) &&
         (value.commsReceiving === undefined || isCommsReceivingEvidence(value.commsReceiving)) &&
         (value.publication === undefined ||
             (isRecord(value.publication) &&

package/dist/run/bundle.d.ts

@@ -5,7 +5,10 @@ import type { SharedWorldEvidence } from "./shared-world-evidence.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import type { RunInterruptSignal } from "./status.js";
 import type { RunSimulationStatus, RunStream, RunStreamKind } from "./streams.js";
-export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
+/** The run bundle version this release writes: each stream's trace is a file run.json indexes. */
+export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v2";
+/** The version 0.122.0 and earlier wrote, with every trace inline. It is still read. */
+export declare const RUN_BUNDLE_V1_SCHEMA = "humanish.run-bundle.v1";
 /** The run bundle file, relative to the run directory. */
 export declare const RUN_BUNDLE_FILE = "run.json";
 export declare const REVIEW_SCHEMA = "humanish.review.v1";
@@ -228,7 +231,7 @@ export interface RunBundle {
         restrictions: ["real-communications"];
     };
     commsReceiving?: CommsReceivingEvidence;
-    schema: typeof RUN_BUNDLE_SCHEMA;
+    schema: typeof RUN_BUNDLE_SCHEMA | typeof RUN_BUNDLE_V1_SCHEMA;
     runId: string;
     mode: "dry-run" | "live";
     simCount: number;

package/dist/run/bundle.js

@@ -1,7 +1,10 @@
 import path from "node:path";
 import { captureGitState } from "./git-state.js";
 import { studyFields } from "./study-provenance.js";
-export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
+/** The run bundle version this release writes: each stream's trace is a file run.json indexes. */
+export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v2";
+/** The version 0.122.0 and earlier wrote, with every trace inline. It is still read. */
+export const RUN_BUNDLE_V1_SCHEMA = "humanish.run-bundle.v1";
 /** The run bundle file, relative to the run directory. */
 export const RUN_BUNDLE_FILE = "run.json";
 export const REVIEW_SCHEMA = "humanish.review.v1";

package/dist/run/detail.d.ts

@@ -36,6 +36,12 @@ export interface RunParticipant {
     thoughts?: number;
     /** `null` when declared absent; absent when never recorded. Never coerced to 0. */
     estimatedCostUsd?: number | null;
+    /**
+     * Why this participant's evidence cannot be shown: the loader refused its trace (a file that does
+     * not match run.json, or run.json items no trace file binds). The participant then has no
+     * thought or thought count.
+     */
+    evidenceUnavailable?: string;
 }
 export interface RunDetail {
     automaticAnalysis?: AutomaticAnalysisView;

package/dist/run/detail.js

@@ -16,6 +16,7 @@ import { savedCaption } from "./participant-caption.js";
 import { recordedPersonaId, streamParticipantIdOf } from "./participant-records.js";
 import { ContainedReadRefusedError, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { isPathInside, resolvePhysicalCwd } from "./paths.js";
+import { displayedTraces, loadStreamTraces } from "./stream-trace.js";
 const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
 /**
  * The latest reasoning a participant has recorded.
@@ -72,6 +73,9 @@ function participantFrom(stream, index, savedPersonaId) {
         ...(typeof trace.counts?.actions === "number" ? { actions: trace.counts.actions } : {}),
         ...(thoughts > 0 ? { thoughts } : {}),
         ...costOf(trace),
+        ...(stream.traceUnavailable === undefined
+            ? {}
+            : { evidenceUnavailable: stream.traceUnavailable }),
     };
 }
 /**
@@ -103,6 +107,15 @@ function costOf(trace) {
         return {};
     }
 }
+/**
+ * The run's streams with their traces loaded through the loader and its bundle rules, as a screen
+ * shows them: a participant whose trace the loader refused carries the reason and none of the
+ * items run.json or a file supplied for it.
+ */
+async function displayedStreams(runPaths, streams, bundle) {
+    const loaded = await loadStreamTraces(runPaths, { ...bundle, streams });
+    return displayedTraces(loaded).streams;
+}
 /**
  * Read one run's participants. Returns null when the run has no readable bundle yet, an ordinary
  * state for a run that has just started, not a failure. Throws when run.json is there and cannot
@@ -138,7 +151,7 @@ export async function readRunDetail(cwdInput, runId) {
         // Absent or torn: the run has not written one yet, or is writing it now.
         return null;
     }
-    const streams = Array.isArray(bundle.streams) ? bundle.streams : [];
+    const streams = await displayedStreams(runPaths, Array.isArray(bundle.streams) ? bundle.streams : [], bundle);
     const observerAbsolute = path.join(runPaths.absoluteRunRoot, "observer", "index.html");
     const automaticAnalysis = await readAutomaticAnalysis(cwd, runId);
     return {

package/dist/run/locate.js

@@ -3,6 +3,7 @@ import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDir
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, ContainedReadRefusedError, LATEST_POINTER_MAX_BYTES, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isRunBundle, isRunPointer } from "./bundle-shape.js";
+import { loadRunTraces } from "./stream-trace.js";
 import { readUnchangedFile } from "./evidence-files.js";
 /** The run input that resolves through latest.json rather than naming a run directory. */
 export const LATEST_RUN_ALIAS = "latest";
@@ -122,7 +123,8 @@ export async function loadRunBundlePrepared(cwdInput, runPaths) {
         return null;
     }
     return {
-        bundle,
+        // A trace that does not match its index throws StreamTraceRefusedError, naming the participant.
+        bundle: await loadRunTraces(runPaths, bundle),
         bundlePath: path.relative(cwd, bundlePath),
         runDir: runPaths.absoluteRunRoot,
     };

package/dist/run/projection.d.ts

@@ -1,3 +1,4 @@
+import type { RunParticipant } from "./detail.js";
 import type { RunIndexEntry } from "./run-index.js";
 /** One study as the study list shows it. */
 export interface StudyRollup {
@@ -72,6 +73,12 @@ export interface NormalizedThought {
     /** True when the source text did not fit and was cut; shown, never silent. */
     truncated: boolean;
 }
+/**
+ * What a screen quotes for a participant of a run detail: why its evidence is unavailable, else
+ * its latest thought. It lives here, beside normalizeThought, so the TUI bundle does not load the
+ * run-detail reader.
+ */
+export declare function participantNote(participant: Pick<RunParticipant, "evidenceUnavailable" | "thought">): string | undefined;
 /**
  * Prepare a participant's recorded reasoning summary for a fixed-width surface. Provider summaries
  * arrive with markdown section leads (`**Thinking through setup**`) and hard newlines; a terminal

package/dist/run/projection.js

@@ -162,6 +162,16 @@ export function formatDuration(ms) {
     const hours = Math.floor(minutes / 60);
     return minutes % 60 === 0 ? `${hours}h` : `${hours}h ${minutes % 60}m`;
 }
+/**
+ * What a screen quotes for a participant of a run detail: why its evidence is unavailable, else
+ * its latest thought. It lives here, beside normalizeThought, so the TUI bundle does not load the
+ * run-detail reader.
+ */
+export function participantNote(participant) {
+    return participant.evidenceUnavailable === undefined
+        ? participant.thought?.text
+        : `Evidence unavailable: ${participant.evidenceUnavailable}`;
+}
 /**
  * Prepare a participant's recorded reasoning summary for a fixed-width surface. Provider summaries
  * arrive with markdown section leads (`**Thinking through setup**`) and hard newlines; a terminal

package/dist/run/run.js

@@ -5,6 +5,7 @@
 import { randomBytes } from "node:crypto";
 import { redactText } from "../evidence/redaction.js";
 import { buildObserverData } from "../observer/data.js";
+import { splitObserverData } from "../observer/participant-items.js";
 import { renderObserver } from "../observer/render.js";
 import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, buildRunSource, } from "./bundle.js";
 import { judgeExecution, } from "./judge.js";
@@ -17,6 +18,7 @@ import { RunSecrets } from "./secrets.js";
 import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
 import { readRunJsonIfExists, runJsonValue } from "./locate.js";
 import { hostSuspensionEvents, systemHostClock, } from "./host-suspension.js";
+import { splitStreamTraces } from "./stream-trace.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";
@@ -171,7 +173,12 @@ function runPublisher(args) {
             cwd: PUBLIC_TARGET_CWD,
             ...(recorded === undefined ? {} : { outcome: recorded }),
         });
-        await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(publicBundle), "utf8");
+        // Each trace file first, so run.json never indexes a file that is not yet written. The review
+        // and the Observer data below read the whole in-memory bundle.
+        const split = splitStreamTraces(publicBundle);
+        for (const file of split.files)
+            await writeContainedOutputFile(paths, file.path, file.bytes);
+        await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(split.bundle), "utf8");
         await afterBundle(publicBundle);
         // The run writes its own status.json; one it refuses renders as a missing one does.
         const status = recorded === undefined
@@ -181,7 +188,7 @@ function runPublisher(args) {
         await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle, status), "utf8");
         const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");
         await writeContainedOutputFile(paths, "events.ndjson", `${events}\n`, "utf8");
-        await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle, undefined, status)), "utf8");
+        await writeContainedOutputFile(paths, "observer/observer-data.json", json(splitObserverData(buildObserverData(publicBundle, undefined, status)).shell), "utf8");
     };
     const snapshot = async (bundle) => {
         await writeBundleFiles(bundle, undefined, async () => { });

package/dist/run/stored-runs.js

@@ -4,11 +4,12 @@ import { redactText } from "../evidence/redaction.js";
 import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, } from "./paths.js";
 import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, refusalText, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
-import { isReviewSummary, isRunOutcome } from "./bundle-shape.js";
+import { isReviewSummary, isRunBundle, isRunOutcome } from "./bundle-shape.js";
 import { bundleDisplayFacts, displayedReview, runDisplay, } from "./display.js";
 import { RUN_STATUS_FILE } from "./status.js";
 import { readLatest, readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { withCuaReviewProvenance } from "./outcomes.js";
+import { displayedTraces, loadStreamTraces } from "./stream-trace.js";
 import { isNodeError, isRecord } from "./type-guards.js";
 import { invalidRunStorageVerifyResult, verifyResolvedRun, } from "../verify/verify.js";
 const RUNS_SCHEMA = "humanish.runs-result.v1";
@@ -174,9 +175,14 @@ export async function readReview(cwdInput, runInput) {
     const bundle = runPaths
         ? runJsonValue(await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE))
         : null;
-    const projected = isRecord(bundle) && Array.isArray(bundle.streams)
-        ? withCuaReviewProvenance(review, bundle.streams.filter(isRecord))
-        : review;
+    // The completion provenance reads each participant's items, loaded through the loader; a
+    // participant whose trace it refused counts without them.
+    const streams = runPaths && isRunBundle(bundle)
+        ? displayedTraces(await loadStreamTraces(runPaths, bundle)).streams
+        : isRecord(bundle) && Array.isArray(bundle.streams)
+            ? bundle.streams.filter(isRecord)
+            : undefined;
+    const projected = streams ? withCuaReviewProvenance(review, streams) : review;
     const displayed = displayedBundle(bundle);
     const { display } = runPaths ? await listedRunDisplay(runPaths, bundle) : {};
     return {

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

@@ -1,4 +1,14 @@
-import { type RunSimulationStatus, type RunStream, type RunStreamKind } from "./streams.js";
+import { type RunSimulationStatus, type RunStream, type RunStreamKind, type StreamTraceIndex } from "./streams.js";
 export declare function isRunStream(value: unknown): value is RunStream;
+export declare function isRunStreamArtifact(value: unknown): value is RunStream["artifacts"][number];
+/**
+ * The trace file names the run writer produces: actor.json for one participant,
+ * actors/<stream>.json for more, actor-<surface>.json on the scripted route. A trace is source
+ * evidence, so an index naming any other file (the Observer page, which the public-safety scan
+ * reads as a regenerated projection) is refused by the shape check and by the loader.
+ */
+export declare function isStreamTracePath(value: string): boolean;
+/** A v2 stream's index of its trace file: a local path, its size and sha256, and what it holds. */
+export declare function isStreamTraceIndex(value: unknown): value is StreamTraceIndex;
 export declare function isRunSimulationStatus(value: unknown): value is RunSimulationStatus;
 export declare function isRunStreamKind(value: unknown): value is RunStreamKind;

package/dist/run/stream-shape.js

@@ -2,7 +2,7 @@
 import { desktopRecordingMetadataSchema, } from "../evidence/desktop-recording-types.js";
 import { isLocalEvidenceArtifactPath } from "./paths.js";
 import {} from "./streams.js";
-import { isFiniteNumber, isPositiveFiniteNumber, isRecord } from "./type-guards.js";
+import { isFiniteNumber, isNonNegativeSafeInteger, isPositiveFiniteNumber, isRecord, } from "./type-guards.js";
 export function isRunStream(value) {
     return (isRecord(value) &&
         typeof value.id === "string" &&
@@ -21,6 +21,7 @@ export function isRunStream(value) {
         (value.desktopGeometry === undefined || isRunDesktopGeometry(value.desktopGeometry)) &&
         (value.recording === undefined || isRunDesktopRecording(value.recording)) &&
         hasConsistentStreamGeometry(value) &&
+        (value.trace === undefined || isStreamTraceIndex(value.trace)) &&
         Array.isArray(value.artifacts) &&
         value.artifacts.every(isRunStreamArtifact) &&
         hasConsistentRecordingArtifact(value.recording, value.artifacts));
@@ -120,7 +121,7 @@ function hasConsistentStreamGeometry(value) {
 function isMeasuredSize(value) {
     return (isRecord(value) && isPositiveFiniteNumber(value.width) && isPositiveFiniteNumber(value.height));
 }
-function isRunStreamArtifact(value) {
+export function isRunStreamArtifact(value) {
     return (isRecord(value) &&
         typeof value.label === "string" &&
         typeof value.path === "string" &&
@@ -134,6 +135,29 @@ function isRunStreamArtifact(value) {
             value.kind === "filesystem" ||
             value.kind === "recording"));
 }
+/** A name part of a trace file: a stream id or surface id that is a plain file name. */
+const TRACE_NAME = "[A-Za-z0-9][A-Za-z0-9._-]{0,127}";
+const TRACE_FILE = new RegExp(`^(?:actor|actor-${TRACE_NAME}|actors/${TRACE_NAME})\\.json$`);
+/**
+ * The trace file names the run writer produces: actor.json for one participant,
+ * actors/<stream>.json for more, actor-<surface>.json on the scripted route. A trace is source
+ * evidence, so an index naming any other file (the Observer page, which the public-safety scan
+ * reads as a regenerated projection) is refused by the shape check and by the loader.
+ */
+export function isStreamTracePath(value) {
+    return TRACE_FILE.test(value);
+}
+/** A v2 stream's index of its trace file: a local path, its size and sha256, and what it holds. */
+export function isStreamTraceIndex(value) {
+    return (isRecord(value) &&
+        typeof value.path === "string" &&
+        isStreamTracePath(value.path) &&
+        isNonNegativeSafeInteger(value.bytes) &&
+        typeof value.sha256 === "string" &&
+        /^[0-9a-f]{64}$/.test(value.sha256) &&
+        isNonNegativeSafeInteger(value.items) &&
+        isNonNegativeSafeInteger(value.screenshots));
+}
 export function isRunSimulationStatus(value) {
     return (value === "queued" ||
         value === "preparing" ||

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

@@ -0,0 +1,68 @@
+import { type RunBundle } from "./bundle.js";
+import { type PreparedOutputRoot } from "./contained-output.js";
+import type { RunStream } from "./streams.js";
+/** A trace that does not match its index, or cannot be read. The message names the stream. */
+export declare class StreamTraceRefusedError extends Error {
+    readonly streamId: string;
+    constructor(streamId: string, detail: string);
+}
+/**
+ * The run.json the run writes, and the trace files it writes first. Each stream with a finished
+ * actor keeps that actor without `items`, its artifacts other than screenshots, and an index of its
+ * trace file; the file is the actor trace with the stream's screenshot entries as `artifacts`. A
+ * stream already split (its actor read back from a v2 run.json without its items) keeps its index,
+ * since its file is on disk.
+ */
+export declare function splitStreamTraces(bundle: RunBundle): {
+    bundle: RunBundle;
+    files: {
+        path: string;
+        bytes: Buffer;
+    }[];
+};
+/**
+ * Where a loader reads trace files from: the bytes at a run-relative path, at most `maxBytes`, or
+ * why it could not. Prepared run paths read through the contained reader; the Observer server
+ * passes a reader over its pinned run folder.
+ */
+export type TraceFileReader = (relativePath: string, maxBytes: number) => Promise<{
+    bytes: Buffer;
+} | {
+    refused: string;
+}>;
+/**
+ * The stream as a v1 run.json held it: its actor with every item and every artifact entry. A
+ * 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
+ * actor, two participants indexing one file) are loadStreamTraces'.
+ */
+export declare function loadStreamTrace(runPaths: PreparedOutputRoot, stream: RunStream, maxBytes?: number): Promise<RunStream>;
+/**
+ * Every stream of the bundle loaded through loadStreamTrace, one file at a time, and the refusal
+ * of each stream that could not be (see bundleRefusal for the rules that need the whole bundle).
+ * Each refused stream is kept as run.json holds it; a reader that shows the run passes the result
+ * to displayedTraces. `source` is the run's prepared paths, or a TraceFileReader. `onTrace`
+ * receives each trace file's path and the bytes the stream was joined from, after they matched
+ * the index, so a caller scans exactly what it reads.
+ */
+export declare function loadStreamTraces(source: PreparedOutputRoot | TraceFileReader, bundle: RunBundle, options?: {
+    maxBytes?: number;
+    onTrace?: (path: string, bytes: Buffer) => void;
+}): Promise<{
+    bundle: RunBundle;
+    refused: StreamTraceRefusedError[];
+}>;
+/**
+ * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's
+ * summary, shows none of the items run.json or a file supplied for it (its actor's items, its
+ * in-progress items, its screenshot entries), and carries `traceUnavailable` with the reason; a
+ * warn event on its timeline says the same.
+ */
+export declare function displayedTraces(loaded: {
+    bundle: RunBundle;
+    refused: readonly StreamTraceRefusedError[];
+}): RunBundle;
+/** The bundle with every stream loaded; the first refusal throws. */
+export declare function loadRunTraces(source: PreparedOutputRoot | TraceFileReader, bundle: RunBundle, maxBytes?: number): Promise<RunBundle>;

package/dist/run/stream-trace.js

@@ -0,0 +1,260 @@
+// Where a participant's trace lives. A v1 run.json holds every stream's trace items and screenshot
+// entries inline. From v2 the run writer moves them into one file per stream and leaves an index
+// in run.json, so run.json stays a summary whatever the length of the sessions. Every reader that
+// needs the items loads them here, which accepts both versions and checks a file against its index.
+import { createHash } from "node:crypto";
+import { RUN_BUNDLE_SCHEMA } from "./bundle.js";
+import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.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. */
+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.`);
+        this.streamId = streamId;
+        this.name = "StreamTraceRefusedError";
+    }
+}
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const isScreenshot = (artifact) => artifact.kind === "screenshot";
+/**
+ * The file a trace path names on any file system. Trace file names are ASCII (isStreamTracePath),
+ * so lower case folds them as a case-insensitive file system does: actors/Case.json and
+ * actors/case.json are one file there.
+ */
+const traceFileKey = (tracePath) => tracePath.toLowerCase();
+/** Names of the form actors/<n>.json, which the splitter gives by position and never reuses. */
+const POSITION_TRACE_FILE = /^actors\/\d+\.json$/;
+/**
+ * The stream's actor trace artifact (actor.json, actors/<stream>.json, actor-<surface>.json) when
+ * no earlier stream claimed it (compared by traceFileKey), else actors/<position>.json. The
+ * position names are a namespace of their own: an artifact named that way is not reused, so two
+ * streams never get one file. Another trace artifact (the scripted route's traces/<surface>.json
+ * holds its native step trace) keeps its own file.
+ */
+function tracePath(stream, index, claimed) {
+    const own = stream.artifacts.find((artifact) => artifact.kind === "trace" &&
+        isStreamTracePath(artifact.path) &&
+        !POSITION_TRACE_FILE.test(artifact.path))?.path;
+    return own !== undefined && !claimed.has(traceFileKey(own)) ? own : `actors/${index + 1}.json`;
+}
+/**
+ * The run.json the run writes, and the trace files it writes first. Each stream with a finished
+ * actor keeps that actor without `items`, its artifacts other than screenshots, and an index of its
+ * trace file; the file is the actor trace with the stream's screenshot entries as `artifacts`. A
+ * stream already split (its actor read back from a v2 run.json without its items) keeps its index,
+ * since its file is on disk.
+ */
+export function splitStreamTraces(bundle) {
+    const files = [];
+    const claimed = new Set();
+    for (const stream of bundle.streams)
+        if (stream.trace)
+            claimed.add(traceFileKey(stream.trace.path));
+    const streams = bundle.streams.map((stream, index) => {
+        const actor = stream.actor;
+        if (actor === undefined || !Array.isArray(actor.items))
+            return stream;
+        const { trace: _previous, ...rest } = stream;
+        const filePath = tracePath(rest, index, claimed);
+        // Only a stream already split that moved position can hold this stream's position name.
+        if (claimed.has(traceFileKey(filePath)))
+            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`);
+        files.push({ path: filePath, bytes });
+        const { items, ...summary } = actor;
+        return {
+            ...rest,
+            // run.json's actor is the summary: every field of the trace except its items.
+            actor: summary,
+            artifacts: stream.artifacts.filter((artifact) => !isScreenshot(artifact)),
+            trace: {
+                path: filePath,
+                bytes: bytes.length,
+                sha256: sha256(bytes),
+                items: items.length,
+                screenshots: screenshots.length,
+            },
+        };
+    });
+    return { bundle: { ...bundle, schema: RUN_BUNDLE_SCHEMA, streams }, files };
+}
+function containedReader(runPaths) {
+    return async (relativePath, maxBytes) => {
+        const read = await readContainedRegularFile(runPaths, relativePath, maxBytes);
+        if (read.status === "missing")
+            return { refused: `${relativePath} is missing` };
+        if (read.status === "refused")
+            return { refused: refusalText(relativePath, read) };
+        return { bytes: read.bytes };
+    };
+}
+/**
+ * The stream from the bytes of its trace file: its actor with the file's items, and its artifacts
+ * followed by the file's screenshot entries, without the index.
+ */
+function joinTrace(stream, bytes) {
+    const index = stream.trace;
+    const refuse = (detail) => {
+        throw new StreamTraceRefusedError(stream.id, detail);
+    };
+    if (bytes.length !== index.bytes)
+        refuse(`${index.path} holds ${bytes.length} bytes and run.json records ${index.bytes} bytes`);
+    if (sha256(bytes) !== index.sha256)
+        refuse(`${index.path} does not match the sha256 run.json records for it`);
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        refuse(`${index.path} is not JSON`);
+    }
+    if (!isRecord(value) || !Array.isArray(value.items) || !Array.isArray(value.artifacts))
+        return refuse(`${index.path} has no items or artifacts list`);
+    const artifacts = value.artifacts;
+    if (!artifacts.every((artifact) => isRunStreamArtifact(artifact) && isScreenshot(artifact)))
+        refuse(`${index.path} lists an artifact that is not a screenshot entry`);
+    if (value.items.length !== index.items || artifacts.length !== index.screenshots)
+        refuse(`${index.path} holds ${value.items.length} items and ${artifacts.length} screenshots and run.json records ${index.items} and ${index.screenshots}`);
+    const { trace: _index, ...rest } = stream;
+    return {
+        ...rest,
+        actor: { ...stream.actor, items: value.items },
+        artifacts: [...stream.artifacts, ...artifacts],
+    };
+}
+/** Refuses an index the shape check would refuse, naming a file that is not a trace file name. */
+function assertIndex(stream) {
+    const index = stream.trace;
+    if (isRecord(index) && typeof index.path === "string" && !isStreamTracePath(index.path))
+        throw new StreamTraceRefusedError(stream.id, `run.json indexes ${index.path}, which is not a trace file name (actor.json, actors/<stream>.json or actor-<surface>.json)`);
+    if (!isStreamTraceIndex(index) || stream.actor === undefined)
+        throw new StreamTraceRefusedError(stream.id, "run.json records a malformed trace index");
+    if (stream.actor.items !== undefined)
+        throw new StreamTraceRefusedError(stream.id, "run.json holds items beside its trace index");
+}
+/** The stream with its trace joined, and the bytes it was joined from when it has an index. */
+async function readStreamTrace(read, stream, maxBytes) {
+    if (stream.trace === undefined)
+        return { stream };
+    assertIndex(stream);
+    const file = await read(stream.trace.path, maxBytes);
+    if ("refused" in file)
+        throw new StreamTraceRefusedError(stream.id, file.refused);
+    return { stream: joinTrace(stream, file.bytes), bytes: file.bytes };
+}
+/**
+ * The stream as a v1 run.json held it: its actor with every item and every artifact entry. A
+ * 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
+ * actor, two participants indexing one file) are loadStreamTraces'.
+ */
+export async function loadStreamTrace(runPaths, stream, maxBytes = RUN_ARTIFACT_MAX_BYTES) {
+    return (await readStreamTrace(containedReader(runPaths), stream, maxBytes)).stream;
+}
+/**
+ * Why a stream of this bundle cannot be read, before any file is. A trace file belongs to one
+ * participant, so every stream indexing a path another stream indexes, compared as a
+ * case-insensitive file system compares them, is refused. In v2 the writer
+ * indexes every actor on every write, mid-run flushes included, so a v2 actor without an index lost
+ * its trace file, and inline items never come from the writer. A run still writing carries its
+ * participants' items so far as `liveActor` (humanish.live-actor.v1), which no index binds; a
+ * run.json whose outcome says the run finished never does, since the final write replaces it.
+ */
+function bundleRefusal(bundle, stream, owners) {
+    const shared = isRecord(stream.trace)
+        ? owners.get(traceFileKey(String(stream.trace.path)))
+        : undefined;
+    if (shared !== undefined && shared.length > 1)
+        return `run.json indexes ${String(stream.trace.path)} for participants ${shared.join(", ")} (paths that differ only in case name one file on some file systems), and a trace file belongs to one participant`;
+    if (bundle.schema !== RUN_BUNDLE_SCHEMA)
+        return undefined;
+    if (stream.actor !== undefined && stream.trace === undefined)
+        return "run.json holds its actor and names no trace file";
+    if (stream.liveActor !== undefined && bundle.outcome?.state === "finished")
+        return "run.json records a finished run and still holds in-progress items";
+    return undefined;
+}
+/**
+ * Every stream of the bundle loaded through loadStreamTrace, one file at a time, and the refusal
+ * of each stream that could not be (see bundleRefusal for the rules that need the whole bundle).
+ * Each refused stream is kept as run.json holds it; a reader that shows the run passes the result
+ * to displayedTraces. `source` is the run's prepared paths, or a TraceFileReader. `onTrace`
+ * receives each trace file's path and the bytes the stream was joined from, after they matched
+ * the index, so a caller scans exactly what it reads.
+ */
+export async function loadStreamTraces(source, bundle, options = {}) {
+    const read = typeof source === "function" ? source : containedReader(source);
+    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]);
+        }
+    const streams = [];
+    const refused = [];
+    for (const stream of bundle.streams) {
+        try {
+            const reason = bundleRefusal(bundle, stream, owners);
+            if (reason !== undefined)
+                throw new StreamTraceRefusedError(stream.id, reason);
+            const loaded = await readStreamTrace(read, stream, options.maxBytes ?? RUN_ARTIFACT_MAX_BYTES);
+            if (loaded.bytes !== undefined)
+                options.onTrace?.(stream.trace.path, loaded.bytes);
+            streams.push(loaded.stream);
+        }
+        catch (error) {
+            if (!(error instanceof StreamTraceRefusedError))
+                throw error;
+            refused.push(error);
+            streams.push(stream);
+        }
+    }
+    return { bundle: { ...bundle, streams }, refused };
+}
+/**
+ * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's
+ * summary, shows none of the items run.json or a file supplied for it (its actor's items, its
+ * in-progress items, its screenshot entries), and carries `traceUnavailable` with the reason; a
+ * warn event on its timeline says the same.
+ */
+export function displayedTraces(loaded) {
+    const reasons = new Map(loaded.refused.map((error) => [error.streamId, error.message]));
+    if (reasons.size === 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 {
+            ...rest,
+            ...(actor === undefined ? {} : { actor: { ...actor, items: [] } }),
+            artifacts: stream.artifacts.filter((artifact) => !isScreenshot(artifact)),
+            traceUnavailable: reason,
+        };
+    });
+    const events = loaded.bundle.streams
+        .filter((stream) => reasons.has(stream.id))
+        .map((stream) => ({
+        id: `event-trace-unavailable-${stream.id}`,
+        at: stream.updatedAt,
+        level: "warn",
+        type: "trace.unavailable",
+        message: reasons.get(stream.id),
+        streamId: stream.id,
+    }));
+    return { ...loaded.bundle, streams, events: [...loaded.bundle.events, ...events] };
+}
+/** The bundle with every stream loaded; the first refusal throws. */
+export async function loadRunTraces(source, bundle, maxBytes) {
+    const loaded = await loadStreamTraces(source, bundle, maxBytes === undefined ? {} : { maxBytes });
+    if (loaded.refused[0])
+        throw loaded.refused[0];
+    return loaded.bundle;
+}