humanish 0.122.0 → 0.124.0

package/dist/verify/artifacts.d.ts

@@ -2,19 +2,20 @@ import { type PreparedRunArtifactPaths } from "../run/paths.js";
 import type { RunBundle } from "../run/bundle.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export declare const MAX_REPORTED_FINDINGS = 50;
-/**
- * The most entries, files and directories, the public-safety scan visits in one run. Bundle export
- * refuses a run with more, so the scan never passes a run whose files it did not all read.
- */
-export declare const MAX_RUN_ENTRIES = 10000;
 /** What the public-safety scan did not read. A run with any of it cannot grade share_ready. */
 export interface UnscannedArtifacts {
     /** Run files it could not read as text, by run-relative path. */
     readonly files: string[];
     /** Folders it could not list, by run-relative path ("" is the run folder). */
     readonly unlistedFolders: string[];
-    /** The folder it was listing when it reached MAX_RUN_ENTRIES. It read nothing listed after. */
-    stoppedIn?: string;
+    /**
+     * Where the scan stopped: the folder it was listing when it passed its entry limit
+     * (runEntryLimit) and that limit. It read nothing listed after.
+     */
+    stopped?: {
+        readonly folder: string;
+        readonly limit: number;
+    };
 }
 /**
  * The UNSCANNED_ARTIFACT reason: the files the scan could not read, the folders it could not list
@@ -66,8 +67,14 @@ interface RegisteredStreamMedia {
  * registered stream media and that the scan cannot read as text (readPlainText), cannot read at
  * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned.files`, so the caller can
  * keep the run from grading share_ready. A directory it cannot list goes to
- * `unscanned.unlistedFolders`, and the directory it was listing when it passed MAX_RUN_ENTRIES
- * entries is `unscanned.stoppedIn`.
+ * `unscanned.unlistedFolders`. It visits at most runEntryLimit(`participants`) entries, the
+ * participants the run's run.json records, and where it stopped past them is `unscanned.stopped`.
+ */
+export declare function scanRunPublicSafetyArtifacts(runPaths: PreparedRunArtifactPaths, derivedFindings: string[], media: RegisteredStreamMedia, unscanned: UnscannedArtifacts, participants: number): Promise<string[]>;
+/**
+ * The public-safety scan of one file read as source evidence, an indexed trace, by its bytes and
+ * whatever its path: no exemption for a regenerated projection applies. `unscanned` when the bytes
+ * are not plain text or hold an encoding the scan cannot read.
  */
-export declare function scanRunPublicSafetyArtifacts(runPaths: PreparedRunArtifactPaths, derivedFindings: string[], media: RegisteredStreamMedia, unscanned: UnscannedArtifacts): Promise<string[]>;
+export declare function scanSourceEvidence(bytes: Buffer): "clean" | "sensitive" | "unscanned";
 export {};

package/dist/verify/artifacts.js

@@ -9,6 +9,7 @@ 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 { 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";
@@ -16,11 +17,6 @@ import { plural } from "../run/text.js";
 import { isZeroEventTerminalTrace } from "./actor.js";
 /** Public-safety and evidence-reference findings stop at this many per list. */
 export const MAX_REPORTED_FINDINGS = 50;
-/**
- * The most entries, files and directories, the public-safety scan visits in one run. Bundle export
- * refuses a run with more, so the scan never passes a run whose files it did not all read.
- */
-export const MAX_RUN_ENTRIES = 10_000;
 // The UNSCANNED_ARTIFACT reason names this many paths of each kind and counts the rest.
 const MAX_LISTED_UNSCANNED = 10;
 /**
@@ -35,11 +31,11 @@ export function unscannedMessage(unscanned) {
         sentences.push(`The public-safety scan cannot read ${plural(files.length, "file")} as text that ${files.length === 1 ? "is not a stream screenshot under screenshots/ or a registered recording" : "are not stream screenshots under screenshots/ or registered recordings"}: ${listed(files)}.`);
     if (folders.length > 0)
         sentences.push(`The public-safety scan could not list ${plural(folders.length, "folder")}, so it read none of the files in ${folders.length === 1 ? "it" : "them"}: ${listed(folders)}.`);
-    if (unscanned.stoppedIn !== undefined)
-        sentences.push(`The public-safety scan stopped at its limit of ${MAX_RUN_ENTRIES} files and folders while listing ${folderName(unscanned.stoppedIn)}, so it read nothing listed after that point.`);
+    if (unscanned.stopped !== undefined)
+        sentences.push(`The public-safety scan stopped at its limit of ${unscanned.stopped.limit} files and folders while listing ${folderName(unscanned.stopped.folder)}, so it read nothing listed after that point.`);
     if (sentences.length === 0)
         return undefined;
-    const onlyFiles = folders.length === 0 && unscanned.stoppedIn === undefined;
+    const onlyFiles = folders.length === 0 && unscanned.stopped === undefined;
     sentences.push(onlyFiles ? "Review them before sharing." : "Review the run folder before sharing.");
     return sentences.join(" ");
 }
@@ -323,14 +319,15 @@ export function rawScreenshotStreamIds(bundle, redactedShapeFrames) {
  * registered stream media and that the scan cannot read as text (readPlainText), cannot read at
  * all, or that holds more than RUN_ARTIFACT_MAX_BYTES goes to `unscanned.files`, so the caller can
  * keep the run from grading share_ready. A directory it cannot list goes to
- * `unscanned.unlistedFolders`, and the directory it was listing when it passed MAX_RUN_ENTRIES
- * entries is `unscanned.stoppedIn`.
+ * `unscanned.unlistedFolders`. It visits at most runEntryLimit(`participants`) entries, the
+ * participants the run's run.json records, and where it stopped past them is `unscanned.stopped`.
  */
-export async function scanRunPublicSafetyArtifacts(runPaths, derivedFindings, media, unscanned) {
+export async function scanRunPublicSafetyArtifacts(runPaths, derivedFindings, media, unscanned, participants) {
     const findings = [];
     await validatePreparedRunArtifactPaths(runPaths);
     await scanRunPublicSafetyDirectory(runPaths, "", findings, derivedFindings, media, unscanned, {
         entries: 0,
+        limit: runEntryLimit(participants),
     });
     await validatePreparedRunArtifactPaths(runPaths);
     return findings;
@@ -351,9 +348,9 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
     }
     for (const entryName of entries) {
         walk.entries += 1;
-        if (walk.entries > MAX_RUN_ENTRIES) {
+        if (walk.entries > walk.limit) {
             // Every directory the walk returns through comes here once more; the first one stopped it.
-            unscanned.stoppedIn ??= relativeDirectory;
+            unscanned.stopped ??= { folder: relativeDirectory, limit: walk.limit };
             return;
         }
         const relativePath = relativeDirectory ? `${relativeDirectory}/${entryName}` : entryName;
@@ -424,6 +421,18 @@ async function scanRunPublicSafetyDirectory(runPaths, relativeDirectory, finding
         }
     }
 }
+/**
+ * The public-safety scan of one file read as source evidence, an indexed trace, by its bytes and
+ * whatever its path: no exemption for a regenerated projection applies. `unscanned` when the bytes
+ * are not plain text or hold an encoding the scan cannot read.
+ */
+export function scanSourceEvidence(bytes) {
+    const decoded = readPlainText(bytes);
+    if (!decoded.ok)
+        return "unscanned";
+    const scan = scanEncodedTextCached(decoded.text);
+    return scan.sensitive ? "sensitive" : scan.opaque ? "unscanned" : "clean";
+}
 function normalizeLocalEvidenceReference(value) {
     if (!value || value.includes("://") || path.isAbsolute(value)) {
         return null;

package/dist/verify/scan-limit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The most entries the scan visits in a run of `participants` participants. run.json states the
+ * count, so it is clamped to the most participants a run's analysis covers, which keeps a forged
+ * count from making the scan unbounded.
+ */
+export declare function runEntryLimit(participants: number): number;

package/dist/verify/scan-limit.js

@@ -0,0 +1,25 @@
+// How many files and folders the public-safety scan visits in one run, and bundle export counts
+// before it copies one. It lives apart from the scan so the planner can check a study's estimated
+// file count against it without loading the scanner.
+import { EVIDENCE_LIMITS } from "../analysis/analysis-limits.js";
+/** The entries any run may hold, whatever its participants. */
+const MAX_RUN_ENTRIES = 10_000;
+/**
+ * The entries each participant adds to the limit. Measured on 2026-10-12: a participant writes a
+ * screenshot a model turn, live participants that worked 5 minutes or more took a turn every 10
+ * s (median of 42 sessions), and its trace file, screenshot folder and first frame add 3 more. A
+ * participant working an 8-hour window then holds about 2,900 entries; 5,000 leaves room for a
+ * dwell window's frames or a faster pace.
+ */
+const ENTRIES_PER_PARTICIPANT = 5_000;
+/**
+ * The most entries the scan visits in a run of `participants` participants. run.json states the
+ * count, so it is clamped to the most participants a run's analysis covers, which keeps a forged
+ * count from making the scan unbounded.
+ */
+export function runEntryLimit(participants) {
+    const counted = Number.isFinite(participants)
+        ? Math.min(Math.max(0, Math.floor(participants)), EVIDENCE_LIMITS.participants)
+        : 0;
+    return MAX_RUN_ENTRIES + ENTRIES_PER_PARTICIPANT * counted;
+}

package/dist/verify/verify.d.ts

@@ -17,7 +17,7 @@ export interface VerifyResult {
     shareSafety: {
         status: "share_ready" | "local_only" | "blocked";
         reasons: Array<{
-            code: "VERIFY_FAILED" | "PUBLIC_SAFETY_FINDINGS" | "ANALYSIS_UNVERIFIED" | "RAW_SCREENSHOTS" | "RAW_SANDBOX_ID" | "CONTINUOUS_MEDIA" | "REAL_COMMUNICATIONS" | "UNSCANNED_ARTIFACT";
+            code: "VERIFY_FAILED" | "PUBLIC_SAFETY_FINDINGS" | "ANALYSIS_UNVERIFIED" | "RAW_SCREENSHOTS" | "RAW_SANDBOX_ID" | "CONTINUOUS_MEDIA" | "REAL_COMMUNICATIONS" | "UNSCANNED_ARTIFACT" | "RUN_NOT_FINISHED";
             message: string;
         }>;
     };

package/dist/verify/verify.js

@@ -5,15 +5,16 @@ 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 } from "../run/bundle.js";
+import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_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";
 import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath, runJsonValue, } from "../run/locate.js";
 import { SANDBOX_RECEIPTS_ARTIFACT } from "../run/sandbox-receipts.js";
 import { isRecord } from "../run/type-guards.js";
 import { runNotFoundMessage } from "../run/run-not-found.js";
 import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
-import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, streamScreenshotPaths, unscannedMessage, } from "./artifacts.js";
+import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, scanSourceEvidence, streamScreenshotPaths, unscannedMessage, } from "./artifacts.js";
 import { flatContextWarnings } from "./context-growth.js";
 import { runNotFinished } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
@@ -75,7 +76,10 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
     }
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
     const bundleRead = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
-    const bundle = runJsonValue(bundleRead);
+    // Every check below reads the streams with their traces loaded; a trace that does not match its
+    // index fails the evidence-artifacts check and its stream is checked without its items.
+    const traces = await loadTraces(runPaths, runJsonValue(bundleRead));
+    const { bundle, refusedTraces } = traces;
     const cleanupRead = await readRunJsonIfExists(runPaths, "cleanup.json");
     const review = {
         json: await readRunJsonIfExists(runPaths, "review.json"),
@@ -103,7 +107,8 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         // A run from before 0.110 with no receipts still names its ids in run.json.
         sandboxIds: [...new Set([...journaledSandboxIds, ...keyedSandboxIds(bundle)])],
         sandboxIdFiles,
-    }, unscannedArtifacts);
+    }, unscannedArtifacts, isRunBundle(bundle) ? bundle.simulations.length : 0);
+    addTraceScan(traces, publicSafetyFindings, unscannedArtifacts);
     // JSON escapes can hide a sensitive value from the byte scan while the
     // decoded recording exposes it to Observer, feedback, or analysis input.
     if (publicSafetyFindings.length < MAX_REPORTED_FINDINGS &&
@@ -125,17 +130,14 @@ export async function verifyResolvedRun(cwd, runInput, runPaths) {
         ? await redactedShapeFramePaths(runPaths, bundle)
         : new Set();
     const invalidEvidenceReferences = isRunBundle(bundle) ? invalidRunEvidenceReferences(bundle) : [];
-    checks.push({
-        name: "local evidence artifacts exist",
-        ok: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0,
-        message: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0
-            ? isRunBundle(bundle)
-                ? "every referenced screenshot, trace, log and filesystem artifact is present"
-                : SHAPE_UNCHECKED
-            : invalidEvidenceReferences.length > 0
-                ? `invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`
-                : `missing local evidence artifacts: ${missingEvidenceArtifacts.join(", ")}`,
-    });
+    checks.push(evidenceArtifactsCheck(isRunBundle(bundle), [
+        ...refusedTraces,
+        ...(invalidEvidenceReferences.length > 0
+            ? [`invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`]
+            : missingEvidenceArtifacts.length > 0
+                ? [`missing local evidence artifacts: ${missingEvidenceArtifacts.join(", ")}`]
+                : []),
+    ]));
     checks.push(...(await evidenceChecks(runPaths, bundle, cleanupRead)));
     const recordingOk = checks.every((check) => check.ok);
     if (derivedPublicSafetyFindings.length > 0)
@@ -208,6 +210,46 @@ export async function verifyRunPrepared(cwdInput, runInput, runPaths) {
     }
     return verifyResolvedRun(cwd, runInput, runPaths);
 }
+/** The evidence-artifacts check: refused traces, then invalid references or missing files. */
+function evidenceArtifactsCheck(shaped, problems) {
+    return {
+        name: "local evidence artifacts exist",
+        ok: problems.length === 0,
+        message: problems.length > 0
+            ? problems.join(" ")
+            : shaped
+                ? "every referenced screenshot, trace, log and filesystem artifact is present"
+                : SHAPE_UNCHECKED,
+    };
+}
+/**
+ * run.json with each stream's trace loaded, one file at a time, and the refusal of each trace that
+ * does not match its index. A run.json that fails the shape guard is returned as it is.
+ */
+async function loadTraces(runPaths, stored) {
+    const scanned = { sensitive: [], opaque: [] };
+    if (!isRunBundle(stored))
+        return { bundle: stored, refusedTraces: [], ...scanned };
+    // Each trace is source evidence: scanned by the bytes it was joined from, apart from the
+    // directory walk and any path exemption the walk makes.
+    const { bundle, refused } = await loadStreamTraces(runPaths, stored, {
+        onTrace: (file, bytes) => {
+            const scan = scanSourceEvidence(bytes);
+            if (scan !== "clean")
+                scanned[scan === "sensitive" ? "sensitive" : "opaque"].push(file);
+        },
+    });
+    return { bundle, refusedTraces: refused.map((error) => error.message), ...scanned };
+}
+/** The trace scan's results, beside the walk's: each file named once. */
+function addTraceScan(traces, findings, unscanned) {
+    for (const file of traces.sensitive)
+        if (!findings.includes(`sensitive text ${file}`))
+            findings.push(`sensitive text ${file}`);
+    for (const file of traces.opaque)
+        if (!unscanned.files.includes(file))
+            unscanned.files.push(file);
+}
 /** The top-level run.json sections the shape guard requires. */
 const REQUIRED_SECTIONS = [
     "source",
@@ -230,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;
+    const schemaOk = schema === RUN_BUNDLE_SCHEMA || schema === RUN_BUNDLE_V1_SCHEMA;
     const redactionRecord = record?.redaction;
     const redaction = isRecord(redactionRecord) ? redactionRecord.status : undefined;
     const missingSections = REQUIRED_SECTIONS.filter((key) => record?.[key] === undefined);
@@ -260,10 +302,10 @@ function bundlePresenceChecks(bundleRead, review) {
             name: "run schema",
             ok: schemaOk,
             message: schemaOk
-                ? `run.json declares ${RUN_BUNDLE_SCHEMA}`
+                ? `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}`,
+                    : `run.json declares ${typeof schema === "string" ? schema : "no schema"}; verify reads ${RUN_BUNDLE_SCHEMA} and ${RUN_BUNDLE_V1_SCHEMA}`,
         },
         {
             name: "run bundle shape",
@@ -397,6 +439,14 @@ 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.
+    const live = args.bundle.streams.filter((stream) => stream.liveActor !== undefined);
+    if (args.bundle.schema === RUN_BUNDLE_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.`,
+        });
     // Runs from 0.110 keep raw sandbox ids only in sandbox-receipts.ndjson. An earlier run records
     // them in run.json, and any file that names one is not share-ready as it is.
     const rawResources = (args.bundle.providerResources ?? []).some((resource) => resource.id !== REDACTED_SANDBOX_ID);

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

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

package/docs/architecture/observer.md

@@ -24,9 +24,26 @@ Observer commands may add derived artifacts:
     observer-data.json
 ```
 
-`run.json` remains the source bundle. `observer/observer-data.json` is the
-normalized view model consumed by the Observer. `events.ndjson` is the appendable
-event stream contract that live adapters update while a run is active.
+`run.json` remains the source bundle. `observer/observer-data.json`
+(`humanish.observer-data.v2`) is the normalized view model consumed by the Observer,
+with every participant except their trace items and the screenshot entries of their
+artifact list. A participant working for hours records thousands of items and a
+screenshot each turn, so these are most of a long run's bytes; apart, the saved file
+stays small enough for `verify` to read. The items stay in the run's traces
+(`actors/<stream>.json`). `events.ndjson` is the appendable event stream
+contract that live adapters update while a run is active.
+
+`observer/index.html` carries both parts: the data slot holds observer-data.json's
+content, and `<script id="observer-items" type="application/octet-stream"
+data-encoding="gzip">` holds the items and full artifact lists (`humanish.observer-items.v1`, by stream id)
+gzip-compressed in base64, which a `file://` page decodes without a fetch. Real
+trace items compress about eight times. The page joins the two before it renders
+(`joinObserverData` in `src/observer/participant-items.ts`), so every view reads the
+same data as before. A stream whose screenshot entries moved records how many in
+`screenshotArtifacts`, and the page renders nothing from items that are another
+run's or miss a participant's items or screenshot entries. The server answers a
+saved v2 observer-data.json that leaves items out as unavailable, since it has no
+items to join.
 
 ## Stream Model
 
@@ -55,7 +72,9 @@ public-safe metadata.
 4. opens the served Observer URL;
 5. keeps the shell attached until Ctrl-C.
 
-The browser polls `observer-data.json` with `no-store` caching. Static
+The browser polls `observer-feed.json` with `no-store` caching: the server's
+projection of the run as `{ data, items }`, observer-data.json's content and the
+items, from one read of the run per poll. Static
 `file://` opening still works for immutable review, but follow mode is the
 operator path. Agents and CI should use `humanish watch --json --no-open` for
 the same fresh evidence without browser open or a long-running process.
@@ -253,7 +272,7 @@ These remain adapter work:
 ## The rendering layer
 
 The renderer is the `observer/` workspace: a Vite single-file build on the
-`@humanish` registry tokens, frozen against `humanish.observer-data.v1`
+`@humanish` registry tokens, frozen against `humanish.observer-data.v2`
 (`tests/observer/data-contract.test.ts`). The root build copies the workspace
 artifact to `dist/observer-app.html`; in a repo checkout a missing or stale
 artifact auto-builds, and an unconditional preflight at CLI startup makes a

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.v1`, the evidence contract that `verify`
+- [run-bundle.md](run-bundle.md): `humanish.run-bundle.v2`, the evidence contract that `verify`
   checks.
 - [policy.md](policy.md): credential, network, spend, redaction, sharing and assisted-run
   boundaries.

package/docs/contracts/run-bundle.md

@@ -1,6 +1,6 @@
 # Run Bundle Contract
 
-`humanish.run-bundle.v1` is the evidence contract. The TypeScript shape in `src/run/bundle.ts`
+`humanish.run-bundle.v2` is the evidence contract. The TypeScript shape in `src/run/bundle.ts`
 (with `streams[]` in `src/run/streams.ts` and `sharedWorld` as `SharedWorldEvidence` in
 `src/run/shared-world-evidence.ts`) and the fail-closed checks in `src/verify/verify.ts` are the
 source of truth. This page explains the stable public fields and the extension rules; it does not
@@ -13,6 +13,79 @@ and `terminal-ledgers.json`. `true` means participant and product setup commands
 in the JSON message of the `terminal-lab.runtime.declared` event. Older bundles omit it.
 The setting does not attest that the studied CLI honors the variable.
 
+## Participant traces
+
+From v2, run.json holds each participant's summary and the trace file holds its items. The run
+writer (`src/run/run.ts`, through `splitStreamTraces` in `src/run/stream-trace.ts`) writes, for
+each stream with an `actor`:
+
+- the trace file: the actor trace (`humanish.actor-trace.v1`) with every item, plus `artifacts`,
+  the stream's screenshot entries. Its path is the stream's actor trace artifact (`actor.json` for
+  one participant, `actors/<stream>.json` for more, `actor-<surface>.json` on the scripted route),
+  or `actors/<n>.json`, `n` its position in `streams[]` (from 1), for a stream with none or whose
+  trace artifact an earlier stream claimed. Names of that form are never reused as a stream's own
+  artifact, so two streams never get one file;
+- in run.json, `streams[].actor` without `items`, `streams[].artifacts` without the screenshot
+  entries, and the index:
+
+```yaml
+trace:
+  path: actors/stream-001.json
+  bytes: 5480211 # the file's size
+  sha256: "<hex digest of the file>"
+  items: 23104 # entries in the file's items
+  screenshots: 2881 # entries in the file's artifacts
+```
+
+run.json keeps every field readers list runs by: each stream's status, judged status,
+assignment and geometry, and the actor's status, completion reason, counts, persona, debrief,
+impressions, token usage and estimated cost. Each trace is written once.
+
+`trace.path` must be one of those trace file names (`actor.json`, `actors/<name>.json`,
+`actor-<name>.json`, with `<name>` a plain file name); `isStreamTracePath` in
+`src/run/stream-shape.ts` holds the rule, and the writer, the shape check and the loader all use
+it. Any other path, such as `observer/index.html`, fails the shape check.
+
+Readers load a stream through `loadStreamTrace(runPaths, stream)`. A v1 stream returns as it is.
+An indexed stream's file is read under the 32 MiB per-file limit (analysis uses its 16 MiB
+source limit for each trace) and refused unless its size, sha256, item count and screenshot count
+match the index. A trace file belongs to one participant: every stream whose index names a file
+another stream's index names, compared without case as a case-insensitive file system compares
+names, is refused before any file is read. The writer claims names the same way. In a v2 run.json every `actor`
+must have an index: an actor with no index, with
+or without inline `items`, is refused, and so is one with both an index and inline `items`.
+verify reports a refused trace in the `local evidence artifacts exist` check, so the run is
+`blocked`. verify also scans the bytes of each trace it loaded with the public-safety text scan,
+apart from its walk of the run folder, so no path exemption the walk makes applies to a trace.
+run.json's digest, which an analysis record binds, covers each index and so each trace.
+
+Mid-run flushes: the writer indexes every finished participant on every write, flushes included,
+so a v2 run.json never holds `actor.items`. A participant still working has its items so far in
+`streams[].liveActor.items` (`humanish.live-actor.v1`), which no index binds. A v2 run.json may
+carry `liveActor` only while its run has not finished: one whose `outcome.state` is `finished`
+and still holds `liveActor` is refused. An unfinished v2 run.json with `liveActor` (a flush, or
+the last write of an interrupted run) verifies as `local_only` with the share-safety reason
+`RUN_NOT_FINISHED`, never `share_ready`. v1 bundles keep their earlier behavior.
+
+Readers that show a run (the Observer server, run detail and the TUI, the review command's
+provenance) load traces through the same loader and rules. A participant whose trace the loader
+refused shows none of the items run.json or a file supplied for it: its stream carries
+`traceUnavailable` with the reason, its Observer timeline a `trace.unavailable` warning, and its
+run-detail entry `evidenceUnavailable`. The Observer server reads the saved observer-data.json
+only while a run has no run.json at all; a run.json that is there and cannot be read, parsed or
+used as a bundle answers 404 with the reason, never the saved projection. In safe serving
+(`observe --all --safe`) every read is checked against the files admitted with the run's
+share_ready verification, so a run.json changed after admission is refused and the admitted
+projection is served.
+observer-data.json is built from the loaded bundle. From 0.124.0 it is
+`humanish.observer-data.v2`: the same data without each participant's trace items, which stay in
+the traces (docs/architecture/observer.md).
+
+Compatibility: humanish 0.122.0 and earlier read only v1 and refuse a v2 run.json by its schema
+(`run schema` fails in verify, analysis refuses the source). This release reads v1 bundles as
+they are, with no migration. An exported copy (`humanish export --format bundle`) is written as
+v2 whatever the source version.
+
 ## Purpose
 
 A run bundle is the durable evidence packet for one harness run. It should be
@@ -22,7 +95,7 @@ feedback drafts and future public issues.
 ## Minimum Bundle Shape
 
 ```yaml
-schema: humanish.run-bundle.v1
+schema: humanish.run-bundle.v2 # v1 bundles are still read
 runId: "<core run id>"
 mode: "dry-run|live"
 simCount: 1
@@ -522,9 +595,13 @@ For run id `example-2026-06-02t10-00-00-000z-proof`, the core layout is:
 .humanish/runs/example-2026-06-02t10-00-00-000z-proof/review.md
 .humanish/runs/example-2026-06-02t10-00-00-000z-proof/observer/observer-data.json
 .humanish/runs/example-2026-06-02t10-00-00-000z-proof/events.ndjson
+.humanish/runs/example-2026-06-02t10-00-00-000z-proof/actors/stream-001.json
 .humanish/runs/latest.json
 ```
 
+`actors/<stream>.json` (or `actor.json` for one participant) is a participant's trace file; see
+[Participant traces](#participant-traces).
+
 Absolute paths, traversal segments, remotes, hosted logs, and private artifact
 URLs are not part of the core layout.
 
@@ -691,7 +768,9 @@ bundle is safe to promote into a public issue. Public promotion should branch on
 `ok: true` also does not mean the run finished. A run killed mid-way leaves an
 in-progress bundle that can pass every check. When the run is not finished,
 `warnings[]` carries one entry starting with the stable code `RUN_NOT_FINISHED`.
-`ok` and `shareSafety` do not change. Verify decides "not finished" by the run
+`ok` does not change. `shareSafety` changes only for a v2 bundle that holds a participant's
+in-progress items (`liveActor`): it is `local_only` with the reason `RUN_NOT_FINISHED`, since no
+trace index binds those items. Verify decides "not finished" by the run
 index's rule, which the TUI and `humanish stats` use: the run's `status.json` when
 it is well formed and names the run, else a `simulations[]` entry still `running` in the
 bundle. A `running` record updated within the stale window reads as still
@@ -715,7 +794,8 @@ receipt records a sandbox not gone or misses a journaled one, and `unknown` othe
 including a receipt from humanish 0.110.0 or earlier, which did not search by tag.
 
 The local-evidence check includes screenshots declared only by
-`streams[].actor.items[].screenshotRef` or `streams[].liveActor.items[].screenshotRef`,
+`streams[].actor.items[].screenshotRef` (in the trace file for a v2 bundle) or
+`streams[].liveActor.items[].screenshotRef`,
 as well as every feedback candidate's evidence. Actor frame paths are relative
 to the run root; missing, malformed or nonlocal references fail verification.
 Screenshots use the existing bounded PNG decoder. Nonimage candidate evidence
@@ -749,8 +829,9 @@ writes every frame, and the recordings `streams[].recording` registers. Every
 other file the scan cannot read as text, cannot read at all, or that is larger
 than 32 MiB (verify reads at most that much of one file) contributes
 `UNSCANNED_ARTIFACT`. So does a folder the scan cannot list, and the rest of a
-run past its first 10,000 files and folders, the most `export --format bundle`
-takes. The reason's message lists the paths, and it keeps otherwise valid
+run past its first 10,000 files and folders plus 5,000 for each participant
+`run.json` records, counting at most 128. `export --format bundle` takes at most
+10,000. The reason's message lists the paths, and it keeps otherwise valid
 evidence `local_only`. This includes images that only feedback candidates,
 adapter artifacts or stream artifact entries cite, and a PNG an actor trace
 references outside `screenshots/`. An adapter artifact larger than 32 MiB grades
@@ -848,6 +929,8 @@ does not inherit resource cleanup authority. Unsupported images, binary formats,
 inline image payloads, invalid evidence and references to omitted files are refused.
 The original and derivative are independently verified. Text still requires human
 review before sharing; screenshot blur does not certify natural-language privacy.
+Export counts the run's files and folders against the public-safety scan's limit
+(10,000 plus 5,000 for each participant `run.json` records) and refuses a run past it.
 
 ## Git Provenance
 

package/docs/contracts/schemas.md

@@ -26,7 +26,7 @@ workflow without leaking private upstream truth into core.
 
 | Contract                          | Schema                                                                                                                                                                                                                                                    | Public-safe fixture                                                                 |
 | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Run bundle                        | `humanish.run-bundle.v1`                                                                                                                                                                                                                                  | `synthetic-run-bundle`                                                              |
+| Run bundle                        | `humanish.run-bundle.v2` (each participant's trace in its own file, indexed by `streams[].trace`; v1 bundles, with traces inline, are still read)                                                                                                         | `synthetic-run-bundle`                                                              |
 | Adapter                           | `humanish.adapter.v1`                                                                                                                                                                                                                                     | `synthetic-cli-adapter`                                                             |
 | Study file                        | `humanish.study.v3`                                                                                                                                                                                                                                       | `first-run`                                                                         |
 | Persona                           | `humanish.persona.v1`                                                                                                                                                                                                                                     | `synthetic-maintainer`                                                              |
@@ -471,7 +471,7 @@ A study's result has one schema on every route, `humanish.study-result.v1`
 (`src/run/study-result.ts`), with `route` and `studyId`. 0.109.0 removed `labId`, which 0.108.0
 wrote with the same value. Route-specific fields stay on their route's result. `humanish run`
 with no study, `observe`, and a refusal made before a route is picked keep
-`humanish.run-result.v1`. The evidence record stays `humanish.run-bundle.v1` in every case.
+`humanish.run-result.v1`. The evidence record stays `humanish.run-bundle.v2` in every case.
 The computer-use result carries `plan` (the pre-flight participant table: concurrency, waves,
 per-participant session budget, worst-case sandbox-minutes), `lanes[]` (always present,
 length 1 at N=1; per-participant status/session/sandbox/subject), and `laneSummary`
@@ -578,7 +578,7 @@ Core-owned fields:
   }`. Emitted by the computer-use and shared-world routes and the clone
   scripted-browser route; absent on pre-existing and other bundles. `repo`/`commit` are clone-route fields; `archiveSha256`
   (64-hex sha256, the local-tree provenance pin) and `dirty` (host git
-  porcelain status at pack time) are local-tree-route fields, additive under
+  porcelain status at pack time) are local-tree-route fields, additive since
   `humanish.run-bundle.v1`: a dirty working tree cannot be commit-pinned, so
   the archive content digest stands in for it. `product` is the desktop-cli field: the
   `subject.product.name` the study declares, with state `undeclared`. A computer-use
@@ -616,7 +616,7 @@ Adapter-owned fields:
 Abbreviated synthetic fixture (omits `cwd`, `simulations`, `streams` and `events`):
 
 ```yaml
-schema: humanish.run-bundle.v1
+schema: humanish.run-bundle.v2
 runId: synthetic-run-bundle-2026-06-02t10-00-00-000z-proof
 mode: dry-run
 simCount: 1
@@ -686,8 +686,8 @@ sequential shared-world route, which 0.106.0 removed. Only bundles written befor
 (`tests/run/legacy-sequential-shared-world.test.ts`). The sequential rules below apply
 to those bundles.
 
-A shared-world bundle adds two additive, optional fields to `humanish.run-bundle.v1`
-(absent on every other bundle, so they stay byte-stable):
+A shared-world bundle adds two additive, optional fields, added under `humanish.run-bundle.v1`
+(absent on every other bundle):
 
 - `attributionClass: isolated | shared-world`: a separate attribution axis
   ("how well did the run attribute interaction?"), distinct from the persona-sampling
@@ -967,6 +967,13 @@ output all map onto one `ActorTrace`. Registered actors live in
 `pi-agent-core` or `claude-agent-sdk` fails to parse. There is no
 `humanish.actor.v1`; that name never shipped.
 
+Where the trace is stored depends on the run bundle version. In `humanish.run-bundle.v2`,
+`streams[].actor` in run.json is the trace without `items`, and the full trace, with the stream's
+screenshot entries as `artifacts`, is the file `streams[].trace.path` names (`actor.json`,
+`actors/<stream>.json` or `actor-<surface>.json`). A v1 run.json holds the full trace inline.
+`loadStreamTrace` in `src/run/stream-trace.ts` reads either; see
+[run-bundle.md](run-bundle.md#participant-traces).
+
 Core-owned fields:
 
 - `schema`
@@ -1822,7 +1829,7 @@ including existence for referenced adapter artifacts.
 
 Reserved: `humanish.evidence-stream.v1` has never shipped as a standalone
 schema, and streams are not standalone artifacts. They are the `streams` array
-inside `humanish.run-bundle.v1`, normalizing UI, browser, terminal, TUI,
+inside the run bundle (`humanish.run-bundle.v2`), normalizing UI, browser, terminal, TUI,
 code-agent UI, artifact, and summary streams, each with transport, terminal
 tail, completion, meaningful-use verdicts, and artifact pointers. See
 [`run-bundle.md`](run-bundle.md#completion-and-meaningful-use-verdicts) for

package/docs/contracts/study-analysis.md

@@ -367,7 +367,7 @@ and an impression alone supports only a finding about what the participant said.
 
 ## Durable records
 
-The frozen `humanish.observer-data.v1` schema is unchanged. A companion
+The `humanish.observer-data.v2` schema is unchanged by analysis. A companion
 `humanish.study-analysis.v1` artifact records source/config/input hashes,
 participant context, evidence manifest, coverage, provider/model/prompt version,
 status, usage and validated findings. The Observer's projection of it,