humanish 0.124.0 → 0.126.0

package/dist/study/plan.js

@@ -86,12 +86,11 @@ export function planStudy(config, options, deps = {}) {
     const bundle = plannedBundle(result.plan);
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
     // plan.study for the run's status record and bundle, and plan.warnings for its bundle events.
-    const closing = closingReportWarning(result.plan);
     const warnings = [
         ...recordedStudyWarnings(study),
         ...(result.plan.warnings ?? []),
         ...(bundle.warning === undefined ? [] : [bundle.warning]),
-        ...(closing === undefined ? [] : [closing]),
+        ...closingReportWarnings(result.plan),
     ];
     const plan = {
         ...result.plan,
@@ -115,21 +114,33 @@ function plannedBundle(plan) {
     return warning === undefined ? { estimate } : { estimate, warning };
 }
 /**
- * The warning for participants with a scheduled end on Claude as a local-agent participant model.
- * Its session has no read-only closing request, so each such participant ends with the scheduled
- * end as its reason and no account of its session.
+ * The warnings for participants with a scheduled end or a session cap on Claude as a local-agent
+ * participant model. Its session has no read-only closing request, so each such participant ends
+ * at its end or cap with that as its reason and no account of its session.
  */
-function closingReportWarning(plan) {
+function closingReportWarnings(plan) {
     if (plan.route !== "computer-use")
-        return undefined;
+        return [];
     const { brain } = plan.runner;
     if (brain.kind !== "local-agent" || brain.agent !== "claude")
-        return undefined;
-    const scheduled = plan.runner.participants.filter((participant) => participant.endAfterMs !== undefined).length;
-    if (scheduled === 0)
-        return undefined;
-    const subject = scheduled === 1 ? "it ends" : "each ends";
-    return `${plural(scheduled, "participant")} ${scheduled === 1 ? "has" : "have"} a scheduled end (participants[].endAfterMs), and Claude as a local-agent participant model cannot be asked for a closing report, so ${subject} with the scheduled end as its reason and no closing account. A computer-use model (actor.type: openai-computer-use) or Codex (actor.localAgent: codex) writes one.`;
+        return [];
+    const { participants } = plan.runner;
+    const scheduled = participants.filter((participant) => participant.endAfterMs !== undefined);
+    const capped = participants.filter((participant) => participant.maxSessionMs !== undefined);
+    const claude = "Claude as a local-agent participant model cannot be asked for a closing report";
+    const writers = "A computer-use model (actor.type: openai-computer-use) or Codex (actor.localAgent: codex) writes one.";
+    return [
+        ...(scheduled.length === 0
+            ? []
+            : [
+                `${plural(scheduled.length, "participant")} ${scheduled.length === 1 ? "has" : "have"} a scheduled end (participants[].endAfterMs), and ${claude}, so ${scheduled.length === 1 ? "it ends" : "each ends"} with the scheduled end as its reason and no closing account. ${writers}`,
+            ]),
+        ...(capped.length === 0
+            ? []
+            : [
+                `${plural(capped.length, "participant")} ${capped.length === 1 ? "has" : "have"} a session cap (participants[].maxSessionMs), and ${claude}, so ${capped.length === 1 ? "if it reaches its cap it ends" : "each that reaches its cap ends"} with the cap as its reason and no closing account. ${writers}`,
+            ]),
+    ];
 }
 function planRoute(route, study, options, input, deps, e2b) {
     const { sandboxCeiling } = e2b;

package/dist/study/preflight.js

@@ -8,6 +8,7 @@ import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.j
 import { planStudy, routeOf } from "./plan.js";
 import { describeArrivals, describeWindows } from "./arrivals.js";
 import { describeBundle } from "./bundle-estimate.js";
+import { describeTimeZones } from "./plan-participants.js";
 import { resolveStudyManifest } from "./discover.js";
 import { participantList } from "./study-fields.js";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
@@ -82,6 +83,9 @@ export async function runStudyPreflight(options) {
     const windows = windowsCheck(planned.planned.plan);
     if (windows !== undefined)
         ctx.checks.push(windows);
+    const timeZones = describeTimeZones(participants);
+    if (timeZones !== undefined)
+        ctx.checks.push({ name: "time zones", ok: true, message: timeZones });
     const bundle = planned.planned.bundle;
     if (bundle !== undefined)
         ctx.checks.push({ name: "bundle size", ok: true, message: describeBundle(bundle) });

package/dist/study/types.d.ts

@@ -257,6 +257,13 @@ export interface StudySubject {
      */
     localTree?: StudySubjectLocalTree;
 }
+/** One file a participant's desktop receives (`participants[].files`). */
+export interface StudyParticipantFile {
+    /** Path of the file, relative to the folder that holds the study file. */
+    from: string;
+    /** Where it lands, relative to the desktop user's home folder. */
+    as: string;
+}
 /**
  * One participant in a differentiated fan-out on the computer-use E2B route (`per-lane-worlds`).
  * Each entry becomes an independent E2B desktop sandbox with its own persona/device/starting-steer. All
@@ -304,6 +311,11 @@ export interface StudyParticipantEntry {
      * shared-world, scripted-browser, and terminal routes.
      */
     target?: string;
+    /**
+     * Hosted computer use only: files copied onto this participant's desktop before it starts, so a
+     * browser upload dialog can find them. src/study/desktop-files.ts holds the rules.
+     */
+    files?: StudyParticipantFile[];
     /**
      * Shared-world only: this participant's loopback entry route, resolved against
      * `subject.serve.url`. It must be same-origin (loopback) with it, and the participant opens
@@ -334,8 +346,16 @@ export interface StudyParticipantEntry {
      */
     endAfterMs?: number;
     /**
-     * With endAfterMs: how long before the end each turn tells the participant the end time and the
-     * minutes left. Default 600000 (10 minutes).
+     * Computer use: the longest this participant's session lasts, in milliseconds from the start of
+     * its session (1 to 86,400,000). It may end its session before then and counts as passed when it
+     * does so normally; at the cap it is asked for its closing report and the session ends as passed,
+     * with stop cause `session_cap`. Its session lasts the cap plus 5 minutes in place of
+     * execution.timeoutMs, and its sandbox is sized from that. Not with endAfterMs.
+     */
+    maxSessionMs?: number;
+    /**
+     * With endAfterMs or maxSessionMs: how long before the end each turn tells the participant the
+     * end time and the minutes left. Default 600000 (10 minutes).
      */
     windDownMs?: number;
     /**
@@ -343,6 +363,14 @@ export interface StudyParticipantEntry {
      * no duration lasts while it only waits. Same range, and no longer than actor.maxWaitMs.
      */
     idleWaitMs?: number;
+    /**
+     * Computer use and shared world: this participant's clock, in place of actor.clock. Its
+     * `timeZone` is the zone each turn gives the time in and, on a hosted desktop, the zone its
+     * browser runs in.
+     */
+    clock?: {
+        timeZone: string;
+    };
 }
 export interface StudyActor {
     /**
@@ -388,9 +416,10 @@ export interface StudyActor {
      */
     idleWaitMs?: number;
     /**
-     * Computer use: the participant's clock. `timeZone`, a time zone name such as "Europe/London", adds
-     * the local time to each turn, for missions that refer to appointment times, and gives a
-     * scheduled end (participants[].endAfterMs) in that zone. A hosted desktop shows no clock.
+     * Computer use: the participants' clock, unless a participant declares its own. `timeZone`, a
+     * time zone name such as "Europe/London", adds the local time to each turn, for missions that
+     * refer to clock times, gives a scheduled end or session cap in that zone, and sets the zone
+     * of a hosted desktop's browser and of the clock in its panel, which shows UTC without one.
      */
     clock?: {
         timeZone: string;

package/dist/study/validation.js

@@ -114,6 +114,9 @@ export function sharedWorldValidationReason(config) {
     const ending = participantList(config)?.findIndex((entry) => entry?.endAfterMs !== undefined);
     if (ending !== undefined && ending >= 0)
         return `participants[${ending}].endAfterMs ends a participant at a set time on route: computer-use only. A shared-world participant runs for execution.timeoutMs; remove endAfterMs and windDownMs.`;
+    const capped = participantList(config)?.findIndex((entry) => entry?.maxSessionMs !== undefined);
+    if (capped !== undefined && capped >= 0)
+        return `participants[${capped}].maxSessionMs caps a participant's session on route: computer-use only. A shared-world participant runs for execution.timeoutMs; remove maxSessionMs and windDownMs.`;
     return config.subject.source === "app-url"
         ? externalPublicSharedWorldValidationReason(config)
         : concurrentSharedWorldValidationReason(config);

package/dist/study/warnings.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedPersona } from "./persona.js";
 import type { StudyConfig } from "./types.js";
-import { type Participant } from "./plan-participants.js";
+import { type DesktopParticipant, type Participant } from "./plan-participants.js";
 /**
  * The fields a config sets that its route does not read, each as `field` or `field (reason)`.
  * parseStudy refuses a study for any of them.
@@ -30,4 +30,4 @@ export declare function personaBackgroundWarnings(studyId: string, participants:
  * and `study show`, which run no plan. Only computer-use and shared-world studies have them; a run's
  * `--count` is not applied.
  */
-export declare function plannedParticipants(config: StudyConfig): readonly Participant[];
+export declare function plannedParticipants(config: StudyConfig): readonly DesktopParticipant[];

package/dist/study/warnings.js

@@ -1,5 +1,6 @@
 import { cli } from "../cli/invocation.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { DESKTOP_FILES_ROUTE_REASON } from "./desktop-files.js";
 import { computerUseParticipants, declaredParticipantIds, sharedWorldParticipants, } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
 import { participantList, participantInstruction, declaredParticipantCount, } from "./study-fields.js";
@@ -27,6 +28,12 @@ const ACTOR_ROWS = [
         applies: (config, routes) => Boolean(participantList(config)?.some((entry) => entry.host === true)) &&
             !routes.externalPublic,
     },
+    {
+        field: "participants[].files",
+        reason: DESKTOP_FILES_ROUTE_REASON,
+        applies: (config, routes) => Boolean(participantList(config)?.some((entry) => entry.files !== undefined)) &&
+            !(routes.hostedCuaBrowser && !routes.shared),
+    },
     {
         field: "actor.mission",
         reason: "the scripted-browser actor runs no model",

package/dist/subject/local-tree-archive.d.ts

@@ -71,6 +71,13 @@ export declare function enumerateLocalTree(root: string, options?: {
  * produces zero entries; or total packed bytes exceed maxArchiveBytes.
  */
 export declare function createLocalTreeArchive(root: string, options?: CreateLocalTreeArchiveOptions): LocalTreeArchive;
+/**
+ * Whether a relative path an author wrote names a file the always-on denylist keeps on this
+ * machine: a secret-shaped name, or one under .git, node_modules or .humanish. It compares without
+ * case, since on a case-insensitive filesystem `.ENV` opens `.env`. participants[].files refuses
+ * the same paths.
+ */
+export declare function isLocalTreeDenylisted(relPath: string): boolean;
 /**
  * Normalize an author-supplied exclude entry to the relPath shape enumeration
  * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax

package/dist/subject/local-tree-archive.js

@@ -283,6 +283,18 @@ function matchesBasenamePattern(basename, pattern) {
 function isDenylistedBasename(basename) {
     return LOCAL_TREE_DENYLIST_BASENAME_PATTERNS.some((pattern) => matchesBasenamePattern(basename, pattern));
 }
+/**
+ * Whether a relative path an author wrote names a file the always-on denylist keeps on this
+ * machine: a secret-shaped name, or one under .git, node_modules or .humanish. It compares without
+ * case, since on a case-insensitive filesystem `.ENV` opens `.env`. participants[].files refuses
+ * the same paths.
+ */
+export function isLocalTreeDenylisted(relPath) {
+    const segments = relPath.toLowerCase().split("/");
+    const basename = segments.at(-1) ?? "";
+    return (segments.some((segment) => LOCAL_TREE_DENYLIST_PATH_SEGMENTS.some((denied) => denied.toLowerCase() === segment)) ||
+        LOCAL_TREE_DENYLIST_BASENAME_PATTERNS.some((pattern) => matchesBasenamePattern(basename, pattern.toLowerCase())));
+}
 function isDenylistedSegment(relPath) {
     const segments = relPath.split("/");
     return segments.some((segment) => LOCAL_TREE_DENYLIST_PATH_SEGMENTS.includes(segment));

package/dist/substrates/e2b/desktop-browser.d.ts

@@ -76,6 +76,9 @@ extraChromiumFlags?: readonly string[], environment?: Readonly<Record<string, st
  * `x-terminal-emulator` is tried first so a template that swaps
  * the emulator still works; a desktop with neither is a template problem and fails closed rather
  * than handing a participant an empty screen and calling it a study.
+ *
+ * A `timeZone` is TZ on the terminal, so its shells, the product under test and any browser started
+ * from it run in that zone.
  */
-export declare function openDesktopTerminal(desktop: E2BDesktopSandbox, requestTimeoutMs: number, workdir: string | undefined): Promise<void>;
+export declare function openDesktopTerminal(desktop: E2BDesktopSandbox, requestTimeoutMs: number, workdir: string | undefined, timeZone?: string): Promise<void>;
 export declare function startDesktopStream(desktop: E2BDesktopSandbox, browserWindowId: string | undefined): Promise<void>;

package/dist/substrates/e2b/desktop-browser.js

@@ -367,9 +367,13 @@ function desktopBrowserFamily(value) {
  * `x-terminal-emulator` is tried first so a template that swaps
  * the emulator still works; a desktop with neither is a template problem and fails closed rather
  * than handing a participant an empty screen and calling it a study.
+ *
+ * A `timeZone` is TZ on the terminal, so its shells, the product under test and any browser started
+ * from it run in that zone.
  */
-export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir) {
+export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir, timeZone) {
     const dir = workdir ?? "/home/user";
+    const zone = timeZone === undefined ? "" : `TZ=${shellQuote(timeZone)} `;
     const result = await runDetachedStep(e2bShell(desktop), {
         name: "desktop-cli-terminal",
         command: [
@@ -379,7 +383,7 @@ export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir) {
             // a study that measures our own mojibake against an unconfigured template would be measuring
             // the template. The product-side fix (an ASCII fallback when the locale is not UTF-8) is in
             // src/routes/terminal/encoding.ts, and it is the one that matters for real users.
-            `    (cd ${shellQuote(dir)} 2>/dev/null || cd /home/user; DISPLAY=:0 LANG=C.UTF-8 LC_ALL=C.UTF-8 HUMANISH_STUDY_PARTICIPANT=1 nohup "$candidate" >/dev/null 2>&1 &)`,
+            `    (cd ${shellQuote(dir)} 2>/dev/null || cd /home/user; DISPLAY=:0 LANG=C.UTF-8 LC_ALL=C.UTF-8 ${zone}HUMANISH_STUDY_PARTICIPANT=1 nohup "$candidate" >/dev/null 2>&1 &)`,
             "    sleep 3",
             '    echo "humanish: opened $candidate"',
             "    exit 0",

package/dist/substrates/e2b/desktop-clock.d.ts

@@ -0,0 +1,10 @@
+import type { E2BDesktopSandbox } from "./sdk.js";
+/**
+ * Set every clock in the desktop's XFCE panel to `timeZone`, a tz database name, by writing the
+ * clock plugin's `timezone` property through xfconf-query. The property lives in the session's
+ * settings daemon, reached over the session bus whose address xfce4-session holds, and the panel
+ * redraws its clock when the property changes (live: 02:12 UTC became 11:12 for Asia/Tokyo with no
+ * restart). A desktop without xfconf-query or without a clock plugin is left as it is. Throws with
+ * xfconf-query's error output when a clock is found and cannot be set.
+ */
+export declare function setPanelClockZone(desktop: E2BDesktopSandbox, timeZone: string, requestTimeoutMs: number): Promise<void>;

package/dist/substrates/e2b/desktop-clock.js

@@ -0,0 +1,29 @@
+// The clock in the hosted desktop's panel. The stock template's XFCE panel sits above every window,
+// so a participant sees its clock in each screenshot, and it shows the desktop's zone, UTC, unless
+// its clock plugin names another.
+import { shellQuote } from "../shell.js";
+import { e2bShell } from "./shell.js";
+/**
+ * Set every clock in the desktop's XFCE panel to `timeZone`, a tz database name, by writing the
+ * clock plugin's `timezone` property through xfconf-query. The property lives in the session's
+ * settings daemon, reached over the session bus whose address xfce4-session holds, and the panel
+ * redraws its clock when the property changes (live: 02:12 UTC became 11:12 for Asia/Tokyo with no
+ * restart). A desktop without xfconf-query or without a clock plugin is left as it is. Throws with
+ * xfconf-query's error output when a clock is found and cannot be set.
+ */
+export async function setPanelClockZone(desktop, timeZone, requestTimeoutMs) {
+    const result = await e2bShell(desktop).run([
+        `zone=${shellQuote(timeZone)}`,
+        "command -v xfconf-query >/dev/null 2>&1 || exit 0",
+        'session_pid="$(pgrep -x xfce4-session | head -n 1)"',
+        'if [ -n "$session_pid" ]; then',
+        `  bus="$(tr '\\0' '\\n' < "/proc/$session_pid/environ" | sed -n 's/^DBUS_SESSION_BUS_ADDRESS=//p')"`,
+        '  if [ -n "$bus" ]; then export DBUS_SESSION_BUS_ADDRESS="$bus"; fi',
+        "fi",
+        `for plugin in $(xfconf-query -c xfce4-panel -p /plugins -l -v | awk '$2 == "clock" { print $1 }'); do`,
+        '  xfconf-query -c xfce4-panel -p "$plugin/timezone" -n -t string -s "$zone" || exit 1',
+        "done",
+    ].join("\n"), { requestTimeoutMs, timeoutMs: 15_000 });
+    if (result.exitCode !== 0)
+        throw new Error(result.stderr.trim() || `xfconf-query exited ${result.exitCode}`);
+}

package/dist/substrates/e2b/sdk.d.ts

@@ -154,6 +154,12 @@ export interface E2BDesktopSandbox {
             requestTimeoutMs?: number;
             useOctetStream?: boolean;
         }): Promise<unknown>;
+        /** A file's size as the sandbox sees it. A relative path is under the sandbox user's home. */
+        getInfo?(path: string, options?: {
+            requestTimeoutMs?: number;
+        }): Promise<{
+            size: number;
+        }>;
     };
     launch(application: string, uri?: string): Promise<void>;
     /** Open a file or URL with the desktop's default application (present on @e2b/desktop >= 1.x). */

package/dist/verify/artifacts.js

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

package/dist/verify/pages.d.ts

@@ -0,0 +1,7 @@
+import type { RunBundle } from "../run/bundle.js";
+/**
+ * One finding per recorded page that holds more than an origin and a path, in each finished
+ * trace's items and summary and each running participant's items. A finding names where the page
+ * is, never what it says.
+ */
+export declare function pageFindings(bundle: RunBundle): string[];

package/dist/verify/pages.js

@@ -0,0 +1,50 @@
+import { REDACTION_MARKERS } from "../evidence/redaction.js";
+import { isRecord } from "../run/type-guards.js";
+// A recorded page (`items[].page`, `finalPage`) keeps a URL's origin and path only. The text scan
+// finds secret shapes in it as in any trace text, but a query string, a fragment or user info can
+// carry a short token no pattern matches, so a page holding one is a public-safety finding.
+// The markers that can stand for a whole origin, such as a withheld sandbox host.
+const MARKERS = new Set(Object.values(REDACTION_MARKERS));
+// `scheme:` alone (a non-web URL) or `scheme://host[:port]`, with nothing after the host. The URL
+// parser reads a backslash there as a slash, so a backslash counts as a path too.
+const ORIGIN = /^[a-z][a-z0-9+.-]*:(?:\/\/[^/\\?#@]*)?$/i;
+/** What is wrong with a recorded page, or undefined when it holds an origin and a path only. */
+function pageProblem(page) {
+    if (!isRecord(page) || typeof page.origin !== "string" || typeof page.path !== "string")
+        return "is not an origin and a path";
+    if (/[?#]/.test(page.path))
+        return "has a query string or fragment in its path";
+    if (!MARKERS.has(page.origin) && !ORIGIN.test(page.origin))
+        return "has an origin with user info, a path, a query string or a fragment";
+    return undefined;
+}
+/**
+ * One finding per recorded page that holds more than an origin and a path, in each finished
+ * trace's items and summary and each running participant's items. A finding names where the page
+ * is, never what it says.
+ */
+export function pageFindings(bundle) {
+    const findings = [];
+    const check = (where, page) => {
+        if (page === undefined)
+            return;
+        const problem = pageProblem(page);
+        if (problem !== undefined)
+            findings.push(`${where} ${problem}`);
+    };
+    // The shape guard admits items that are not records, so each is read as unknown.
+    const checkItems = (where, items) => {
+        if (!Array.isArray(items))
+            return;
+        items.forEach((item, index) => {
+            if (isRecord(item))
+                check(`${where}[${index}].page`, item.page);
+        });
+    };
+    for (const stream of bundle.streams) {
+        checkItems(`${stream.id} items`, stream.actor?.items);
+        check(`${stream.id} finalPage`, stream.actor?.finalPage);
+        checkItems(`${stream.id} liveActor.items`, stream.liveActor?.items);
+    }
+    return findings;
+}

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

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

package/dist/verify/screenshot-reads.js

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