humanish 0.125.0 → 0.126.0

package/dist/routes/computer-use/types.d.ts

@@ -13,7 +13,7 @@ import { type CuaDiagnostics } from "./diagnostics.js";
 import type { ActorCompletionReason, ActorStatus, ActorStopCause, ActorTokenUsage, ActorTraceItem } from "../../actors/contract.js";
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { StudyDeps } from "../../study/study-deps.js";
-import type { ArrivalPlan, ParticipantArrival } from "../../study/arrivals.js";
+import type { ArrivalPlan, ParticipantArrival, ParticipantEnd } from "../../study/arrivals.js";
 import type { StudyEvent, ParticipantRef } from "../../study/run-study-events.js";
 import type { InProcessDriver, ProviderFactory, RunStudyHomes } from "../../study/run-study-homes.js";
 import { type BrowserScorer } from "../../study/adapter-extension.js";
@@ -23,9 +23,10 @@ import { type DesktopResourceObservation } from "../../substrates/e2b/desktop-re
 import { type DetachedTimers } from "../../substrates/detached.js";
 import type { Brain, ComputerUsePlan, ComputerUseRunner, ResidualConfig } from "../../study/plan-types.js";
 import { type StudyCommsEmail } from "../../study/types.js";
+import type { DesktopFile } from "../../study/desktop-files.js";
 import { type ObserverResult } from "../../observer/render.js";
 import { type BundleRun, type RunBundle, type RunRerunLineage, type RunScorerProvenance, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "../../run/bundle.js";
-import { type RunDesktopGeometry } from "../../run/streams.js";
+import { type RunDesktopFile, type RunDesktopGeometry } from "../../run/streams.js";
 import { type PreparedOutputRoot } from "../../run/contained-output.js";
 import type { ComputerUseParticipant, SharedWorldParticipant } from "../../study/plan-participants.js";
 import type { ResolvedParticipant } from "../../run/participant.js";
@@ -114,6 +115,8 @@ export interface CuaParticipantPlanEntry {
     startAfterMs?: number;
     /** The participant's declared end, on the same clock. */
     endAfterMs?: number;
+    /** The participant's session cap, from the start of its session. */
+    maxSessionMs?: number;
 }
 /** The pre-flight spend and participant plan (pure; printed to stderr + recorded as a bundle event before
  *  any sandbox or provider call; identical in dry-run, marked $0). */
@@ -195,7 +198,7 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED" | "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_SUBJECT_BUILD_FAILED" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED" | "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY" | "HUMANISH_COMPUTER_USE_DESKTOP_FILES_INVALID" | "HUMANISH_COMPUTER_USE_TIME_ZONE_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_SUBJECT_BUILD_FAILED" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
 export interface CuaActorStudyResult extends AutomaticAnalysisResult, StudyResultIdentity<"computer-use"> {
     /** True when the Observer verified the bundle, all live participants passed credibility checks
      * (or this is a dry-run), and no declared adapter/scorer verdict failed. */
@@ -316,6 +319,9 @@ export interface E2BDesktopDeps {
     /** Local-tree route only: the once-per-run packed archive bytes, shared byte-identically
      *  across every fan-out participant's upload step. Absent on dry-run and every other route. */
     localTreeArchiveBuffer?: ArrayBuffer;
+    /** Computer use on a hosted desktop: each participant's files (participants[].files) by id,
+     *  read on this machine before any sandbox. A participant without an entry receives none. */
+    desktopFiles?: ReadonlyMap<string, readonly DesktopFile[]>;
     env: Record<string, string | undefined>;
     e2bApiKey: string;
     requestTimeoutMs: number;
@@ -367,14 +373,12 @@ export interface ParticipantModelDeps {
     openaiApiKey: string;
     timeoutMs: number;
     /**
-     * The participant's scheduled end on `now`'s clock, when it declares participants[].endAfterMs
-     * (scheduledParticipantDeps). Its session ends there with stop cause `scheduled_end`.
+     * How the participant's session ends, when it declares participants[].endAfterMs or maxSessionMs
+     * (scheduledParticipantDeps): at its scheduled end on `now`'s clock, with stop cause
+     * `scheduled_end`, or at its cap after the session starts, with stop cause `session_cap`.
      */
-    scheduledEnd?: {
-        readonly atMs: number;
-        readonly windDownMs: number;
-    };
-    /** The run's clock. A participant with a scheduled end runs its session on it. */
+    end?: ParticipantEnd;
+    /** The run's clock. A participant with an end or a cap runs its session on it. */
     now: () => number;
     participantCount: number;
     artifactRoot: PreparedOutputRoot;
@@ -449,6 +453,8 @@ export interface ParticipantRunOutcome {
     /** Requested + measured desktop/browser geometry. Viewport is absent when measurement failed. */
     desktopGeometry?: RunDesktopGeometry;
     recording?: RunDesktopRecording;
+    /** participants[].files confirmed on the participant's desktop. */
+    desktopFiles?: RunDesktopFile[];
     stateStepRecords: RunSubjectStateStepRecord[];
     /** Completed subject-phase records (clone/upload/extract/install/build/ready/state groups),
      *  folded into bundle.events at build time. Empty on the in-process route (no provisioning). */

package/dist/routes/shared-world/bundle-records.js

@@ -122,6 +122,9 @@ function sharedWorldStream(ctx, spec, index, view) {
                 },
             }),
         desktopGeometry,
+        ...(spec.planned.limits.timeZone === undefined
+            ? {}
+            : { timeZone: spec.planned.limits.timeZone }),
         ui: {
             route: view.route,
             intent: `Watch ${name} use the shared app at the same time as the others.`,

package/dist/routes/shared-world/participant-specs.js

@@ -140,10 +140,11 @@ export function participantRunDeps(ctx, live, scrubKnownValues) {
         studyCwd: ctx.cwd,
         redactScreenshots: ctx.redactScreenshots,
         scrubKnownValues,
-        // A session that throws returns no trace; the run still records that it started.
+        // A session that throws returns no trace; the run still records that it started. Observed
+        // URLs land in a shared-world bundle only as digests, so no session records its pages.
         runSession: (options) => {
             ctx.run.participantStarted();
-            return ctx.runSession(options);
+            return ctx.runSession({ ...options, recordPages: false });
         },
         liveFlush: () => live.flush?.flush,
         onStream: participantStreams(ctx.input.onStream, live),

package/dist/routes/shared-world/plan.js

@@ -8,6 +8,8 @@ import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { brainOf, planCaps, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
 import { sharedWorldParticipants } from "../../study/plan-participants.js";
+import { DESKTOP_FILES_ROUTE_REASON } from "../../study/desktop-files.js";
+import { participantList } from "../../study/study-fields.js";
 import { PUBLIC_TARGET_OWNER_PATTERN } from "../../study/parse/subject.js";
 import { REPO_SLUG_PATTERN } from "../../study/parse/values.js";
 import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } from "../../study/validation.js";
@@ -41,6 +43,9 @@ export function planSharedWorldStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
+    // The parser refuses these; a library caller's config skips it.
+    if (participantList(config)?.some((entry) => entry.files !== undefined))
+        return refuse(invalid, `participants[].files: ${DESKTOP_FILES_ROUTE_REASON}. Remove them.`);
     const actorType = config.actor?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))

package/dist/run/contained-output.d.ts

@@ -117,10 +117,14 @@ export declare function readOpenedAtMost(handle: FileHandle, maxBytes: number):
 /**
  * The first `length` bytes of one regular file, under the checks readContainedRegularFile makes,
  * or all of a file that holds fewer. Bytes past `length`, such as a later append, are not read.
+ * With `start`, the bytes from `start` to `length`.
  */
-export declare function readContainedPrefix(rootInput: PreparedOutputRoot, relativePath: string, length: number): Promise<ContainedRead>;
-/** The first `length` bytes of an opened file, read by position, or all of a shorter one. */
-export declare function readOpenedPrefix(handle: FileHandle, length: number): Promise<Buffer>;
+export declare function readContainedPrefix(rootInput: PreparedOutputRoot, relativePath: string, length: number, start?: number): Promise<ContainedRead>;
+/**
+ * The first `length` bytes of an opened file, read by position, or all of a shorter one. With
+ * `start`, the bytes from `start` to `length`.
+ */
+export declare function readOpenedPrefix(handle: FileHandle, length: number, start?: number): Promise<Buffer>;
 /** The caller owns this checked descriptor and must close it after reading/streaming. */
 export declare function openContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<FileHandle | null>;
 export declare function assertSafeOutputPathSegment(value: string, label?: string): void;

package/dist/run/contained-output.js

@@ -307,15 +307,16 @@ export async function readOpenedAtMost(handle, maxBytes) {
 /**
  * The first `length` bytes of one regular file, under the checks readContainedRegularFile makes,
  * or all of a file that holds fewer. Bytes past `length`, such as a later append, are not read.
+ * With `start`, the bytes from `start` to `length`.
  */
-export async function readContainedPrefix(rootInput, relativePath, length) {
+export async function readContainedPrefix(rootInput, relativePath, length, start = 0) {
     const opened = await openContained(rootInput, relativePath);
     if (opened.status === "missing")
         return opened;
     if (opened.status === "refused")
         return { status: "refused", reason: opened.reason, limit: length };
     try {
-        return { status: "read", bytes: await readOpenedPrefix(opened.handle, length) };
+        return { status: "read", bytes: await readOpenedPrefix(opened.handle, length, start) };
     }
     catch {
         return { status: "refused", reason: "unreadable", limit: length };
@@ -324,12 +325,15 @@ export async function readContainedPrefix(rootInput, relativePath, length) {
         await opened.handle.close().catch(() => { });
     }
 }
-/** The first `length` bytes of an opened file, read by position, or all of a shorter one. */
-export async function readOpenedPrefix(handle, length) {
-    const bytes = Buffer.allocUnsafe(length);
+/**
+ * The first `length` bytes of an opened file, read by position, or all of a shorter one. With
+ * `start`, the bytes from `start` to `length`.
+ */
+export async function readOpenedPrefix(handle, length, start = 0) {
+    const bytes = Buffer.allocUnsafe(Math.max(0, length - start));
     let total = 0;
-    while (total < length) {
-        const { bytesRead } = await handle.read(bytes, total, length - total, total);
+    while (total < bytes.length) {
+        const { bytesRead } = await handle.read(bytes, total, bytes.length - total, start + total);
         if (bytesRead === 0)
             break;
         total += bytesRead;

package/dist/run/judge.d.ts

@@ -6,7 +6,7 @@ export interface BlockerFacts {
     completionReason: ActorCompletionReason;
     /** A harness-owned stop condition ended the session: a matched stopWhen or a completed dwell window. */
     stopConditionMatched: boolean;
-    /** What the participant declared in a field, when its provider has one. */
+    /** What the participant declared, when it declared an outcome (ActorTrace.declaredOutcome). */
     declaredOutcome?: ParticipantDeclaredOutcome;
     /** The route's reading of the closing report: it describes a blocker or asks for instructions. */
     closingReportReadsBlocked: boolean;
@@ -22,9 +22,12 @@ export interface SessionEnding extends BlockerFacts {
  */
 export declare function hollowCompletion(ending: SessionEnding): boolean;
 /**
- * The participant said it reached the goal but reported a blocker. A declared outcome is its own
- * word and wins. Without one, the closing report is read, unless a stop condition ended the
- * session: a matched stopWhen is structured completion evidence and overrides the text.
+ * The session ended goal_satisfied but the participant reported a blocker. A declared `reached`
+ * or `blocked` is its own word and wins. Otherwise the closing report is read, unless a stop
+ * condition ended the session: a matched stopWhen is structured completion evidence and overrides
+ * the text. A declared `not_reached` is read the same way: it ends the session as gave_up when
+ * the participant ends it, so here it comes from a closing report at a scheduled end or a session
+ * cap, and it does not say whether something stopped the participant.
  */
 export declare function selfReportedBlocker(ending: BlockerFacts): boolean;
 /** What a participant's pass reads: its session's end, or why it has none, and the two judgments above. */

package/dist/run/judge.js

@@ -25,16 +25,21 @@ export function hollowCompletion(ending) {
         !ending.stopConditionMatched);
 }
 /**
- * The participant said it reached the goal but reported a blocker. A declared outcome is its own
- * word and wins. Without one, the closing report is read, unless a stop condition ended the
- * session: a matched stopWhen is structured completion evidence and overrides the text.
+ * The session ended goal_satisfied but the participant reported a blocker. A declared `reached`
+ * or `blocked` is its own word and wins. Otherwise the closing report is read, unless a stop
+ * condition ended the session: a matched stopWhen is structured completion evidence and overrides
+ * the text. A declared `not_reached` is read the same way: it ends the session as gave_up when
+ * the participant ends it, so here it comes from a closing report at a scheduled end or a session
+ * cap, and it does not say whether something stopped the participant.
  */
 export function selfReportedBlocker(ending) {
-    if (ending.declaredOutcome !== undefined)
-        return ending.declaredOutcome === "blocked" && ending.completionReason === "goal_satisfied";
-    return (ending.completionReason === "goal_satisfied" &&
-        ending.closingReportReadsBlocked &&
-        !ending.stopConditionMatched);
+    if (ending.completionReason !== "goal_satisfied")
+        return false;
+    if (ending.declaredOutcome === "blocked")
+        return true;
+    if (ending.declaredOutcome === "reached")
+        return false;
+    return ending.closingReportReadsBlocked && !ending.stopConditionMatched;
 }
 /** Judge participant evidence for the bundle and the result in the same order. */
 export function judgeParticipantRecords(participants, wording = {}) {

package/dist/run/live-items.d.ts

@@ -8,6 +8,11 @@ export declare const LIVE_ACTOR_SCHEMA = "humanish.live-actor.v2";
 export declare const LIVE_ACTOR_V1_SCHEMA = "humanish.live-actor.v1";
 /** Whether `value` is a live items index naming a live file name and its own generation. */
 export declare function isLiveItemsIndex(value: unknown): value is LiveItemsIndex;
+/** Where a reader's copy of a live file ends: its first `items` lines, `bytes` bytes. */
+export interface LiveItemsCursor {
+    items: number;
+    bytes: number;
+}
 /**
  * The items the indexed prefix of a live file holds, or why the bytes do not match the index:
  * `bytes` must be exactly the indexed byte count, hash to the indexed sha256, and hold the indexed
@@ -18,6 +23,20 @@ export declare function liveItemsFromBytes(bytes: Buffer, index: LiveItemsIndex)
 } | {
     refused: string;
 };
+/**
+ * The items past `after` in the indexed prefix of a live file, from the file's bytes between
+ * `after.bytes - 1` and the indexed end, or why they do not fit: the first byte must end the line
+ * before the cursor, and the rest must hold exactly the lines between the cursor's count and the
+ * indexed count, each a JSON object. A line end at `after.bytes - 1` fixes how many lines precede
+ * it, so a cursor whose `items` is not that count fails on the line count. The sha256 run.json
+ * records covers the whole prefix and is not checked here: what precedes the cursor is the
+ * reader's, and a generation's bytes never change once written.
+ */
+export declare function liveItemsAfter(bytes: Buffer, index: LiveItemsIndex, after: LiveItemsCursor): {
+    items: ActorTraceItem[];
+} | {
+    refused: string;
+};
 /** One run's live files: what each stream position's current generation holds. */
 export interface LiveItemsWriter {
     /**

package/dist/run/live-items.js

@@ -41,20 +41,40 @@ export function liveItemsFromBytes(bytes, index) {
         };
     if (createHash("sha256").update(bytes).digest("hex") !== index.sha256)
         return { refused: `${index.path} does not match the sha256 run.json records for it` };
+    return itemLinesOf(bytes, index.items, index.path);
+}
+/**
+ * The items past `after` in the indexed prefix of a live file, from the file's bytes between
+ * `after.bytes - 1` and the indexed end, or why they do not fit: the first byte must end the line
+ * before the cursor, and the rest must hold exactly the lines between the cursor's count and the
+ * indexed count, each a JSON object. A line end at `after.bytes - 1` fixes how many lines precede
+ * it, so a cursor whose `items` is not that count fails on the line count. The sha256 run.json
+ * records covers the whole prefix and is not checked here: what precedes the cursor is the
+ * reader's, and a generation's bytes never change once written.
+ */
+export function liveItemsAfter(bytes, index, after) {
+    if (bytes.length !== index.bytes - after.bytes + 1)
+        return {
+            refused: `${index.path} holds ${bytes.length - 1} bytes past byte ${after.bytes} and run.json records ${index.bytes - after.bytes}`,
+        };
+    if (bytes[0] !== 0x0a)
+        return { refused: `${index.path} has no line end before byte ${after.bytes}` };
+    return itemLinesOf(bytes.subarray(1), index.items - after.items, index.path);
+}
+/** The JSON object on each of `count` lines in `bytes`, which must be UTF-8 and end a line. */
+function itemLinesOf(bytes, count, file) {
     let text;
     try {
         text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
     }
     catch {
-        return { refused: `${index.path} is not UTF-8 text` };
+        return { refused: `${file} is not UTF-8 text` };
     }
     const lines = text === "" ? [] : text.split("\n");
     if (lines.length > 0 && lines.pop() !== "")
-        return { refused: `${index.path} does not end its indexed bytes at a line end` };
-    if (lines.length !== index.items)
-        return {
-            refused: `${index.path} holds ${lines.length} items and run.json records ${index.items}`,
-        };
+        return { refused: `${file} does not end its indexed bytes at a line end` };
+    if (lines.length !== count)
+        return { refused: `${file} holds ${lines.length} items and run.json records ${count}` };
     const items = [];
     for (const line of lines) {
         let item;
@@ -62,10 +82,10 @@ export function liveItemsFromBytes(bytes, index) {
             item = JSON.parse(line);
         }
         catch {
-            return { refused: `${index.path} holds a line that is not JSON` };
+            return { refused: `${file} holds a line that is not JSON` };
         }
         if (!isRecord(item))
-            return { refused: `${index.path} holds a line that is not an item` };
+            return { refused: `${file} holds a line that is not an item` };
         items.push(item);
     }
     return { items };

package/dist/run/stream-trace.d.ts

@@ -1,6 +1,7 @@
 import { type RunBundle } from "./bundle.js";
 import { type PreparedOutputRoot } from "./contained-output.js";
-import type { RunStream } from "./streams.js";
+import { type LiveItemsCursor } from "./live-items.js";
+import type { LiveItemsIndex, RunStream } from "./streams.js";
 /** A trace that does not match its index, or cannot be read. The message names the stream. */
 export declare class StreamTraceRefusedError extends Error {
     readonly streamId: string;
@@ -23,15 +24,27 @@ export declare function splitStreamTraces(bundle: RunBundle): {
 /**
  * Where a loader reads trace files from: the bytes at a run-relative path, at most `maxBytes`, or
  * why it could not. With `length`, the first `length` bytes, or all of a shorter file: a live file
- * grows past what run.json indexes, and the loader reads only the indexed prefix. Prepared run
- * paths read through the contained reader; the Observer server passes a reader over its pinned run
+ * grows past what run.json indexes, and the loader reads only the indexed prefix. With `start` as
+ * well, the bytes from `start` to `length`: the items past a reader's cursor. Prepared run paths
+ * read through the contained reader; the Observer server passes a reader over its pinned run
  * folder.
  */
-export type TraceFileReader = (relativePath: string, maxBytes: number, length?: number) => Promise<{
+export type TraceFileReader = (relativePath: string, maxBytes: number, length?: number, start?: number) => Promise<{
     bytes: Buffer;
 } | {
     refused: string;
 }>;
+/**
+ * A live file the loader joined into stream `streamId`: the index it read the items by, and the
+ * cursor it read past when the stream holds only the items after one.
+ */
+export interface LiveItemsRead {
+    streamId: string;
+    index: LiveItemsIndex;
+    after?: LiveItemsCursor;
+}
+/** For a live file's index, the prefix of that file the caller holds already, if any. */
+type LiveAfter = (index: LiveItemsIndex) => LiveItemsCursor | undefined;
 /**
  * The stream as a v1 run.json held it: its actor with every item and every artifact entry. A
  * stream without an index is returned as it is (a v1 stream, or one with no actor). An indexed
@@ -44,6 +57,8 @@ export declare function loadStreamTrace(runPaths: PreparedOutputRoot, stream: Ru
 interface LoadedTraces {
     bundle: RunBundle;
     refused: StreamTraceRefusedError[];
+    /** Each live file joined into a stream that loaded, in stream order. */
+    live: LiveItemsRead[];
 }
 /**
  * Every stream of the bundle loaded through loadStreamTrace, one file at a time, and the refusal
@@ -53,6 +68,11 @@ interface LoadedTraces {
  * receives each trace and live file's path and the bytes the stream was joined from, after they
  * matched the index, so a caller scans exactly what it reads.
  *
+ * `liveAfter` names, for a live file's index, the prefix the caller holds already (the Observer
+ * feed's cursor). The loader then reads and joins only the items past it, checked by liveItemsAfter
+ * without the indexed sha256, and `live` records the cursor; a cursor past the index or off the
+ * file's lines gets the whole prefix, checked as always.
+ *
  * A live file that cannot be read may have been removed by the writer after `bundle` was read: it
  * removes a superseded generation once run.json names the next one, and every live file once the
  * run finished. The loader then reads run.json again, once, through the same reader, and loads
@@ -61,6 +81,7 @@ interface LoadedTraces {
 export declare function loadStreamTraces(source: PreparedOutputRoot | TraceFileReader, bundle: RunBundle, options?: {
     maxBytes?: number;
     onTrace?: (path: string, bytes: Buffer) => void;
+    liveAfter?: LiveAfter;
 }): Promise<LoadedTraces>;
 /**
  * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's

package/dist/run/stream-trace.js

@@ -8,7 +8,7 @@ import { createHash } from "node:crypto";
 import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V2_SCHEMA, } from "./bundle.js";
 import { isRunBundle } from "./bundle-shape.js";
 import { readContainedPrefix, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
-import { isLiveItemsIndex, LIVE_ACTOR_SCHEMA, LIVE_ACTOR_V1_SCHEMA, liveItemsFromBytes, } from "./live-items.js";
+import { isLiveItemsIndex, LIVE_ACTOR_SCHEMA, LIVE_ACTOR_V1_SCHEMA, liveItemsAfter, liveItemsFromBytes, } from "./live-items.js";
 import { isRunStreamArtifact, isStreamTraceIndex, isStreamTracePath } from "./stream-shape.js";
 import { isRecord } from "./type-guards.js";
 /** A trace that does not match its index, or cannot be read. The message names the stream. */
@@ -87,10 +87,10 @@ export function splitStreamTraces(bundle) {
     return { bundle: { ...bundle, schema: RUN_BUNDLE_SCHEMA, streams }, files };
 }
 function containedReader(runPaths) {
-    return async (relativePath, maxBytes, length) => {
+    return async (relativePath, maxBytes, length, start) => {
         const read = length === undefined
             ? await readContainedRegularFile(runPaths, relativePath, maxBytes)
-            : await readContainedPrefix(runPaths, relativePath, length);
+            : await readContainedPrefix(runPaths, relativePath, length, start);
         if (read.status === "missing")
             return { refused: `${relativePath} is missing` };
         if (read.status === "refused")
@@ -152,7 +152,7 @@ class LiveFileUnreadableError extends StreamTraceRefusedError {
  * file's path and those bytes. A live actor with inline items (humanish.live-actor.v1) is returned
  * as it is; bundleRefusal refuses one in a v3 run.json.
  */
-async function readLiveItems(read, stream, maxBytes) {
+async function readLiveItems(read, stream, maxBytes, liveAfter) {
     const live = stream.liveActor;
     if (live === undefined || isInlineLiveActor(live))
         return { stream };
@@ -168,6 +168,15 @@ async function readLiveItems(read, stream, maxBytes) {
         refuse("run.json holds in-progress items beside their live file");
     if (index.bytes > maxBytes)
         refuse(`${index.path} is indexed at ${index.bytes} bytes, more than the ${maxBytes} read`);
+    const { itemsFile: _index, ...summary } = live;
+    const after = liveAfter?.(index);
+    const tail = after === undefined ? undefined : await readLiveTail(read, stream, index, after);
+    if (tail !== undefined)
+        return {
+            stream: { ...stream, liveActor: { ...summary, items: tail.items } },
+            file: { path: index.path, bytes: tail.bytes },
+            read: { streamId: stream.id, index, after: after },
+        };
     const file = await read(index.path, maxBytes, index.bytes);
     if ("refused" in file)
         throw new LiveFileUnreadableError(stream.id, file.refused);
@@ -175,17 +184,38 @@ async function readLiveItems(read, stream, maxBytes) {
     const joined = liveItemsFromBytes(file.bytes.subarray(0, index.bytes), index);
     if ("refused" in joined)
         return refuse(joined.refused);
-    const { itemsFile: _index, ...summary } = live;
     return {
         stream: { ...stream, liveActor: { ...summary, items: joined.items } },
-        live: { path: index.path, bytes: file.bytes.subarray(0, index.bytes) },
+        file: { path: index.path, bytes: file.bytes.subarray(0, index.bytes) },
+        read: { streamId: stream.id, index },
     };
 }
+/**
+ * The items of the live file `index` describes past `after`, and the bytes they were read from;
+ * undefined when the cursor does not fit the index or the file's lines, so the caller reads the
+ * whole prefix. A cursor at the indexed end reads nothing. A file the reader cannot read throws
+ * LiveFileUnreadableError, as a whole read does.
+ */
+async function readLiveTail(read, stream, index, after) {
+    if (after.bytes === 0 ||
+        after.items > index.items ||
+        after.bytes > index.bytes ||
+        (after.items === index.items) !== (after.bytes === index.bytes))
+        return undefined;
+    if (after.bytes === index.bytes)
+        return { items: [], bytes: Buffer.alloc(0) };
+    const file = await read(index.path, index.bytes - after.bytes + 1, index.bytes, after.bytes - 1);
+    if ("refused" in file)
+        throw new LiveFileUnreadableError(stream.id, file.refused);
+    const tail = file.bytes.subarray(0, index.bytes - after.bytes + 1);
+    const joined = liveItemsAfter(tail, index, after);
+    return "refused" in joined ? undefined : { items: joined.items, bytes: tail.subarray(1) };
+}
 /**
  * The stream with its trace and live items joined, and each file's path and the bytes it was
  * joined from.
  */
-async function readStreamTrace(read, stream, maxBytes) {
+async function readStreamTrace(read, stream, maxBytes, liveAfter) {
     const files = [];
     let joined = stream;
     if (stream.trace !== undefined) {
@@ -196,10 +226,10 @@ async function readStreamTrace(read, stream, maxBytes) {
         joined = joinTrace(stream, file.bytes);
         files.push({ path: stream.trace.path, bytes: file.bytes });
     }
-    const live = await readLiveItems(read, joined, maxBytes);
-    if (live.live !== undefined)
-        files.push(live.live);
-    return { stream: live.stream, files };
+    const live = await readLiveItems(read, joined, maxBytes, liveAfter);
+    if (live.file !== undefined)
+        files.push(live.file);
+    return { stream: live.stream, files, ...(live.read === undefined ? {} : { live: live.read }) };
 }
 /**
  * The stream as a v1 run.json held it: its actor with every item and every artifact entry. A
@@ -249,6 +279,11 @@ function bundleRefusal(bundle, stream, owners) {
  * receives each trace and live file's path and the bytes the stream was joined from, after they
  * matched the index, so a caller scans exactly what it reads.
  *
+ * `liveAfter` names, for a live file's index, the prefix the caller holds already (the Observer
+ * feed's cursor). The loader then reads and joins only the items past it, checked by liveItemsAfter
+ * without the indexed sha256, and `live` records the cursor; a cursor past the index or off the
+ * file's lines gets the whole prefix, checked as always.
+ *
  * A live file that cannot be read may have been removed by the writer after `bundle` was read: it
  * removes a superseded generation once run.json names the next one, and every live file once the
  * run finished. The loader then reads run.json again, once, through the same reader, and loads
@@ -257,15 +292,15 @@ function bundleRefusal(bundle, stream, owners) {
 export async function loadStreamTraces(source, bundle, options = {}) {
     const read = typeof source === "function" ? source : containedReader(source);
     const maxBytes = options.maxBytes ?? RUN_ARTIFACT_MAX_BYTES;
-    let loaded = await loadEveryStream(read, bundle, maxBytes);
+    let loaded = await loadEveryStream(read, bundle, maxBytes, options.liveAfter);
     if (loaded.refused.some((error) => error instanceof LiveFileUnreadableError)) {
         const current = await rereadBundle(read, bundle.runId);
         if (current !== undefined)
-            loaded = await loadEveryStream(read, current, maxBytes);
+            loaded = await loadEveryStream(read, current, maxBytes, options.liveAfter);
     }
     for (const file of loaded.files)
         options.onTrace?.(file.path, file.bytes);
-    return { bundle: loaded.bundle, refused: loaded.refused };
+    return { bundle: loaded.bundle, refused: loaded.refused, live: loaded.live };
 }
 /** run.json as it is now, when it is a run bundle of run `runId`. */
 async function rereadBundle(read, runId) {
@@ -280,7 +315,7 @@ async function rereadBundle(read, runId) {
         return undefined;
     }
 }
-async function loadEveryStream(read, bundle, maxBytes) {
+async function loadEveryStream(read, bundle, maxBytes, liveAfter) {
     const owners = new Map();
     for (const stream of bundle.streams)
         if (isRecord(stream.trace)) {
@@ -290,13 +325,16 @@ async function loadEveryStream(read, bundle, maxBytes) {
     const streams = [];
     const refused = [];
     const files = [];
+    const live = [];
     for (const stream of bundle.streams) {
         try {
             const reason = bundleRefusal(bundle, stream, owners);
             if (reason !== undefined)
                 throw new StreamTraceRefusedError(stream.id, reason);
-            const loaded = await readStreamTrace(read, stream, maxBytes);
+            const loaded = await readStreamTrace(read, stream, maxBytes, liveAfter);
             files.push(...loaded.files);
+            if (loaded.live !== undefined)
+                live.push(loaded.live);
             streams.push(loaded.stream);
         }
         catch (error) {
@@ -306,7 +344,7 @@ async function loadEveryStream(read, bundle, maxBytes) {
             streams.push(stream);
         }
     }
-    return { bundle: { ...bundle, streams }, refused, files };
+    return { bundle: { ...bundle, streams }, refused, files, live };
 }
 /**
  * A loaded bundle as a reader that shows a run presents it. A refused stream keeps run.json's

package/dist/run/streams.d.ts

@@ -175,6 +175,15 @@ export interface RunParticipantAssignment {
         goal: string;
     }>;
 }
+/** One file humanish copied onto a participant's desktop before it started (participants[].files). */
+export interface RunDesktopFile {
+    /** Where it landed, relative to the desktop user's home folder. */
+    as: string;
+    /** Its size in bytes, confirmed on the desktop. */
+    size: number;
+    /** The sha256 of the bytes humanish copied, 64 hex characters. */
+    sha256: string;
+}
 export interface RunStream {
     id: string;
     simId: string;
@@ -232,6 +241,13 @@ export interface RunStream {
     };
     /** Truthful screen/window/viewport evidence for hosted desktop browser participants. */
     desktopGeometry?: RunDesktopGeometry;
+    /** The files copied onto this participant's desktop before it started. Never their contents. */
+    desktopFiles?: RunDesktopFile[];
+    /**
+     * The participant's time zone (participants[].clock, else actor.clock): its turns gave the time
+     * in it, and its hosted browser ran in it. Absent when it had none.
+     */
+    timeZone?: string;
     terminal?: {
         title: string;
         format: "ansi" | "plain";