humanish 0.122.0 → 0.124.0

package/CHANGELOG.md

@@ -8,6 +8,35 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.124.0: Small Observer files for long studies, faster verify, closing reports under zero data retention (2026-10-12)
+
+humanish 0.124.0 keeps a long study's Observer files small, checks screenshots about eight times
+faster, and asks an `openai-computer-use` participant for its closing report at a scheduled end
+under zero data retention. `observer/observer-data.json` is now `humanish.observer-data.v2`: the
+run and each participant without their trace items and screenshot entries, which the Observer
+page carries compressed. On a synthetic run of 24 participants working 8 hours, observer-data.json
+fell from 155 MiB to 0.33 MiB and index.html from 94 MiB to 16 MiB, so verify reads both. A
+reader of observer-data.json that needs a participant's items reads the run's traces. verify of a
+synthetic 8-hour run with 8,895 real-size screenshots took 51 s, down from 282 s.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.124.0)
+
+## 0.123.0: Run bundle v2 writes each trace once, bundle size estimate (2026-10-12)
+
+humanish 0.123.0 writes each participant's trace once, outside run.json, so long studies stay
+within the bundle's size limits, and estimates a study's bundle before it runs. Run bundles are now
+`humanish.run-bundle.v2`: a participant's trace items live only in its trace file
+(`actor.json`, `actors/<stream>.json` or `actor-<surface>.json`), and run.json indexes each one by
+path, size and sha256. On a synthetic 8-participant, 1,000-turn run, run.json fell from 17 MB to
+74 KB. Every reader loads traces through one loader that checks the index and refuses a missing,
+altered or shared trace; a refused trace shows as evidence unavailable, and an unfinished run
+grades `local_only`. Bundles from earlier versions still load unchanged; npm 0.122.0 and earlier
+refuse a v2 bundle by name. `study check` and `run` estimate the bundle's size and file count and
+warn before any sandbox is created when it may pass the analysis or verify limit, and the
+public-safety scan's file limit grows with the number of participants.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.123.0)
+
 ## 0.122.0: Participants end on the clock, a harness error ends only its participant (2026-10-12)
 
 humanish 0.122.0 lets a participant end at a scheduled time and keeps one participant's harness

package/CONTEXT.md

@@ -12,7 +12,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | Term                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | study               | What a user designs and runs: one YAML file that declares the subject, the actor, the participants and the caps. The file lives at `humanish/studies/<id>.yaml` with schema `humanish.study.v3`, read by `humanish study` and `--study`. humanish refuses a 0.107 `humanish.lab.v2` file, and `humanish migrate` converts it (second table).                                                                                                                                                                                          | `src/study/`; `StudyConfig` in `src/study/types.ts`, parsed by `parseStudy` in `src/study/config.ts`                                                                                                                                                                                                                                                                                                        |
-| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v1`) as the source of truth.                                                                                                                                                                                                                                                                                                                                                                                                      | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
+| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v2`) as the source of truth and each participant's trace in its own file.                                                                                                                                                                                                                                                                                                                                                         | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
 | dry run             | A run with no live participant, from `--dry-run` or `mode: dry-run`. humanish writes a synthetic run bundle, review and Observer with no browser, model, keys or provider spend, and tests no product behavior. The `preview` route only dry-runs; "preview" names that route and nothing else.                                                                                                                                                                                                                                       | `runDryRun` in `src/run/dry-run.ts`; `resolveStudyDryRun` in `src/study/plan.ts`                                                                                                                                                                                                                                                                                                                            |
 | participant         | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the study config with `computerUseParticipants` (`src/study/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/study/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
 | persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/study/persona.ts`, `src/study/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                      |
@@ -36,7 +36,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | topology            | Whether participants share one instance of the subject. `route: shared-world` gives one for all; every other route gives each participant its own (`per-lane-worlds`). `run.json` records it as `sharedWorld.topology`.                                                                                                                                                                                                                                                                                                               | `route` in `StudyConfig` (`src/study/types.ts`); `isSharedWorldComposition` in `src/study/routing.ts`                                                                                                                                                                                                                                                                                                       |
 | plane               | The one instance of the subject that a shared-world study's participants use together. A `provisioned` plane is a `clone` or `local-tree` subject that humanish serves in a sandbox, with a declared subject state. An `external-public` plane is a deployment already running at `subject.appUrl`, whose owner the study names in `subject.publicTarget.owner`. Each plane has at least two participants.                                                                                                                            | `SharedWorldPlane` in `src/study/plan-types.ts`; `src/routes/shared-world/`                                                                                                                                                                                                                                                                                                                                 |
 | stream              | One live or recorded view of a participant, such as a browser or a terminal, in `run.json` and the Observer.                                                                                                                                                                                                                                                                                                                                                                                                                          | `RunStream` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                                                                                                         |
-| Observer            | The single-file review page built from `observer/observer-data.json` (`humanish.observer-data.v1`).                                                                                                                                                                                                                                                                                                                                                                                                                                   | `observer/` (the page), `src/observer/` (data, render, serve)                                                                                                                                                                                                                                                                                                                                               |
+| Observer            | The single-file review page built from `observer/observer-data.json` (`humanish.observer-data.v2`).                                                                                                                                                                                                                                                                                                                                                                                                                                   | `observer/` (the page), `src/observer/` (data, render, serve)                                                                                                                                                                                                                                                                                                                                               |
 | evidence            | Files a run keeps: screenshots, traces, transcripts, recordings. `verify` checks them and grades share-safety.                                                                                                                                                                                                                                                                                                                                                                                                                        | `src/evidence/`; `verifyRun` in `src/verify/verify.ts`                                                                                                                                                                                                                                                                                                                                                      |
 | analysis            | An independent model reading of a finished run's retained evidence, kept apart from participant feedback. Supported live runs request it automatically, and `humanish analyze` runs it on demand. It records findings and observations as `humanish.study-analysis.v1`.                                                                                                                                                                                                                                                               | `src/analysis/`; `runAutomaticAnalysis` in `src/analysis/automatic.ts`; `analyzeRun` in `src/analysis/service.ts`; `ANALYSIS_SCHEMA` in `src/analysis/types.ts`                                                                                                                                                                                                                                             |
 | finding             | A result of analysis, with citations to evidence in the run. Each finding groups the observations that support it.                                                                                                                                                                                                                                                                                                                                                                                                                    | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                             |

package/README.md

@@ -1,12 +1,23 @@
 # humanish
 
-Synthetic user research for apps, CLIs, and agent-facing product flows. AI participants with a persona and a task use your app on real desktops, and each run leaves evidence you can verify: what they did, where they got stuck, and what it cost.
+[![npm version](https://img.shields.io/npm/v/humanish)](https://www.npmjs.com/package/humanish) [![npm downloads per month](https://img.shields.io/npm/dm/humanish)](https://www.npmjs.com/package/humanish) [![CI status on main](https://img.shields.io/github/actions/workflow/status/danielgwilson/humanish/ci.yml?branch=main&label=CI)](https://github.com/danielgwilson/humanish/actions/workflows/ci.yml?query=branch%3Amain) [![License: MIT](https://img.shields.io/npm/l/humanish)](LICENSE) [![Node.js version](https://img.shields.io/node/v/humanish)](https://nodejs.org/)
 
-[![The Observer grid of a saved eight-participant study: eight desktops in one multiplayer lobby, each tile a participant's live screen](https://humanish.dev/runs/lobby-0927/poster.jpg)](https://humanish.dev/demo)
+Synthetic user research for apps, CLIs, and agent-facing product flows. AI participants with a persona and a task use your app on real desktops, and each run leaves evidence you can verify: what they did, where they got stuck, and what it cost.
 
-**[Watch a saved run](https://humanish.dev/demo).** Eight synthetic participants joined one
-lobby of a multiplayer game on its live deployment, each on its own hosted desktop. The page
-replays the real Observer; nothing runs from it.
+<a href="https://humanish.dev/demo">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-grid-dark.webp">
+    <img alt="The humanish Observer replaying a saved study five minutes into its 13-minute recording: a grid of eight participants' desktops in a multiplayer movie-guessing game, seven in the same round and one held at the join page, under tabs for 8 participants and 7 findings" src="https://humanish.dev/runs/lobby-0927/observer-grid-light.webp">
+  </picture>
+</a>
+
+**[Watch the replay](https://humanish.dev/demo).** The image is the Observer partway through a
+saved study. Eight synthetic participants joined one lobby of a multiplayer movie-guessing game
+on its live deployment, each on its own hosted desktop, and each tile shows one participant's
+screen at the same moment of the recording. Six reached the final standings. Two were blocked,
+among them Player six, who arrived after the game started and is still on the join page. The
+Findings tab holds the seven findings the analysis wrote. The demo page replays this run in the
+Observer, and nothing runs from it.
 
 ## Learn how a study works
 
@@ -19,6 +30,14 @@ disposable browser VM on your machine. On the computer-use route a model drives
 participant: every turn it reads a screenshot and answers with mouse and keyboard actions, until
 the participant finishes, gets stuck or reaches a limit.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-player-dark.webp">
+  <img alt="The Observer with one participant open: its desktop during a round of a movie-guessing game, replay controls and a filmstrip of captures below, and on the right its trace, with the participant's reasoning and each TAB and ENTER keypress" src="https://humanish.dev/runs/lobby-0927/observer-player-light.webp">
+</picture>
+
+Player four from the run above, a keyboard-only participant: its screen, and beside it each
+keypress and the reasoning it wrote before acting.
+
 The run writes its evidence to gitignored `.humanish/runs/<run id>/`: screenshots, every
 action, each participant's report and the estimated cost. The Observer replays it,
 `humanish review` prints the findings of the analysis that follows a live run, and
@@ -26,6 +45,14 @@ action, each participant's report and the estimated cost. The Observer replays i
 [How a study works](https://humanish.dev/docs/concepts) walks through one annotated study file,
 and the [study file reference](https://humanish.dev/docs/study-files) lists every field.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://humanish.dev/runs/lobby-0927/observer-findings-dark.webp">
+  <img alt="The Observer's Findings tab: the first of seven findings, that three participants found keyboard guessing hard to track and one stopped mid-game, with the analysis's summary, what to check next, a cited capture and the timeline of evidence moments behind it" src="https://humanish.dev/runs/lobby-0927/observer-findings-light.webp">
+</picture>
+
+The first of the seven findings the analysis wrote for the same run, with the evidence moments
+it cites.
+
 ## Try it without keys
 
 In a project directory, with Node.js 22.19 or newer:
@@ -308,7 +335,7 @@ and the library exports.
 - Breaking changes ship together in one minor release. Its release notes carry a migration
   table: each old form, its new form, and the change to make.
 - The study file and the run bundle carry versioned schemas, `humanish.study.v3` and
-  `humanish.run-bundle.v1`. A breaking change to either one bumps its version.
+  `humanish.run-bundle.v2`. A breaking change to either one bumps its version.
 
 Pin the exact version in `package.json` and read [CHANGELOG.md](CHANGELOG.md) before upgrading.
 

package/dist/actors/computer-use/loop/trace.js

@@ -65,7 +65,12 @@ export function statusForCompletionReason(reason) {
 }
 export function loopResult(session, stop, debrief) {
     const { provider, settings, trace: recorder, usage } = session;
-    const { completionReason, reason, stopCause } = stop;
+    const { completionReason, stopCause } = stop;
+    // A participant whose session ended on the clock has its closing account as its reason, as one
+    // that ended the session itself has its last message; the stop cause keeps the scheduled end.
+    const reason = stopCause === "scheduled_end" && debrief?.report !== undefined
+        ? debrief.report.summary
+        : stop.reason;
     const completedAtMs = session.now();
     const status = statusForCompletionReason(completionReason);
     const ids = {};

package/dist/actors/computer-use/openai-conversation.d.ts

@@ -65,12 +65,6 @@ export declare class OpenAiConversation {
      * from the request being sent. False when none are asked for, so the rejection stands.
      */
     dropReasoningSummaries(): boolean;
-    /**
-     * Whether the server holds the whole session, so a closing report threaded on it reads every
-     * turn. An explicit-context conversation summarizes its oldest turns past its budget, configured
-     * or switched to at runtime.
-     */
-    get serverHoldsSession(): boolean;
     /** The trace's account of how the conversation was carried (ActorConversation). */
     record(): ActorConversation;
     /**

package/dist/actors/computer-use/openai-conversation.js

@@ -72,14 +72,6 @@ export class OpenAiConversation {
         this.reasoningSummary = undefined;
         return true;
     }
-    /**
-     * Whether the server holds the whole session, so a closing report threaded on it reads every
-     * turn. An explicit-context conversation summarizes its oldest turns past its budget, configured
-     * or switched to at runtime.
-     */
-    get serverHoldsSession() {
-        return this.mode === "threaded" && this.lastResponseId !== undefined;
-    }
     /** The trace's account of how the conversation was carried (ActorConversation). */
     record() {
         return this.evidence.snapshot(this.mode);

package/dist/actors/computer-use/openai-provider.js

@@ -509,14 +509,11 @@ export function createOpenAiResponsesProvider(options) {
         get conversation() {
             return conversation.record();
         },
-        // A retrospective report reads the session the server holds; see serverHoldsSession.
-        get debrief() {
-            return conversation.serverHoldsSession
-                ? (req, signal) => requestTurn(req, signal, "report")
-                : undefined;
-        },
-        // Offered in both modes. An explicit_context conversation carries its newest screens whole and
-        // earlier turns as text, which serves impressions; a closing report needs the whole session.
+        // Both are offered in both modes. A threaded request reads the session the server holds; an
+        // explicit_context one carries its newest screens whole and its oldest turns summarized past
+        // the budget, which the trace's conversation record counts. A participant that worked a long
+        // shift writes its closing account from what it carries, as a person writes one from memory.
+        debrief: (req, signal) => requestTurn(req, signal, "report"),
         requestImpressions: (req, signal) => requestTurn(req, signal, "impressions"),
     };
 }

package/dist/analysis/automatic.js

@@ -4,6 +4,7 @@ import {} from "../run/bundle.js";
 import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalysisRun, } from "./service.js";
 import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
 import { captureEvidence } from "./evidence.js";
+import { loadRunTraces } from "../run/stream-trace.js";
 import { hashAnalysisValue } from "./validation.js";
 import { refusedCost } from "./admission.js";
 import { claimAutomaticAnalysis, readAutomaticAnalysisPrepared, requestAutomaticAnalysisCancellationPrepared, } from "./job.js";
@@ -88,7 +89,7 @@ async function readAutomaticSource(cwd, prepared, configInput, deps, hasKey) {
     let config = configInput;
     try {
         const bytes = await readCompletedAnalysisSource(cwd, prepared);
-        const bundle = JSON.parse(bytes.toString("utf8"));
+        const bundle = await loadRunTraces(prepared, JSON.parse(bytes.toString("utf8")));
         if (bundle.streams.some((stream) => stream.actor?.stopCause === "harness_aborted"))
             return skipped("AUTOMATIC_ANALYSIS_ACTOR_CANCELLED");
         const participantEvidence = hasParticipantEvidence(bundle);

package/dist/analysis/evidence.js

@@ -3,7 +3,8 @@ import { createHash } from "node:crypto";
 import { screenshotEvidenceError } from "../evidence/image.js";
 import { runIdOf } from "../run/paths.js";
 import { isRecord } from "../run/type-guards.js";
-import { RUN_BUNDLE_FILE } from "../run/bundle.js";
+import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "../run/bundle.js";
+import { loadStreamTraces } from "../run/stream-trace.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { digestAnalysisInput, hashAnalysisValue, validateAnalysisInputMetadata, } from "./validation.js";
 import { boundedText, fairShares, hasUnmappedCaptures, participantAssignment, participantSource, sourceEntries, sourceOrder, impressionEventIds, } from "./evidence-sources.js";
@@ -29,7 +30,7 @@ function parseSource(prepared, bytes) {
         throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
     const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
     if (!isRecord(value) ||
-        value.schema !== "humanish.run-bundle.v1" ||
+        (value.schema !== RUN_BUNDLE_SCHEMA && value.schema !== RUN_BUNDLE_V1_SCHEMA) ||
         value.runId !== runIdOf(prepared) ||
         !Array.isArray(value.streams) ||
         value.streams.length > EVIDENCE_LIMITS.participants ||
@@ -49,24 +50,8 @@ function parseSource(prepared, bytes) {
             throw new Error("ANALYSIS_SOURCE_INVALID");
         }
         ids.add(stream.id);
-        const actor = stream.actor;
-        if (actor !== undefined &&
-            (!isRecord(actor) || !Array.isArray(actor.items) || actor.items.length > 100000)) {
+        if (stream.actor !== undefined && !isRecord(stream.actor))
             throw new Error("ANALYSIS_SOURCE_INVALID");
-        }
-        const eventIds = new Set();
-        for (const item of isRecord(actor) ? actor.items : []) {
-            if (!isRecord(item) ||
-                typeof item.id !== "string" ||
-                item.id.length === 0 ||
-                item.id.length > 256 ||
-                eventIds.has(item.id) ||
-                typeof item.kind !== "string" ||
-                typeof item.title !== "string" ||
-                (item.text !== undefined && typeof item.text !== "string"))
-                throw new Error("ANALYSIS_SOURCE_INVALID");
-            eventIds.add(item.id);
-        }
     }
     for (const event of value.events) {
         if (!isRecord(event) ||
@@ -77,6 +62,41 @@ function parseSource(prepared, bytes) {
     }
     return value;
 }
+/**
+ * run.json's bundle with each stream's trace loaded. The source limit applies to each trace file
+ * as it does to run.json; run.json's digest, which the analysis record binds, binds each trace's
+ * sha256.
+ */
+async function readSource(prepared, bytes, traceBytes) {
+    const stored = parseSource(prepared, bytes);
+    if (stored.streams.some((stream) => (stream.trace?.bytes ?? 0) > traceBytes))
+        throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
+    const loaded = await loadStreamTraces(prepared, stored, { maxBytes: traceBytes });
+    if (loaded.refused.length > 0)
+        throw new Error("ANALYSIS_SOURCE_INVALID");
+    for (const stream of loaded.bundle.streams)
+        validateTraceItems(stream.actor);
+    return loaded.bundle;
+}
+function validateTraceItems(actor) {
+    if (actor !== undefined &&
+        (!isRecord(actor) || !Array.isArray(actor.items) || actor.items.length > 100000)) {
+        throw new Error("ANALYSIS_SOURCE_INVALID");
+    }
+    const eventIds = new Set();
+    for (const item of isRecord(actor) ? actor.items : []) {
+        if (!isRecord(item) ||
+            typeof item.id !== "string" ||
+            item.id.length === 0 ||
+            item.id.length > 256 ||
+            eventIds.has(item.id) ||
+            typeof item.kind !== "string" ||
+            typeof item.title !== "string" ||
+            (item.text !== undefined && typeof item.text !== "string"))
+            throw new Error("ANALYSIS_SOURCE_INVALID");
+        eventIds.add(item.id);
+    }
+}
 /** Select once from retained source. Models receive no filesystem or network resolver. */
 export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     const limits = { ...EVIDENCE_LIMITS, ...requested };
@@ -92,7 +112,7 @@ export async function captureEvidence(prepared, bundleBytes, requested = {}) {
     const current = await readBoundedFile(prepared, RUN_BUNDLE_FILE, limits.sourceBytes);
     if (!current || !current.equals(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
-    const bundle = parseSource(prepared, bundleBytes);
+    const bundle = await readSource(prepared, bundleBytes, limits.sourceBytes);
     const captureVersion = ACTION_CAPTURE_VERSION;
     if (bundle.streams.some((stream) => stream.liveActor !== undefined || UNFINISHED_STREAM_STATUSES.has(stream.status))) {
         throw new Error("ANALYSIS_RUN_UNFINISHED");
@@ -393,7 +413,7 @@ function packEvidence(selected, packings, textByEntry, evidence, images) {
 export async function validateAnalysisEvidence(prepared, artifact, bundleBytes) {
     if (artifact.captureVersion !== undefined && artifact.captureVersion !== ACTION_CAPTURE_VERSION)
         throw new Error("ANALYSIS_CAPTURE_VERSION_INVALID");
-    const bundle = parseSource(prepared, bundleBytes);
+    const bundle = await readSource(prepared, bundleBytes, EVIDENCE_LIMITS.sourceBytes);
     if (artifact.runId !== bundle.runId || artifact.sourceRunSha256 !== sha256(bundleBytes))
         throw new Error("ANALYSIS_SOURCE_CHANGED");
     const included = new Set(artifact.coverage.includedStreamIds);

package/dist/cli/commands/study-run.js

@@ -84,7 +84,14 @@ export async function runStudyCommand(args) {
     // the keys its plan reads. This comes after the option refusals above, which read no key, and
     // before the route's CLI setup and prepareStudy, which do.
     if (resolveStudyDryRun(config, args.options.dryRun, true) === false) {
-        const announced = announcedKeyNames(config, args.options);
+        const planned = planStudy(config, { cwd: args.options.cwd, dryRun: false });
+        // The plan's warnings, such as a bundle estimated past a limit, before anything is created.
+        // The study file's own were printed above.
+        if (planned.ok)
+            for (const warning of planned.planned.plan.warnings ?? [])
+                if (!resolved.warnings.includes(warning))
+                    warnAndQueue(args.command, args.io, warning);
+        const announced = announcedKeyNames(config, args.options, planned);
         await discoverCliKeys({
             io: args.io,
             cwd: args.options.cwd,
@@ -150,10 +157,9 @@ export async function runStudyCommand(args) {
  * change who runs, not which keys. Undefined, so every fill is printed, when a scorer is declared,
  * since its host code may read any key, and when the study does not plan.
  */
-function announcedKeyNames(config, options) {
+function announcedKeyNames(config, options, planned) {
     if (options.scorer !== undefined || config.review?.scorer !== undefined)
         return undefined;
-    const planned = planStudy(config, { cwd: options.cwd, dryRun: false });
     return planned.ok ? keyNamesOf(planned.planned.plan) : undefined;
 }
 /** Each route's CLI setup. It returns undefined when it has already written its own result. */

package/dist/evidence/image.js

@@ -1,3 +1,4 @@
+import { crc32, inflateSync } from "node:zlib";
 import { PNG } from "pngjs";
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const PNG_IHDR_LENGTH = 13;
@@ -145,12 +146,90 @@ export function screenshotEvidenceError(relativePath, bytes) {
     if (chunks?.some((chunk) => chunk.type === "IEND" && chunk.end - chunk.start !== 12)) {
         return "PNG IEND chunk must be empty";
     }
+    return chunks === null || !pngStructureHolds(bytes, chunks)
+        ? "could not decode PNG evidence"
+        : null;
+}
+/** The bit depths PNG allows for each color type. */
+const PNG_BIT_DEPTHS = {
+    0: [1, 2, 4, 8, 16],
+    2: [8, 16],
+    3: [1, 2, 4, 8],
+    4: [8, 16],
+    6: [8, 16],
+};
+const PNG_CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+/** The fewest bytes the decoder reads from a chunk; a shorter one fails to decode. */
+const PNG_MIN_CHUNK_BYTES = { gAMA: 4 };
+/**
+ * Whether a PNG that passed pngDecodeRefusal decodes, read from its structure: the file ends at an
+ * empty IEND, every chunk's CRC matches, IHDR comes once with fields PNG defines, the image data is
+ * one run of IDAT chunks, and it inflates, with zlib's native code, to exactly the
+ * bytes its rows need with nothing after the stream, each row starting with a filter type from 0
+ * to 4. For an image without a palette that is all a decode establishes, at about an eighth of
+ * the time of pngjs, which unfilters every pixel in JavaScript; a run holds a screenshot for each
+ * turn. A palette image is also decoded, since each pixel must index a palette that comes before
+ * the image data; in any other image a palette chunk is only a suggestion, wherever it is.
+ */
+function pngStructureHolds(bytes, chunks) {
+    const last = chunks.at(-1);
+    if (last?.type !== "IEND" || last.end !== bytes.length)
+        return false;
+    const crcHolds = (chunk) => crc32(bytes.subarray(chunk.start + 4, chunk.end - 4)) === bytes.readUInt32BE(chunk.end - 4);
+    if (!chunks.every(crcHolds))
+        return false;
+    const types = chunks.map((chunk) => chunk.type);
+    const firstIdat = types.indexOf("IDAT");
+    const idats = chunks.filter((chunk) => chunk.type === "IDAT");
+    if (types.lastIndexOf("IHDR") !== 0 ||
+        firstIdat < 0 ||
+        types.lastIndexOf("IDAT") !== firstIdat + idats.length - 1)
+        return false;
+    const [width, height] = [bytes.readUInt32BE(16), bytes.readUInt32BE(20)];
+    const [depth, colorType, compression, filter] = [bytes[24], bytes[25], bytes[26], bytes[27]];
+    if (!PNG_BIT_DEPTHS[colorType]?.includes(depth) || compression !== 0 || filter !== 0)
+        return false;
+    // The decoder sizes a row in 32-bit arithmetic and refuses one wider; no screenshot is.
+    const rowBits = width * PNG_CHANNELS[colorType] * depth;
+    if (rowBits + 7 > 0x7fffffff)
+        return false;
+    const trnsBytes = colorType === 0 ? 2 : colorType === 2 ? 6 : 0;
+    const tooShort = (chunk) => chunk.end - chunk.start - 12 <
+        (chunk.type === "tRNS" ? trnsBytes : (PNG_MIN_CHUNK_BYTES[chunk.type] ?? 0));
+    if (chunks.some(tooShort))
+        return false;
+    const rowBytes = 1 + Math.ceil(rowBits / 8);
+    const data = Buffer.concat(idats.map((chunk) => bytes.subarray(chunk.start + 8, chunk.end - 4)));
+    let rows;
     try {
-        const decoded = PNG.sync.read(bytes, { checkCRC: true });
-        return pngDimensionsError(decoded.width, decoded.height);
+        // A stream that would inflate past the rows the image needs stops there, so a small file
+        // cannot claim gigabytes.
+        const options = {
+            maxOutputLength: rowBytes * height,
+            info: true,
+        };
+        const inflated = inflateSync(data, options);
+        if (inflated.engine.bytesWritten !== data.length)
+            return false;
+        rows = inflated.buffer;
     }
     catch {
-        return "could not decode PNG evidence";
+        return false;
+    }
+    if (rows.length !== rowBytes * height)
+        return false;
+    for (let row = 0; row < rows.length; row += rowBytes)
+        if (rows[row] > 4)
+            return false;
+    return colorType !== 3 || pngDecodes(bytes);
+}
+function pngDecodes(bytes) {
+    try {
+        PNG.sync.read(bytes, { checkCRC: true });
+        return true;
+    }
+    catch {
+        return false;
     }
 }
 export function assertScreenshotEvidence(relativePath, bytes) {

package/dist/feedback/derivative-text.d.ts

@@ -0,0 +1,12 @@
+import type { RunBundle } from "../run/bundle.js";
+/** A source file's path and bytes. */
+interface TextFile {
+    path: string;
+    bytes: Buffer;
+}
+export declare function jsonBytes(value: unknown): Buffer;
+export declare function transformText(file: TextFile, imagePaths: ReadonlySet<string>): Buffer;
+export declare function assertRewritableNumbers(json: string): void;
+/** The loaded source bundle as the copy records it: screenshots declared and labelled blurred. */
+export declare function derivedBundle(bundle: RunBundle, imagePaths: ReadonlySet<string>): RunBundle;
+export {};

package/dist/feedback/derivative-text.js

@@ -0,0 +1,130 @@
+// How a redacted copy rewrites a run's text: screenshots declared blurred, sandbox ids redacted,
+// inline images and secret-shaped text refused. src/feedback/export-bundle.ts copies the files.
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ACTOR_TRACE_SCHEMA } from "../actors/contract.js";
+import { containsSensitive, redactSandboxIds } from "../evidence/redaction.js";
+import { decodeEscapes, readingsOf } from "../evidence/encoded-text.js";
+import { readPlainText } from "../evidence/plain-text.js";
+export function jsonBytes(value) {
+    return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+}
+function assertNoInlineRaster(text) {
+    // Decode the escapes verify decodes (decodeEscapes) before checking. Unknown embedded bytes are
+    // refused: copying a text extension must not smuggle untransformed pixels.
+    if (readingsOf(text).some(containsSensitive))
+        throw new Error("Decoded text contains a secret-shaped value or private path; export refused.");
+    const decoded = decodeEscapes(text);
+    if (/data\s*:\s*(?:image\/|application\/|text\/|[^,\s]*;base64,|,)/i.test(decoded) ||
+        /iVBORw0KGgo|\/9j\/[A-Za-z0-9+/]|R0lGOD|UklGR[A-Za-z0-9+/]{4}|<svg\b/i.test(decoded)) {
+        throw new Error("Text contains an inline image/data payload; embedded raster redaction is unsupported.");
+    }
+}
+function decodeText(file) {
+    const decoded = readPlainText(file.bytes);
+    if (!decoded.ok)
+        throw new Error(decoded.reason === "invalid-utf8"
+            ? "Source text contains invalid UTF-8 or binary bytes."
+            : "Source text contains binary control bytes.");
+    assertNoInlineRaster(decoded.text);
+    return decoded.text;
+}
+function updateScreenshotDeclarations(value, imagePaths) {
+    if (Array.isArray(value))
+        return value.map((entry) => updateScreenshotDeclarations(entry, imagePaths));
+    if (value === null || typeof value !== "object")
+        return value;
+    const object = value;
+    const result = Object.create(null);
+    for (const [key, entry] of Object.entries(object))
+        result[key] = updateScreenshotDeclarations(entry, imagePaths);
+    if (object.schema === ACTOR_TRACE_SCHEMA &&
+        object.redaction !== null &&
+        typeof object.redaction === "object") {
+        const original = object.redaction;
+        if (original.screenshots === "raw" || original.screenshots === "blurred") {
+            result.redaction = {
+                ...original,
+                screenshots: "blurred",
+                notes: `${typeof original.notes === "string" ? original.notes : ""} Exported copy: screenshots blurred during export; original capture posture: ${original.screenshots}. See derivation.json.`,
+            };
+        }
+        if (Array.isArray(result.items)) {
+            result.items = result.items.map((item) => {
+                if (item === null || typeof item !== "object")
+                    return item;
+                const entry = item;
+                if (entry.screenshotRef === undefined)
+                    return item;
+                if (entry.screenshotRef === null || typeof entry.screenshotRef !== "object")
+                    throw new Error("Actor screenshot reference is malformed.");
+                const ref = entry.screenshotRef;
+                if (typeof ref.path !== "string" || !imagePaths.has(ref.path)) {
+                    throw new Error("Actor screenshot reference must resolve to a PNG transformed from this run's inventory.");
+                }
+                return { ...entry, screenshotRef: { ...ref, redaction: "blurred" } };
+            });
+        }
+    }
+    return result;
+}
+export function transformText(file, imagePaths) {
+    const text = decodeText(file);
+    const extension = path.extname(file.path).toLowerCase();
+    if (extension === ".json") {
+        const parsed = JSON.parse(text);
+        // Parsing also resolves escape sequences in string values before inspection.
+        assertNoInlineRaster(JSON.stringify(parsed));
+        // The copy names no sandbox: an id is local operational evidence, and the copy is shared.
+        const transformed = redactSandboxIds(updateScreenshotDeclarations(parsed, imagePaths));
+        if (JSON.stringify(transformed) === JSON.stringify(parsed))
+            return file.bytes;
+        assertRewritableNumbers(text);
+        return jsonBytes(transformed);
+    }
+    if (extension === ".ndjson" || extension === ".jsonl") {
+        const lines = text.split("\n");
+        const transformed = lines.map((line) => {
+            if (line.trim().length === 0)
+                return line;
+            const parsed = JSON.parse(line);
+            assertNoInlineRaster(JSON.stringify(parsed));
+            const updated = JSON.stringify(redactSandboxIds(updateScreenshotDeclarations(parsed, imagePaths)));
+            if (updated === JSON.stringify(parsed))
+                return line;
+            assertRewritableNumbers(line);
+            return updated;
+        });
+        return Buffer.from(transformed.join("\n"));
+    }
+    if (extension === ".yaml" || extension === ".yml") {
+        assertNoInlineRaster(JSON.stringify(parseYaml(text, { maxAliasCount: 100, logLevel: "silent" })) ?? "");
+    }
+    return file.bytes;
+}
+export function assertRewritableNumbers(json) {
+    // Opaque adapter JSON stays byte-identical. A known trace that actually needs
+    // rewriting must not silently round an identifier outside JS's integer range.
+    const unquoted = json.replace(/"(?:\\.|[^"\\])*"/g, '""');
+    for (const match of unquoted.matchAll(/-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
+        const number = Number(match[0]);
+        if (!Number.isFinite(number) || (Number.isInteger(number) && !Number.isSafeInteger(number))) {
+            throw new Error("A trace requiring redaction contains an unsafe numeric value; represent large identifiers as strings before capture.");
+        }
+    }
+}
+/** The loaded source bundle as the copy records it: screenshots declared and labelled blurred. */
+export function derivedBundle(bundle, imagePaths) {
+    const transformed = redactSandboxIds(updateScreenshotDeclarations(bundle, imagePaths));
+    transformed.redaction = {
+        status: "passed",
+        notes: `${bundle.redaction.notes} Exported copy: screenshots were blurred during export; the original capture is retained separately. See derivation.json.`,
+    };
+    for (const stream of transformed.streams) {
+        for (const artifact of stream.artifacts) {
+            if (artifact.kind === "screenshot")
+                artifact.label = artifact.label.replace(/\((raw|blurred)\)/g, "(blurred at export)");
+        }
+    }
+    return transformed;
+}