humanish 0.124.0 → 0.126.0

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";
@@ -16,6 +16,7 @@ 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, scanSourceEvidence, streamScreenshotPaths, unscannedMessage, } from "./artifacts.js";
 import { flatContextWarnings } from "./context-growth.js";
+import { pageFindings } from "./pages.js";
 import { runNotFinished } from "./liveness.js";
 import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
@@ -229,7 +230,7 @@ function evidenceArtifactsCheck(shaped, problems) {
 async function loadTraces(runPaths, stored) {
     const scanned = { sensitive: [], opaque: [] };
     if (!isRunBundle(stored))
-        return { bundle: stored, refusedTraces: [], ...scanned };
+        return { bundle: stored, refusedTraces: [], ...scanned, pages: [] };
     // 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, {
@@ -239,9 +240,14 @@ async function loadTraces(runPaths, stored) {
                 scanned[scan === "sensitive" ? "sensitive" : "opaque"].push(file);
         },
     });
-    return { bundle, refusedTraces: refused.map((error) => error.message), ...scanned };
+    return {
+        bundle,
+        refusedTraces: refused.map((error) => error.message),
+        ...scanned,
+        pages: pageFindings(bundle),
+    };
 }
-/** The trace scan's results, beside the walk's: each file named once. */
+/** The trace scan's results, beside the walk's: each file named once, then each page finding. */
 function addTraceScan(traces, findings, unscanned) {
     for (const file of traces.sensitive)
         if (!findings.includes(`sensitive text ${file}`))
@@ -249,6 +255,7 @@ function addTraceScan(traces, findings, unscanned) {
     for (const file of traces.opaque)
         if (!unscanned.files.includes(file))
             unscanned.files.push(file);
+    findings.push(...traces.pages);
 }
 /** The top-level run.json sections the shape guard requires. */
 const REQUIRED_SECTIONS = [
@@ -272,7 +279,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 +312,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 +446,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/actor-contract.md

@@ -167,6 +167,7 @@ export interface ActorTraceItem {
   command?: { text?: string; cwd?: string; exitCode?: number; outputTail?: string };
   screenshotRef?: { path: string; redaction: "blurred" | "ocr_scrubbed" | "none" };
   text?: string; // redacted
+  page?: { origin: string; path: string }; // computer-use screenshot items; redacted, no query
 }
 
 export interface ActorCapabilities {
@@ -204,6 +205,7 @@ export interface ActorTrace {
   ids: { sessionId?: string; threadId?: string; turnId?: string; model?: string };
   counts: Record<string, number>;
   items: ActorTraceItem[];
+  finalPage?: { origin: string; path: string }; // computer-use: the last observation's page
   tokenUsage?: { input?: number; output?: number; total?: number; costUsd?: number };
   estimatedCost?: ActorEstimatedCost; // humanish.actor-estimated-cost.v1 (additive)
   capabilities: ActorCapabilities;

package/docs/architecture/external-public-shared-world.md

@@ -120,7 +120,10 @@ The runtime `location.href` (and the 6-char code inside it) is never persisted r
 runtime-only; the threaded code flows only into the follower's composed prompt (never a raw bundle
 field) and is scrubbed from all narration once latched; the shared origin and lobby path persist only
 as sha256-16 digests (`publicOriginDigest`, `lobbyConvergenceDigest`). This matches the existing
-e2b-URL / host-digest redaction discipline.
+e2b-URL / host-digest redaction discipline. The computer-use loop records each observation's page
+origin and path by default; the shared-world runner (`participantRunDeps` in
+`src/routes/shared-world/participant-specs.ts`) runs every session with `recordPages: false`, on
+both planes, so no page and no `finalPage` reaches a shared-world trace.
 
 ## Mobile fidelity caveat
 

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/architecture/observer.md

@@ -74,7 +74,16 @@ public-safe metadata.
 
 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
+items, from one read of the run per poll. While a participant runs, its entry in
+`items` carries `live`, a cursor `<position>.<generation>.<items>.<bytes>` naming its
+live file (`live/<position>.<generation>.ndjson`) and how far the list goes. The page
+sends the cursors of its last body back as `?after=<cursor>,<cursor>`, and the server
+then reads and sends only the items past each one, marking that entry with
+`liveAfter`, the cursor they follow (`src/observer/feed-cursors.ts`). A cursor for an
+earlier generation, past the index or off a line end gets the participant's full list,
+and so does every participant of a finished run. A tail is checked for line ends and
+its line count; the sha256 run.json records is checked whenever a list is read whole.
+A page that cannot join a body sends no cursors with its next 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.

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.

package/docs/contracts/policy.md

@@ -146,6 +146,13 @@ certification that the artifact is free of every class in the policy below. A
 first-class PII/PHI detector is [planned](https://github.com/danielgwilson/humanish/issues/108) and would move the listed
 PII classes from author-responsibility to enforced.
 
+The same scan reads the page each computer-use observation recorded (`items[].page`,
+`finalPage`). verify also reports a page whose path holds a query string or fragment, or whose
+origin holds user info or anything after the host, since such a part can carry a short token no
+pattern matches. The recorder withholds email- and token-shaped path segments
+([schemas.md](schemas.md#actor-trace)); a name or other personal data in a readable path is not
+detected.
+
 Required redaction gates:
 
 - run bundle verification;

package/docs/contracts/run-bundle.md

@@ -1,6 +1,6 @@
 # Run Bundle Contract
 
-`humanish.run-bundle.v2` is the evidence contract. The TypeScript shape in `src/run/bundle.ts`
+`humanish.run-bundle.v3` 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
@@ -46,7 +46,11 @@ impressions, token usage and estimated cost. Each trace is written once.
 `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.
+A reader outside humanish loads a run through the package's `loadRunBundle(cwd, run)`, with `run`
+a run id or `latest`: it returns run.json with every trace file and live file joined and checked
+as below, for v1, v2 and v3 bundles, and throws an Error named `StreamTraceRefusedError` for a
+file that does not match its index. Inside humanish, 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
@@ -60,12 +64,69 @@ apart from its walk of the run folder, so no path exemption the walk makes appli
 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.
+so a run.json from v2 on never holds `actor.items`. A participant still working has its items so
+far in `streams[].liveActor`. A 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 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.
+
+## Live items
+
+From v3, a running participant's items so far are in a live file, so a flush appends only the
+items recorded since the last one instead of rewriting run.json with every item. The run writer
+(`liveItemsWriter` in `src/run/live-items.ts`, called from `src/run/run.ts`) keeps, for each
+stream with a `liveActor`:
+
+- the live file `live/<position>.<generation>.ndjson`, `position` the stream's place in
+  `streams[]` (from 1). Each line is one trace item as JSON, scrubbed of the run's raw sandbox ids
+  as it is appended. A live file is never truncated or rewritten;
+- in run.json, `liveActor` as `humanish.live-actor.v2`: its summary fields (`updatedAt`,
+  `persona`, `tokenUsage`, `ids`, `executionProfile`, `providerRequests`, `historyTurnsOmitted`,
+  `estimatedCost`) and, in place of `items`, the index of the prefix written so far:
+
+```yaml
+liveActor:
+  schema: humanish.live-actor.v2
+  updatedAt: "<ISO timestamp>"
+  itemsFile:
+    path: live/1.1.ndjson
+    generation: 1
+    items: 4210 # lines in the indexed prefix
+    bytes: 1048211 # the indexed prefix's size
+    sha256: "<hex digest of the indexed prefix>"
+```
+
+Each write appends the items past the indexed count, syncs them, then writes run.json, so run.json
+never indexes bytes that are not on disk. The sha256 is a running hash, so no write rehashes a
+file. The writer starts the next generation, holding the participant's full list, when appending
+cannot keep the file equal to that list: the list shrank, an item already written is not the same
+object it wrote, an append failed, or a sandbox id the run learned since occurs in the current
+generation. Once run.json naming the new generation is written, the writer removes every earlier
+one, so at most two generations of a participant exist at once. A failed removal or a failed
+run.json write keeps the earlier generations until the next run.json is written, which removes
+them. The live flush deep-freezes each item it is handed, so a producer that edits an item after
+recording it throws there; a producer records a new item instead.
+
+A write that starts a new generation copies the participant's whole list, as every flush did
+before v3. When a participant's generation is replaced on two writes in a row, the run records one
+warn event in `events`, type `live-items.rewritten`, with that stream's `streamId`, and keeps it in
+every later write. A run records at most one.
+
+`Run.finish` writes the final trace files and run.json, then removes every live file it wrote and
+`live/`, so a finished v3 bundle holds no live files and differs from v2 only in its schema name.
+A run that ends without its final write (interrupted, or killed) keeps its live files and the
+last run.json that indexes them.
+
+Readers load live items through the same loader as traces: `loadStreamTraces` reads exactly the
+indexed bytes of the live file (bytes appended after run.json was written are not read), refuses
+them unless their size, sha256 and line count match the index and each line is a JSON object,
+and returns the stream with `liveActor.items` and without `itemsFile`. It refuses a `liveActor`
+schema it does not know, and inline live items (`humanish.live-actor.v1`) in a v3 run.json. A
+reader that cannot read a live file reads run.json again once and loads that bundle instead, since
+the writer may have removed a superseded generation, or every live file at finish, after the
+reader read run.json. v1 and v2 run.json keep `liveActor.items` inline (`humanish.live-actor.v1`)
+and load as before.
 
 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
@@ -81,10 +142,11 @@ 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.
+Compatibility: humanish 0.122.0 and earlier read only v1 and refuse a v2 or v3 run.json by its
+schema (`run schema` fails in verify, analysis refuses the source); 0.123.0 and 0.124.0 read v1
+and v2 and refuse v3 the same way. This release reads v1 and v2 bundles as they are, with no
+migration. An exported copy (`humanish export --format bundle`) is written as v3 whatever the
+source version.
 
 ## Purpose
 
@@ -95,7 +157,7 @@ feedback drafts and future public issues.
 ## Minimum Bundle Shape
 
 ```yaml
-schema: humanish.run-bundle.v2 # v1 bundles are still read
+schema: humanish.run-bundle.v3 # v2 and v1 bundles are still read
 runId: "<core run id>"
 mode: "dry-run|live"
 simCount: 1
@@ -270,7 +332,7 @@ An actor trace may include `stopCause` alongside its unchanged `status`,
 `completionReason` and verbatim `reason`. Computer-use sessions distinguish
 `provider_output_limit`, `provider_token_limit`, `time_limit`, `spend_limit`,
 `study_spend_limit`, `adapter_limit`, `provider_incomplete`, `provider_status`,
-`provider_refused_prompt`, `harness_aborted`, `usage_unreported`, and `scheduled_end`. Absence means the route or
+`provider_refused_prompt`, `harness_aborted`, `usage_unreported`, `scheduled_end`, and `session_cap`. Absence means the route or
 recording did not retain this precise field; it does not mean the participant
 finished.
 
@@ -392,6 +454,36 @@ contain the older requested-screen `stream.viewport` shape without `desktopGeome
 Deterministic Playwright-style adapters remain free to declare a viewport that they also render
 exactly; this hosted-desktop rule does not change that contract.
 
+## Desktop Files
+
+A hosted computer-use participant's stream carries `desktopFiles` when its study gave it
+`participants[].files`: one entry per file confirmed on the desktop before the participant
+started, in the order they landed.
+
+```yaml
+desktopFiles:
+  - as: Downloads/insurance-card.png
+    size: 251
+    sha256: <64 hex characters>
+```
+
+`as` is relative to the desktop user's home folder. `size` is the byte count humanish copied,
+which `files.getInfo` on the desktop matched. `sha256` is the digest of those bytes, read on the
+host before any sandbox existed. The contents and the `from` path are not recorded. A participant
+whose copy failed records the files confirmed before the failure. No `desktopFiles` means no file
+was confirmed on that desktop: the study gave the participant none, the run was a dry run, or the
+copy failed before the first file was confirmed. A copy that failed records a `warn` event of type
+`cua-lab.desktop.files.completed`.
+
+## Participant Time Zone
+
+A computer-use or shared-world participant's stream carries `timeZone`, a tz database name such as
+`Europe/London`, when its study gave it one: `participants[].clock.timeZone`, else
+`actor.clock.timeZone`. Its turns gave the local time in that zone, and on a hosted desktop its
+browser launched with `TZ` set to it. The field records the declared zone, also on a dry run; it is
+not read back from the browser. No `timeZone` means the participant had none, and its hosted
+browser ran in the desktop's UTC.
+
 ## Subject Provenance
 
 `subject` is an optional, additive top-level field: structured provenance for

package/docs/contracts/schemas.md

@@ -24,38 +24,38 @@ workflow without leaking private upstream truth into core.
 
 ## Contract Index
 
-| Contract                          | Schema                                                                                                                                                                                                                                                    | Public-safe fixture                                                                 |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| 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`                                                              |
-| Scenario                          | `humanish.scenario.v1`                                                                                                                                                                                                                                    | `first-run-smoke`                                                                   |
-| Actor trace                       | `humanish.actor-trace.v1`                                                                                                                                                                                                                                 | `synthetic-actor-trace`                                                             |
-| Substrate                         | reserved (never shipped)                                                                                                                                                                                                                                  | none                                                                                |
-| Evidence stream                   | reserved (streams live inside the run bundle)                                                                                                                                                                                                             | see [`run-bundle.md`](run-bundle.md)                                                |
-| Review                            | `humanish.review.v1`                                                                                                                                                                                                                                      | `contract-proof-review`                                                             |
-| Study analysis                    | `humanish.study-analysis.v1` (prompt `study-evidence-7` adds `findings[].headline`, `findings[].experience` and `designFindings[]`; older artifacts omit them; `study-evidence-8` adds participant impressions to the instructions, with no field change) | see [study analysis](study-analysis.md) and synthetic analysis fixtures in `tests/` |
-| Study analysis correction         | `humanish.study-analysis-correction.v1`                                                                                                                                                                                                                   | see [study analysis](study-analysis.md#human-review-and-sharing)                    |
-| Analysis findings view            | `humanish.analysis-findings.v1` (`review --json` field `analysis`; read-only projection of the selected analysis)                                                                                                                                         | see [study analysis](study-analysis.md#reading-findings)                            |
-| Analysis execution receipt        | `humanish.analysis-execution.v1`                                                                                                                                                                                                                          | see [study analysis](study-analysis.md#durable-records)                             |
-| Analysis execution start          | `humanish.analysis-execution-start.v1`                                                                                                                                                                                                                    | see [study analysis](study-analysis.md#durable-records)                             |
-| Verification                      | `humanish.verify-result.v1`                                                                                                                                                                                                                               | `five-check-verify`                                                                 |
-| Policy                            | `humanish.policy.v1` (fixture-only; not engine-validated)                                                                                                                                                                                                 | `public-safety-policy`                                                              |
-| Feedback                          | `humanish.feedback.v1`                                                                                                                                                                                                                                    | `public-safe-feedback`                                                              |
-| Terminal cost ledger              | `humanish.terminal-cost-ledger.v1`                                                                                                                                                                                                                        | see Terminal Cost Ledger below                                                      |
-| Terminal no-spend proof           | `humanish.terminal-no-spend-proof.v1`                                                                                                                                                                                                                     | see Terminal Cost Ledger below                                                      |
-| Pricing (operator-editable rates) | `humanish.pricing.v1` (`src/run/pricing.ts`; dated per-model + E2B desktop rates)                                                                                                                                                                         | see Run Cost Summary And Estimated Actor Cost below                                 |
-| Run cost summary                  | `humanish.run-cost-summary.v1` (additive `RunBundle.cost`; estimate, never a charge)                                                                                                                                                                      | see Run Cost Summary And Estimated Actor Cost below                                 |
-| Estimated actor cost              | `humanish.actor-estimated-cost.v1` (additive `ActorTrace.estimatedCost`)                                                                                                                                                                                  | see Run Cost Summary And Estimated Actor Cost below                                 |
-| Model settings                    | `humanish.model-settings.v1` (additive `ActorTrace.modelSettings`; the reasoning effort the request carried)                                                                                                                                              | see Actor Trace below                                                               |
-| Affordance use                    | `humanish.affordance-use.v1` (additive `ActorTrace.affordanceUse`; per-class counts of the routes an actor took)                                                                                                                                          | see Affordance Use below                                                            |
-| Adapter score                     | `humanish.adapter-score.v1` (`RunBundle.adapterScore`; namespaced; route-specific acceptance semantics)                                                                                                                                                   | see Product-Adapter Extension Seam below                                            |
-| Adapter artifact                  | `humanish.adapter-artifact.v1` (`RunBundle.adapterArtifacts[]`; namespaced; local relative proof references)                                                                                                                                              | see Product-Adapter Extension Seam below                                            |
-| Shared-world evidence             | `humanish.shared-world.v1` (additive `RunBundle.sharedWorld` + `RunBundle.attributionClass`; `topologyMode: sequential \| concurrent`)                                                                                                                    | see Shared-World Evidence below                                                     |
-| Comms thread                      | `humanish.comms-thread.v1` (off-app email/SMS the app sent, captured; a `kind: log` run-dir artifact of digests only: from/to/subject/link digests + one OTP count, never raw)                                                                            | see `comms` under Study File                                                        |
-| Serve result                      | `humanish.serve-result.v1` (`src/observer/serve.ts` is authoritative)                                                                                                                                                                                     | none (command result envelope; see Serve Result below)                              |
-| Serve control plane               | reserved (`/_humanish/api/*` answers `501` `HUMANISH_SERVE_CONTROL_PLANE_DISABLED` in v1)                                                                                                                                                                 | none                                                                                |
+| Contract                          | Schema                                                                                                                                                                                                                                                                                           | Public-safe fixture                                                                 |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| Run bundle                        | `humanish.run-bundle.v3` (each participant's trace in its own file, indexed by `streams[].trace`, and a running participant's items so far in a live file indexed by `streams[].liveActor.itemsFile`; v2 bundles, with running items inline, and 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`                                                              |
+| Scenario                          | `humanish.scenario.v1`                                                                                                                                                                                                                                                                           | `first-run-smoke`                                                                   |
+| Actor trace                       | `humanish.actor-trace.v1`                                                                                                                                                                                                                                                                        | `synthetic-actor-trace`                                                             |
+| Substrate                         | reserved (never shipped)                                                                                                                                                                                                                                                                         | none                                                                                |
+| Evidence stream                   | reserved (streams live inside the run bundle)                                                                                                                                                                                                                                                    | see [`run-bundle.md`](run-bundle.md)                                                |
+| Review                            | `humanish.review.v1`                                                                                                                                                                                                                                                                             | `contract-proof-review`                                                             |
+| Study analysis                    | `humanish.study-analysis.v1` (prompt `study-evidence-7` adds `findings[].headline`, `findings[].experience` and `designFindings[]`; older artifacts omit them; `study-evidence-8` adds participant impressions to the instructions, with no field change)                                        | see [study analysis](study-analysis.md) and synthetic analysis fixtures in `tests/` |
+| Study analysis correction         | `humanish.study-analysis-correction.v1`                                                                                                                                                                                                                                                          | see [study analysis](study-analysis.md#human-review-and-sharing)                    |
+| Analysis findings view            | `humanish.analysis-findings.v1` (`review --json` field `analysis`; read-only projection of the selected analysis)                                                                                                                                                                                | see [study analysis](study-analysis.md#reading-findings)                            |
+| Analysis execution receipt        | `humanish.analysis-execution.v1`                                                                                                                                                                                                                                                                 | see [study analysis](study-analysis.md#durable-records)                             |
+| Analysis execution start          | `humanish.analysis-execution-start.v1`                                                                                                                                                                                                                                                           | see [study analysis](study-analysis.md#durable-records)                             |
+| Verification                      | `humanish.verify-result.v1`                                                                                                                                                                                                                                                                      | `five-check-verify`                                                                 |
+| Policy                            | `humanish.policy.v1` (fixture-only; not engine-validated)                                                                                                                                                                                                                                        | `public-safety-policy`                                                              |
+| Feedback                          | `humanish.feedback.v1`                                                                                                                                                                                                                                                                           | `public-safe-feedback`                                                              |
+| Terminal cost ledger              | `humanish.terminal-cost-ledger.v1`                                                                                                                                                                                                                                                               | see Terminal Cost Ledger below                                                      |
+| Terminal no-spend proof           | `humanish.terminal-no-spend-proof.v1`                                                                                                                                                                                                                                                            | see Terminal Cost Ledger below                                                      |
+| Pricing (operator-editable rates) | `humanish.pricing.v1` (`src/run/pricing.ts`; dated per-model + E2B desktop rates)                                                                                                                                                                                                                | see Run Cost Summary And Estimated Actor Cost below                                 |
+| Run cost summary                  | `humanish.run-cost-summary.v1` (additive `RunBundle.cost`; estimate, never a charge)                                                                                                                                                                                                             | see Run Cost Summary And Estimated Actor Cost below                                 |
+| Estimated actor cost              | `humanish.actor-estimated-cost.v1` (additive `ActorTrace.estimatedCost`)                                                                                                                                                                                                                         | see Run Cost Summary And Estimated Actor Cost below                                 |
+| Model settings                    | `humanish.model-settings.v1` (additive `ActorTrace.modelSettings`; the reasoning effort the request carried)                                                                                                                                                                                     | see Actor Trace below                                                               |
+| Affordance use                    | `humanish.affordance-use.v1` (additive `ActorTrace.affordanceUse`; per-class counts of the routes an actor took)                                                                                                                                                                                 | see Affordance Use below                                                            |
+| Adapter score                     | `humanish.adapter-score.v1` (`RunBundle.adapterScore`; namespaced; route-specific acceptance semantics)                                                                                                                                                                                          | see Product-Adapter Extension Seam below                                            |
+| Adapter artifact                  | `humanish.adapter-artifact.v1` (`RunBundle.adapterArtifacts[]`; namespaced; local relative proof references)                                                                                                                                                                                     | see Product-Adapter Extension Seam below                                            |
+| Shared-world evidence             | `humanish.shared-world.v1` (additive `RunBundle.sharedWorld` + `RunBundle.attributionClass`; `topologyMode: sequential \| concurrent`)                                                                                                                                                           | see Shared-World Evidence below                                                     |
+| Comms thread                      | `humanish.comms-thread.v1` (off-app email/SMS the app sent, captured; a `kind: log` run-dir artifact of digests only: from/to/subject/link digests + one OTP count, never raw)                                                                                                                   | see `comms` under Study File                                                        |
+| Serve result                      | `humanish.serve-result.v1` (`src/observer/serve.ts` is authoritative)                                                                                                                                                                                                                            | none (command result envelope; see Serve Result below)                              |
+| Serve control plane               | reserved (`/_humanish/api/*` answers `501` `HUMANISH_SERVE_CONTROL_PLANE_DISABLED` in v1)                                                                                                                                                                                                        | none                                                                                |
 
 ## Study File
 
@@ -210,6 +210,24 @@ The rest of this section names keys by their v3 spelling:
   Public/non-loopback targets still require `policies.allowPublicTargets: true`.
   `target` is mutually exclusive with `entry`: `target` is an absolute app-url
   browser target; `entry` is a shared-world participant's same-origin path;
+- `participants[].files` (computer-use on `execution.target: e2b-desktop` only):
+  1 to 20 `{ from, as }` entries, each a file copied onto that participant's desktop
+  before its browser opens. `from` is relative to the folder that holds the study file
+  (`cwd` for a library config); `as` is relative to the desktop user's home folder.
+  The parser refuses an absolute path, a `.`, `..` or empty part, a backslash, an `as`
+  that starts with `~`, lands in `subject/` or on a name starting with `.humanish`, looks
+  like a secret, a local path or encoded text, repeats another `as` or is its folder,
+  and a `from` the local-tree denylist names in any case (`isLocalTreeDenylisted` in
+  `src/subject/local-tree-archive.ts`). The route also refuses an `as` that holds a
+  value from the run's environment, such as a key. The route reads each distinct `from` once, before
+  any sandbox and on dry runs too, with `readContainedRegularFile`: a missing file, a
+  folder, a symbolic or hard link, a path out of the folder, a file above 10 MiB, more
+  than 25 MiB for one participant or 100 MiB of distinct files for the study is
+  refused with `HUMANISH_COMPUTER_USE_DESKTOP_FILES_INVALID` (`readDesktopFiles` in
+  `src/study/desktop-files.ts`). Each file
+  is written with the E2B SDK's `files.write` and its `files.getInfo` size must match, or
+  the participant fails before its first turn. The stream records `desktopFiles`
+  ([run-bundle.md](run-bundle.md#desktop-files)). Other routes refuse the field;
 - a `participants` entry with `count: n` (computer-use E2B route): a group of
   repeated participants. It needs an `id` and the parser expands it to
   `<id>-01` … `<id>-NN`, even when n is 1, before the engine runs (`viewer-01`,
@@ -235,17 +253,42 @@ The rest of this section names keys by their v3 spelling:
   participant's session budget is its window plus 5 minutes (`participantSessionMs` in
   `src/study/arrivals.ts`) in place of `execution.timeoutMs`, and its sandbox deadline adds the
   route's headroom to that. At the end the loop requests the closing report (`debrief.trigger:
-  scheduled_end`) and the session ends `goal_satisfied` with `stopCause: scheduled_end`. Before
+  scheduled_end`) and the session ends `goal_satisfied` with `stopCause: scheduled_end`. The
+  outcome an accepted report declares, its `outcome` field or the first line of its summary, is
+  the trace's `declaredOutcome`. The blocker rule reads a declared `reached` or `blocked` before
+  the summary, and after a declared `not_reached` it reads the summary. Before
   the end, a turn that requests no action does not end the session: the trace records a
   `participant ended before its scheduled end` notice, the next request says the time left, and
   the turn counts toward the idle backstop. Before the end, a turn that only waits or takes
   screenshots counts toward neither backstop streak (`advanceBackstop`'s `waitingIsTheTask`). The
   plan entry carries `endAfterMs`, and `study check` prints a `windows` row;
+- `participants[].maxSessionMs` (computer-use only, also on `count:` groups): the longest the
+  participant's session lasts, in whole milliseconds from 1 to 86,400,000, counted from the start
+  of its own session. `windDownMs` applies to it as to `endAfterMs`. Refused: a value outside that
+  range, `maxSessionMs` beside `endAfterMs` on one participant, `maxSessionMs` on `shared-world`,
+  and a cap whose sandbox deadline passes the sandbox ceiling. The session budget is the cap plus
+  5 minutes (`participantSessionMs`) in place of `execution.timeoutMs`, and the schedule holds the
+  participant's slot that long. The route reads the cap's end when the session starts
+  (`participantEnd` in `src/study/arrivals.ts`, `participantClock` in
+  `src/routes/computer-use/participant-model.ts`) and passes it to the loop as
+  `clock.end` with `kind: session_cap`. The participant may end its session before the cap, and
+  its waiting turns count toward the backstops. At the cap the loop requests the closing report
+  (`debrief.trigger: session_cap`) and the session ends `goal_satisfied` with
+  `stopCause: session_cap`, its report's declared outcome read as at a scheduled end. The plan
+  entry carries `maxSessionMs`, and the plan line shows
+  `cap=<duration>`;
 - `participants[].idleWaitMs` (computer-use and shared-world, also on `count:` groups): this
   participant's `actor.idleWaitMs`, in the same range and refused above an explicit
   `actor.maxWaitMs` (`waitLimitValidationReason`). Its trace records it in `waitSettings`;
-- `actor.clock.timeZone` (computer-use): a tz database time zone name, such as `Europe/London`. Each turn's context hint carries
-  the local time in it, and a scheduled end is given in it (UTC without it);
+- `actor.clock.timeZone` (computer-use and shared-world): a tz database time zone name, such as `Europe/London`. Each turn's context hint carries
+  the local time in it, and a scheduled end or session cap is given in it (UTC without it). On a hosted desktop the
+  participant's browser launches with `TZ` set to it (`openParticipantSurface` in
+  `src/routes/computer-use/e2b-desktop/start.ts`). `parseClock` in `src/study/parse/clock.ts` refuses a name Intl does not know, a
+  UTC offset and a case variant of Intl's spelling, which Chrome's ICU reads as UTC or `Etc/Unknown`. The computer-use planner
+  refuses a zone on the local runtime and the in-process route with `HUMANISH_COMPUTER_USE_TIME_ZONE_UNSUPPORTED`;
+- `participants[].clock.timeZone` (computer-use and shared-world, also on `count:` groups): this participant's `actor.clock`,
+  with the same rule. The plan's `limits.timeZone` is the participant's zone, else the actor's. `study check` prints a
+  `time zones` row, and each participant's stream in `run.json` records `timeZone`;
 - `execution.concurrency` (computer-use E2B routes, including shared-world): a
   cap on participants in flight at once. When omitted, every participant runs
   simultaneously: both routes resolve it when they plan, from the final participant count
@@ -293,7 +336,8 @@ The rest of this section names keys by their v3 spelling:
   desktop template (image) name or ID the run launches on, for a subject that
   needs runtimes the stock `desktop` image lacks (e.g. node/bun/a local Postgres
   baked into an adopter-maintained image). Any non-empty string is a valid
-  name/id (no allowlist); a blank/whitespace value is rejected. Threaded to the
+  name/id (no allowlist); a blank/whitespace value is rejected, and so is one that
+  verify would flag as a secret or local path, as written or encoded. Threaded to the
   SDK's `Sandbox.create(template, opts)` on every desktop-creating route (the
   single-participant and fan-out cua participants, and the shared-world subject and every actor
   sandbox); when absent the call
@@ -471,7 +515,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.v2` in every case.
+`humanish.run-result.v1`. The evidence record stays `humanish.run-bundle.v3` 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`
@@ -616,7 +660,7 @@ Adapter-owned fields:
 Abbreviated synthetic fixture (omits `cwd`, `simulations`, `streams` and `events`):
 
 ```yaml
-schema: humanish.run-bundle.v2
+schema: humanish.run-bundle.v3
 runId: synthetic-run-bundle-2026-06-02t10-00-00-000z-proof
 mode: dry-run
 simCount: 1
@@ -967,7 +1011,7 @@ 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`,
+Where the trace is stored depends on the run bundle version. From `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.
@@ -1010,6 +1054,32 @@ Core-owned fields:
   click-like `ui_action` items, structured `coord` (`x`/`y`). Both are additive:
   absent on older bundles and non-stamping producers, and absence means
   "timing/position unrecorded", never zero
+- optional `items[].page` and `finalPage` (`{ origin, path }`, `TracePage` in
+  `src/actors/contract.ts`): where a computer-use participant's browser was. The loop puts `page`
+  on the `screenshot` item of each observation that read a URL: `turn-00-start` is the page before
+  any action, `turn-01` the page after turn 1's actions, and dwell frames have their own.
+  `finalPage` is the page of the session's last observation, which is a closing observation with
+  no item when tasks are declared; it is absent when that observation read no URL. The screenshot
+  items with a `page`, in item order, then `finalPage`, list the participant's path through the
+  app. `origin` is the URL's scheme, host and port; `path` is its percent-encoded path. A query
+  string, fragment and user info are never kept, and a non-web URL keeps its scheme only
+  (`{ origin: "about:", path: "" }`). Redaction (`tracePage` in `src/evidence/trace-page.ts`):
+  a path segment becomes `[REDACTED_URL_PART]` when it percent-encodes a letter, digit, `-`, `.`,
+  `_`, `~` or `%`, or when any decoded reading of it is email-shaped, holds a run of 16 or more letters,
+  digits, `-` and `_` with a piece of 8 or more characters mixing letters and digits, or changes
+  under the trace text redaction (the study's secrets, then `redactText`). The whole path then
+  goes through that redaction, is cut to 1024 characters ending `[TRUNCATED]`, and is withheld
+  whole when verify's trace scan would still read it as sensitive or opaque. A host label
+  shaped like that token run becomes `[REDACTED_URL_PART]`, then the origin goes through the same
+  redaction (an E2B sandbox host becomes `[REDACTED_SECRET]`). When origin and path together
+  still change under that redaction (a study secret that is a whole link), both become
+  `[REDACTED_URL_PART]`. A token shorter than 16 characters, an
+  all-digit id and personal data in readable words stay, so the sharing rules for synthetic data
+  still apply. Pages come from the browser-state probe, which hosted runs have on Chrome and
+  Chromium only; a Firefox participant, or one whose probe is unavailable, has screenshots without
+  pages. The local browser route and the shared-world route record none. verify reports a page
+  whose path holds `?` or `#`, or whose origin is neither a redaction marker nor a scheme with an
+  optional host and port, as a public-safety finding. Both fields are additive; absence means "page not recorded"
 - optional `modelSettings` (`humanish.model-settings.v1`): how the model was
   asked to run, alongside `ids.model` which says which model it was.
   `reasoningEffort` records the value the request actually carried,
@@ -1829,7 +1899,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 the run bundle (`humanish.run-bundle.v2`), normalizing UI, browser, terminal, TUI,
+inside the run bundle (`humanish.run-bundle.v3`), 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