humanish 0.124.0 → 0.125.0

package/dist/run/stream-trace.js

@@ -1,10 +1,14 @@
 // 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.
+// in run.json, so run.json stays a summary whatever the length of the sessions. From v3 a running
+// participant's items so far are in a live file run.json indexes too (src/run/live-items.ts).
+// Every reader that needs the items loads them here, which accepts every version and checks each
+// 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 { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V2_SCHEMA, } from "./bundle.js";
+import { isRunBundle } from "./bundle-shape.js";
+import { readContainedPrefix, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
+import { isLiveItemsIndex, LIVE_ACTOR_SCHEMA, LIVE_ACTOR_V1_SCHEMA, liveItemsFromBytes, } from "./live-items.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. */
@@ -83,8 +87,10 @@ export function splitStreamTraces(bundle) {
     return { bundle: { ...bundle, schema: RUN_BUNDLE_SCHEMA, streams }, files };
 }
 function containedReader(runPaths) {
-    return async (relativePath, maxBytes) => {
-        const read = await readContainedRegularFile(runPaths, relativePath, maxBytes);
+    return async (relativePath, maxBytes, length) => {
+        const read = length === undefined
+            ? await readContainedRegularFile(runPaths, relativePath, maxBytes)
+            : await readContainedPrefix(runPaths, relativePath, length);
         if (read.status === "missing")
             return { refused: `${relativePath} is missing` };
         if (read.status === "refused")
@@ -136,15 +142,64 @@ function assertIndex(stream) {
     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)
+/** 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. */
+class LiveFileUnreadableError extends StreamTraceRefusedError {
+}
+/**
+ * The stream with its live actor's items joined from the indexed prefix of its live file, and the
+ * file's path and those bytes. A live actor with inline items (humanish.live-actor.v1) is returned
+ * as it is; bundleRefusal refuses one in a v3 run.json.
+ */
+async function readLiveItems(read, stream, maxBytes) {
+    const live = stream.liveActor;
+    if (live === undefined || isInlineLiveActor(live))
         return { stream };
-    assertIndex(stream);
-    const file = await read(stream.trace.path, maxBytes);
+    const refuse = (detail) => {
+        throw new StreamTraceRefusedError(stream.id, detail);
+    };
+    if (live.schema !== LIVE_ACTOR_SCHEMA)
+        refuse(`run.json records live actor schema ${String(live.schema)}, which this version does not read`);
+    const index = live.itemsFile;
+    if (!isLiveItemsIndex(index))
+        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 file = await read(index.path, maxBytes, index.bytes);
     if ("refused" in file)
-        throw new StreamTraceRefusedError(stream.id, file.refused);
-    return { stream: joinTrace(stream, file.bytes), bytes: file.bytes };
+        throw new LiveFileUnreadableError(stream.id, file.refused);
+    // Only the indexed prefix: a reader that ignores `length` hands over the bytes appended since.
+    const joined = liveItemsFromBytes(file.bytes.subarray(0, index.bytes), index);
+    if ("refused" in joined)
+        return refuse(joined.refused);
+    const { itemsFile: _index, ...summary } = live;
+    return {
+        stream: { ...stream, liveActor: { ...summary, items: joined.items } },
+        live: { path: index.path, bytes: file.bytes.subarray(0, index.bytes) },
+    };
+}
+/**
+ * The stream with its trace and live items joined, and each file's path and the bytes it was
+ * joined from.
+ */
+async function readStreamTrace(read, stream, maxBytes) {
+    const files = [];
+    let joined = stream;
+    if (stream.trace !== undefined) {
+        assertIndex(stream);
+        const file = await read(stream.trace.path, maxBytes);
+        if ("refused" in file)
+            throw new StreamTraceRefusedError(stream.id, file.refused);
+        joined = joinTrace(stream, file.bytes);
+        files.push({ path: stream.trace.path, bytes: file.bytes });
+    }
+    const live = await readLiveItems(read, joined, maxBytes);
+    if (live.live !== undefined)
+        files.push(live.live);
+    return { stream: live.stream, files };
 }
 /**
  * The stream as a v1 run.json held it: its actor with every item and every artifact entry. A
@@ -163,8 +218,10 @@ export async function loadStreamTrace(runPaths, stream, maxBytes = RUN_ARTIFACT_
  * 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.
+ * participants' items so far as `liveActor`: inline in v2 (humanish.live-actor.v1), in a live file
+ * from v3 (humanish.live-actor.v2), so a v3 run.json with inline live items did not come from the
+ * writer. A run.json whose outcome says the run finished never carries `liveActor`, since the
+ * final write replaces it.
  */
 function bundleRefusal(bundle, stream, owners) {
     const shared = isRecord(stream.trace)
@@ -172,12 +229,16 @@ function bundleRefusal(bundle, stream, owners) {
         : 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)
+    if (bundle.schema !== RUN_BUNDLE_SCHEMA && bundle.schema !== RUN_BUNDLE_V2_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";
+    if (bundle.schema === RUN_BUNDLE_SCHEMA &&
+        stream.liveActor !== undefined &&
+        isInlineLiveActor(stream.liveActor))
+        return "run.json v3 holds in-progress items inline, which the writer keeps in a live file";
     return undefined;
 }
 /**
@@ -185,11 +246,41 @@ function bundleRefusal(bundle, stream, owners) {
  * 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.
+ * receives each trace and live file's path and the bytes the stream was joined from, after they
+ * matched the index, so a caller scans exactly what it reads.
+ *
+ * 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
+ * run finished. The loader then reads run.json again, once, through the same reader, and loads
+ * that bundle instead when it is a run bundle of the same run.
  */
 export async function loadStreamTraces(source, bundle, options = {}) {
     const read = typeof source === "function" ? source : containedReader(source);
+    const maxBytes = options.maxBytes ?? RUN_ARTIFACT_MAX_BYTES;
+    let loaded = await loadEveryStream(read, bundle, maxBytes);
+    if (loaded.refused.some((error) => error instanceof LiveFileUnreadableError)) {
+        const current = await rereadBundle(read, bundle.runId);
+        if (current !== undefined)
+            loaded = await loadEveryStream(read, current, maxBytes);
+    }
+    for (const file of loaded.files)
+        options.onTrace?.(file.path, file.bytes);
+    return { bundle: loaded.bundle, refused: loaded.refused };
+}
+/** run.json as it is now, when it is a run bundle of run `runId`. */
+async function rereadBundle(read, runId) {
+    const file = await read(RUN_BUNDLE_FILE, RUN_ARTIFACT_MAX_BYTES);
+    if ("refused" in file)
+        return undefined;
+    try {
+        const value = JSON.parse(file.bytes.toString("utf8"));
+        return isRunBundle(value) && value.runId === runId ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function loadEveryStream(read, bundle, maxBytes) {
     const owners = new Map();
     for (const stream of bundle.streams)
         if (isRecord(stream.trace)) {
@@ -198,14 +289,14 @@ export async function loadStreamTraces(source, bundle, options = {}) {
         }
     const streams = [];
     const refused = [];
+    const files = [];
     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);
+            const loaded = await readStreamTrace(read, stream, maxBytes);
+            files.push(...loaded.files);
             streams.push(loaded.stream);
         }
         catch (error) {
@@ -215,7 +306,7 @@ export async function loadStreamTraces(source, bundle, options = {}) {
             streams.push(stream);
         }
     }
-    return { bundle: { ...bundle, streams }, refused };
+    return { bundle: { ...bundle, streams }, refused, files };
 }
 /**
  * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's

package/dist/run/streams.d.ts

@@ -154,6 +154,18 @@ export interface StreamTraceIndex {
     items: number;
     screenshots: number;
 }
+/**
+ * A v3 run.json's index of a running participant's live file (src/run/live-items.ts): its path
+ * `live/<position>.<generation>.ndjson`, the generation, and the prefix written so far, as its item
+ * (line) count, byte count and sha256. The file only grows, so the prefix stays as indexed.
+ */
+export interface LiveItemsIndex {
+    path: string;
+    generation: number;
+    items: number;
+    bytes: number;
+    sha256: string;
+}
 /** The original participant-facing assignment, before runtime access/coordination details. */
 export interface RunParticipantAssignment {
     mission: string;
@@ -260,10 +272,11 @@ export interface RunStream {
      * grow. It is deliberately not an ActorTrace: a running participant has no final status,
      * completionReason, or completedAt, and this shape cannot claim them. Present only on
      * `inProgress` bundles; the final write replaces it with the real `actor` and never
-     * carries it.
+     * carries it. A v3 run.json holds `humanish.live-actor.v2` with `itemsFile` in place of `items`;
+     * the trace loader (src/run/stream-trace.ts) reads the file and puts the items back.
      */
     liveActor?: {
-        schema: "humanish.live-actor.v1";
+        schema: "humanish.live-actor.v1" | "humanish.live-actor.v2";
         executionProfile?: ActorTrace["executionProfile"];
         providerRequests?: ActorTrace["providerRequests"];
         historyTurnsOmitted?: number;
@@ -273,6 +286,8 @@ export interface RunStream {
         /** When this flush was written (ISO-8601). */
         updatedAt: string;
         items: ActorTraceItem[];
+        /** In a v3 run.json, in place of `items`: the live file that holds them. */
+        itemsFile?: LiveItemsIndex;
     };
     completion?: RunStreamCompletion;
     recording?: RunDesktopRecording;

package/dist/study/parse/actors.js

@@ -7,6 +7,7 @@ import { entryCredentialReason, urlCredentialReason } from "./url-credentials.js
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
 import { invalid, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
+import { scanEncodedText } from "../../evidence/encoded-text.js";
 import { isStartAfterMs, startAfterMessage, windowReason } from "../arrivals.js";
 // A participant id interpolates into its evidence paths (screenshots/<id>/, actors/<id>.json), so
 // it must be a public-safe path token, same shape as a study id.
@@ -36,15 +37,29 @@ export function parseActorType(entry, path) {
     }
     return { ok: true, value: type };
 }
+/**
+ * A persona id. It names the persona file `humanish/personas/<id>.yaml`, and the run records it, so
+ * text verify would flag, as written or encoded, is refused here: redacting it would name a
+ * different file.
+ */
+function parsePersonaId(raw, path) {
+    const persona = str(raw);
+    if (persona !== undefined && scanEncodedText(persona).sensitive) {
+        return invalid(`\`${path}\` looks like a secret or a local path, and the run records it. A persona id names the persona file humanish/personas/<id>.yaml: use a plain file name such as skeptical-shopper, and put the persona's details in that file.`);
+    }
+    return { ok: true, value: persona };
+}
 /**
  * Every actor key other than `type`. The parser reads them after the participant entries, so a file
  * with errors in both reports the entry first.
  */
 export function parseActorFields(entry, path) {
     const actor = {};
-    const persona = str(entry.persona);
-    if (persona)
-        actor.persona = persona;
+    const persona = parsePersonaId(entry.persona, `${path}.persona`);
+    if (!persona.ok)
+        return persona;
+    if (persona.value !== undefined)
+        actor.persona = persona.value;
     const mission = str(entry.mission);
     if (mission)
         actor.mission = mission;
@@ -141,9 +156,11 @@ export function parseParticipantEntries(raw, paths) {
             }
             parsedEntry.device = device;
         }
-        const persona = str(entry.persona);
-        if (persona !== undefined)
-            parsedEntry.persona = persona;
+        const persona = parsePersonaId(entry.persona, `${paths.entry(entryIndex)}.persona`);
+        if (!persona.ok)
+            return persona;
+        if (persona.value !== undefined)
+            parsedEntry.persona = persona.value;
         const actorType = parseEntryMetadata(entry.actorType, `${paths.entry(entryIndex)}.actorType`);
         if (!actorType.ok)
             return actorType;

package/dist/study/parse/execution.js

@@ -3,6 +3,7 @@ import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isExactRuntimeVersion } from "../../routes/terminal/runtime.js";
 import { invalid, nonNegNumber, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
+import { scanEncodedText } from "../../evidence/encoded-text.js";
 export function parseExecution(raw) {
     if (raw === undefined) {
         return { ok: true, value: undefined };
@@ -154,11 +155,16 @@ function parseDesktop(raw) {
     // A custom E2B desktop template name or ID. Trimmed non-empty when present; deliberately not
     // allowlisted (any string is a valid template name/id; over-restricting would reject real
     // adopter images). An explicitly-set but blank/whitespace value is a mistake, not a template.
+    // The run records the template it launched on, so text verify would flag, as written or
+    // encoded, is refused: redacting it in the record would name an image other than the one that ran.
     if (raw.template !== undefined) {
         const template = str(raw.template);
         if (template === undefined) {
             return invalid("`execution.desktop.template` must be a non-empty E2B desktop template name or ID when it is set. Any name is accepted.");
         }
+        if (scanEncodedText(template).sensitive) {
+            return invalid("`execution.desktop.template` looks like a secret or a local path, and the run records the template it launched on. Set it to the E2B template's name or ID only.");
+        }
         desktop.template = template;
     }
     if (typeof raw.codexAppServer === "boolean")

package/dist/study/plan-base.js

@@ -1,6 +1,7 @@
 // What every route planner shares: the plan fields common to all routes, the frozen residual config,
 // and the requirement and subject helpers.
 import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
+import { redactText } from "../evidence/redaction.js";
 // A YAML alias can make a parsed record contain itself (an inline persona that names its own
 // anchor), and structuredClone keeps the cycle, so each object is frozen once.
 function deepFreeze(value, frozen = new WeakSet()) {
@@ -110,7 +111,9 @@ export function planBase(config, input) {
     const analysis = input.analysis?.config;
     return {
         studyId: config.id,
-        ...(config.title === undefined ? {} : { title: config.title }),
+        // Every bundle writer takes the title from here, and review.md, run.json and the Observer show
+        // it, so a key or sandbox URL in it would make verify grade the run blocked.
+        ...(config.title === undefined ? {} : { title: redactText(config.title) }),
         residual: residualOf(config),
         dryRun: input.dryRun,
         ...(analysis === undefined

package/dist/verify/artifacts.js

@@ -1,6 +1,5 @@
 import { lstat, readdir } from "node:fs/promises";
 import path from "node:path";
-import { isRedactedFrameShape, screenshotEvidenceError } from "../evidence/image.js";
 import { isAnalysisRecordPath } from "../analysis/sharing.js";
 import { scanEncodedTextCached } from "../evidence/encoded-text.js";
 import { readPlainText } from "../evidence/plain-text.js";
@@ -9,12 +8,14 @@ import { isLocalEvidenceArtifactPath, isRiskyPublicArtifactPath, validatePrepare
 import { openContainedRegularFile, RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
 import { holdsKeyedSandboxId } from "../run/sandbox-ids.js";
 import { SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
+import { mapWithConcurrency } from "../run/concurrency.js";
 import { runEntryLimit } from "./scan-limit.js";
 import { readSafeRunArtifact, readSafeRunArtifactBytes, readSafeRunArtifactJson, } from "../run/locate.js";
 import { isRecord } from "../run/type-guards.js";
 import { TERMINAL_EVENTS_ARTIFACT } from "../run/terminal-contract.js";
 import { plural } from "../run/text.js";
 import { isZeroEventTerminalTrace } from "./actor.js";
+import { readScreenshot } from "./screenshot-reads.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export const MAX_REPORTED_FINDINGS = 50;
 // The UNSCANNED_ARTIFACT reason names this many paths of each kind and counts the rest.
@@ -108,44 +109,38 @@ export async function missingLocalEvidenceArtifacts(runPaths, bundle) {
             }
         }
     }
-    const missing = [];
-    for (const [artifactPath, requirements] of requiredPaths) {
-        const recording = recordings.get(artifactPath);
-        if (recording) {
-            const handle = await openContainedRegularFile(runPaths, artifactPath);
-            try {
-                if (!handle || (await handle.stat()).size !== recording.bytes)
-                    missing.push(artifactPath);
-                else {
-                    const header = Buffer.alloc(12);
-                    const read = await handle.read(header, 0, header.length, 0);
-                    if (read.bytesRead !== header.length || header.toString("ascii", 4, 8) !== "ftyp")
-                        missing.push(`${artifactPath} (invalid MP4 header)`);
-                }
-            }
-            finally {
-                await handle?.close();
-            }
-            continue;
-        }
-        const artifact = await readSafeRunArtifact(runPaths, artifactPath);
-        if (artifact.state === "limit") {
-            missing.push(`${artifactPath} (larger than the ${RUN_ARTIFACT_MAX_BYTES} bytes verify reads)`);
-            continue;
-        }
-        if (artifact.state === "unavailable" ||
-            (artifact.bytes.length === 0 && !requirements.allowEmpty)) {
-            missing.push(artifactPath);
-            continue;
-        }
-        if (requirements.screenshot) {
-            const imageError = screenshotEvidenceError(artifactPath, artifact.bytes);
-            if (imageError) {
-                missing.push(`${artifactPath} (${imageError})`);
-            }
+    // Reads overlap, so one frame's file system calls run while another frame's PNG is checked.
+    const found = await mapWithConcurrency([...requiredPaths], EVIDENCE_READ_CONCURRENCY, ([artifactPath, requirements]) => missingArtifact(runPaths, artifactPath, requirements, recordings.get(artifactPath)));
+    return found.filter((entry) => entry !== null);
+}
+// Evidence files verify reads at once. Each read holds at most RUN_ARTIFACT_MAX_BYTES.
+const EVIDENCE_READ_CONCURRENCY = 8;
+/** Why one required path fails its requirements, or null when it meets them. */
+async function missingArtifact(runPaths, artifactPath, requirements, recording) {
+    if (recording) {
+        const handle = await openContainedRegularFile(runPaths, artifactPath);
+        try {
+            if (!handle || (await handle.stat()).size !== recording.bytes)
+                return artifactPath;
+            const header = Buffer.alloc(12);
+            const read = await handle.read(header, 0, header.length, 0);
+            return read.bytesRead !== header.length || header.toString("ascii", 4, 8) !== "ftyp"
+                ? `${artifactPath} (invalid MP4 header)`
+                : null;
+        }
+        finally {
+            await handle?.close();
         }
     }
-    return missing;
+    const read = requirements.screenshot
+        ? await readScreenshot(runPaths, artifactPath)
+        : await readSafeRunArtifact(runPaths, artifactPath);
+    if (read.state === "limit")
+        return `${artifactPath} (larger than the ${RUN_ARTIFACT_MAX_BYTES} bytes verify reads)`;
+    if (read.state === "unavailable" ||
+        (("size" in read ? read.size : read.bytes.length) === 0 && !requirements.allowEmpty))
+        return artifactPath;
+    return "error" in read && read.error !== null ? `${artifactPath} (${read.error})` : null;
 }
 function declaredActorScreenshotReferences(stream) {
     const references = [];
@@ -270,20 +265,13 @@ export function rawScreenshotPostureWarnings(bundle, redactedShapeFrames) {
  * (isRedactedFrameShape). A frame that is missing or cannot be read is not in the set.
  */
 export async function redactedShapeFramePaths(runPaths, bundle) {
-    const shaped = new Set();
-    for (const stream of bundle.streams) {
-        for (const reference of declaredActorScreenshotReferences(stream)) {
-            if (!isRunRootEvidenceReference(reference.path))
-                continue;
-            const normalized = normalizedFramePath(reference.path);
-            if (shaped.has(normalized))
-                continue;
-            const bytes = await readSafeRunArtifactBytes(runPaths, normalized).catch(() => null);
-            if (bytes !== null && isRedactedFrameShape(bytes))
-                shaped.add(normalized);
-        }
-    }
-    return shaped;
+    const frames = new Set();
+    for (const stream of bundle.streams)
+        for (const reference of declaredActorScreenshotReferences(stream))
+            if (isRunRootEvidenceReference(reference.path))
+                frames.add(normalizedFramePath(reference.path));
+    const reads = await mapWithConcurrency([...frames], EVIDENCE_READ_CONCURRENCY, (frame) => readScreenshot(runPaths, frame));
+    return new Set([...frames].filter((_, index) => reads[index].state === "read" && reads[index].redactedShape));
 }
 function normalizedFramePath(value) {
     return path.posix.normalize(value.replace(/\\/g, "/"));

package/dist/verify/screenshot-reads.d.ts

@@ -0,0 +1,21 @@
+import type { PreparedRunArtifactPaths } from "../run/paths.js";
+/** What verify needs from a registered screenshot, from one read of its bytes. */
+type ScreenshotRead = {
+    state: "read";
+    size: number;
+    /** screenshotEvidenceError for the path the caller gave. */
+    error: string | null;
+    redactedShape: boolean;
+} | {
+    state: "limit";
+} | {
+    state: "unavailable";
+};
+/**
+ * A registered screenshot's facts: its size, why it is not PNG evidence (null when it is), and
+ * whether it has the redactor's output shape. `relativePath` may use `\`, read as `/`. A frame read
+ * before through the same `runPaths` is not read again while it is still the same file with the
+ * same size and times, and its last change was at least 2 s before that read started.
+ */
+export declare function readScreenshot(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<ScreenshotRead>;
+export {};

package/dist/verify/screenshot-reads.js

@@ -0,0 +1,46 @@
+import { isRedactedFrameShape, screenshotEvidenceError } from "../evidence/image.js";
+import { RUN_ARTIFACT_MAX_BYTES } from "../run/contained-output.js";
+import { isUnchangedFile, readUnchangedFile } from "../run/evidence-files.js";
+// A stamp from a read that started within this long of the file's last change may not show a
+// later write: a filesystem with coarse timestamps gives both writes the same times.
+const RACY_WINDOW_NS = 2000000000n;
+/**
+ * Facts per prepared run, by the path the caller gave. A finished study verifies its run up to five
+ * times through one prepared object (the Observer render, the analysis gate, the analysis and two
+ * refreshes), and decoding every frame each time took most of each verify on a long run. The
+ * entries live as long as the prepared object.
+ */
+const known = new WeakMap();
+/**
+ * A registered screenshot's facts: its size, why it is not PNG evidence (null when it is), and
+ * whether it has the redactor's output shape. `relativePath` may use `\`, read as `/`. A frame read
+ * before through the same `runPaths` is not read again while it is still the same file with the
+ * same size and times, and its last change was at least 2 s before that read started.
+ */
+export async function readScreenshot(runPaths, relativePath) {
+    const filePath = relativePath.replace(/\\/g, "/");
+    // Created before the first await: reads of one run overlap, and each must add to the same map.
+    let entries = known.get(runPaths);
+    if (entries === undefined)
+        known.set(runPaths, (entries = new Map()));
+    const entry = entries.get(relativePath);
+    if (entry !== undefined && (await isUnchangedFile(runPaths, filePath, entry.stamp)))
+        return entry.facts;
+    const startedNs = BigInt(Date.now()) * 1000000n;
+    const read = await readUnchangedFile(runPaths, filePath, RUN_ARTIFACT_MAX_BYTES);
+    if (read.state !== "read") {
+        entries.delete(relativePath);
+        return read.state === "limit" ? { state: "limit" } : read;
+    }
+    const facts = {
+        state: "read",
+        size: read.bytes.length,
+        error: screenshotEvidenceError(relativePath, read.bytes),
+        redactedShape: isRedactedFrameShape(read.bytes),
+    };
+    if (read.stamp.ctimeNs <= startedNs - RACY_WINDOW_NS)
+        entries.set(relativePath, { stamp: read.stamp, facts });
+    else
+        entries.delete(relativePath);
+    return facts;
+}

package/dist/verify/verify.js

@@ -5,7 +5,7 @@ import { analysisSharingProblems } from "../analysis/sharing.js";
 import { containsSensitive, REDACTED_SANDBOX_ID } from "../evidence/redaction.js";
 import { keyedSandboxIds, readRunSandboxIds } from "../run/sandbox-ids.js";
 import { validatePreparedRunArtifactPaths } from "../run/paths.js";
-import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "../run/bundle.js";
+import { isReadRunBundleSchema, RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, RUN_BUNDLE_V2_SCHEMA, } from "../run/bundle.js";
 import { ContainedReadRefusedError, refusalText } from "../run/contained-output.js";
 import { isCleanupResult, isRunBundle } from "../run/bundle-shape.js";
 import { loadStreamTraces } from "../run/stream-trace.js";
@@ -272,7 +272,7 @@ function bundlePresenceChecks(bundleRead, review) {
     const bundle = runJsonValue(bundleRead);
     const record = isRecord(bundle) ? bundle : undefined;
     const schema = record?.schema;
-    const schemaOk = schema === RUN_BUNDLE_SCHEMA || schema === RUN_BUNDLE_V1_SCHEMA;
+    const schemaOk = isReadRunBundleSchema(schema);
     const redactionRecord = record?.redaction;
     const redaction = isRecord(redactionRecord) ? redactionRecord.status : undefined;
     const missingSections = REQUIRED_SECTIONS.filter((key) => record?.[key] === undefined);
@@ -305,7 +305,7 @@ function bundlePresenceChecks(bundleRead, review) {
                 ? `run.json declares ${String(schema)}`
                 : record === undefined
                     ? "no readable run.json, so no schema"
-                    : `run.json declares ${typeof schema === "string" ? schema : "no schema"}; verify reads ${RUN_BUNDLE_SCHEMA} and ${RUN_BUNDLE_V1_SCHEMA}`,
+                    : `run.json declares ${typeof schema === "string" ? schema : "no schema"}; verify reads ${RUN_BUNDLE_SCHEMA}, ${RUN_BUNDLE_V2_SCHEMA} and ${RUN_BUNDLE_V1_SCHEMA}`,
         },
         {
             name: "run bundle shape",
@@ -439,10 +439,11 @@ function buildShareSafety(args) {
     const unscanned = unscannedMessage(args.unscannedArtifacts);
     if (unscanned !== undefined)
         reasons.push({ code: "UNSCANNED_ARTIFACT", message: unscanned });
-    // A v2 run.json binds each finished participant's items by its trace index. Items written while
-    // a participant was still working (liveActor) have no index, so such a run stays local.
+    // From v2, run.json binds each finished participant's items by its trace index. Items written
+    // while a participant was still working (liveActor) belong to no finished trace, so such a run
+    // stays local.
     const live = args.bundle.streams.filter((stream) => stream.liveActor !== undefined);
-    if (args.bundle.schema === RUN_BUNDLE_SCHEMA && live.length > 0)
+    if (args.bundle.schema !== RUN_BUNDLE_V1_SCHEMA && live.length > 0)
         reasons.push({
             code: "RUN_NOT_FINISHED",
             message: `The run did not finish: run.json holds in-progress items for ${live.map((stream) => stream.id).join(", ")}, which no trace file binds. Review it locally; rerun the study for evidence you can share.`,

package/docs/architecture/github-feedback-loop.md

@@ -129,7 +129,7 @@ humanish_swarm:
     - .env*
     - .github/workflows/**
     - infra/**
-  artifact_schema_version: humanish.run-bundle.v2
+  artifact_schema_version: humanish.run-bundle.v3
   credential_manifest: []
   network_policy: no_network
   spend_policy: no_spend

package/docs/contracts/README.md

@@ -8,7 +8,7 @@ disagree.
   (`RunStudyOptions`) and the exports removed in 0.107.0.
 - [core.md](core.md): the records a run writes under `.humanish/runs/<id>/` and how each route
   starts a run.
-- [run-bundle.md](run-bundle.md): `humanish.run-bundle.v2`, the evidence contract that `verify`
+- [run-bundle.md](run-bundle.md): `humanish.run-bundle.v3`, the evidence contract that `verify`
   checks.
 - [policy.md](policy.md): credential, network, spend, redaction, sharing and assisted-run
   boundaries.