humanish 0.124.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/bundle-shape.js

@@ -1,6 +1,6 @@
 import { isCommsReceivingEvidence } from "../comms/receiving-evidence.js";
 import { isCapturedGitState } from "./git-state.js";
-import { PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "./bundle.js";
+import { PUBLIC_TARGET_CWD, REVIEW_SCHEMA, isReadRunBundleSchema, } from "./bundle.js";
 import { CLEANUP_SCHEMA, } from "./results.js";
 import { isRunSimulationStatus, isRunStream, isRunStreamKind } from "./stream-shape.js";
 import { isLocalEvidenceArtifactPath } from "./paths.js";
@@ -10,7 +10,7 @@ import { isSharedWorldEvidence } from "./shared-world-shape.js";
 import { isNonNegativeSafeInteger, isPositiveSafeInteger, isRecord } from "./type-guards.js";
 export function isRunBundle(value) {
     return (isRecord(value) &&
-        (value.schema === RUN_BUNDLE_SCHEMA || value.schema === RUN_BUNDLE_V1_SCHEMA) &&
+        isReadRunBundleSchema(value.schema) &&
         (value.commsReceiving === undefined || isCommsReceivingEvidence(value.commsReceiving)) &&
         (value.publication === undefined ||
             (isRecord(value.publication) &&

package/dist/run/bundle.d.ts

@@ -5,10 +5,17 @@ import type { SharedWorldEvidence } from "./shared-world-evidence.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import type { RunInterruptSignal } from "./status.js";
 import type { RunSimulationStatus, RunStream, RunStreamKind } from "./streams.js";
-/** The run bundle version this release writes: each stream's trace is a file run.json indexes. */
-export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v2";
+/**
+ * The run bundle version this release writes: each stream's trace, and each running participant's
+ * items so far, are files run.json indexes.
+ */
+export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v3";
+/** The version 0.123.0 and 0.124.0 wrote, with a running participant's items inline. It is still read. */
+export declare const RUN_BUNDLE_V2_SCHEMA = "humanish.run-bundle.v2";
 /** The version 0.122.0 and earlier wrote, with every trace inline. It is still read. */
 export declare const RUN_BUNDLE_V1_SCHEMA = "humanish.run-bundle.v1";
+/** Whether `value` names a run bundle version this release reads: v3, v2 or v1. */
+export declare function isReadRunBundleSchema(value: unknown): value is RunBundle["schema"];
 /** The run bundle file, relative to the run directory. */
 export declare const RUN_BUNDLE_FILE = "run.json";
 export declare const REVIEW_SCHEMA = "humanish.review.v1";
@@ -231,7 +238,7 @@ export interface RunBundle {
         restrictions: ["real-communications"];
     };
     commsReceiving?: CommsReceivingEvidence;
-    schema: typeof RUN_BUNDLE_SCHEMA | typeof RUN_BUNDLE_V1_SCHEMA;
+    schema: typeof RUN_BUNDLE_SCHEMA | typeof RUN_BUNDLE_V2_SCHEMA | typeof RUN_BUNDLE_V1_SCHEMA;
     runId: string;
     mode: "dry-run" | "live";
     simCount: number;

package/dist/run/bundle.js

@@ -1,10 +1,19 @@
 import path from "node:path";
 import { captureGitState } from "./git-state.js";
 import { studyFields } from "./study-provenance.js";
-/** The run bundle version this release writes: each stream's trace is a file run.json indexes. */
-export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v2";
+/**
+ * The run bundle version this release writes: each stream's trace, and each running participant's
+ * items so far, are files run.json indexes.
+ */
+export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v3";
+/** The version 0.123.0 and 0.124.0 wrote, with a running participant's items inline. It is still read. */
+export const RUN_BUNDLE_V2_SCHEMA = "humanish.run-bundle.v2";
 /** The version 0.122.0 and earlier wrote, with every trace inline. It is still read. */
 export const RUN_BUNDLE_V1_SCHEMA = "humanish.run-bundle.v1";
+/** Whether `value` names a run bundle version this release reads: v3, v2 or v1. */
+export function isReadRunBundleSchema(value) {
+    return (value === RUN_BUNDLE_SCHEMA || value === RUN_BUNDLE_V2_SCHEMA || value === RUN_BUNDLE_V1_SCHEMA);
+}
 /** The run bundle file, relative to the run directory. */
 export const RUN_BUNDLE_FILE = "run.json";
 export const REVIEW_SCHEMA = "humanish.review.v1";

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

@@ -46,6 +46,21 @@ export declare function writeContainedOutputFile(rootInput: PreparedOutputRoot,
  * writeContainedOutputFile renames a finished file into place instead, replacing what is there.
  */
 export declare function createContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
+/**
+ * Appends `data` to an existing single-link regular file inside the root that holds exactly
+ * `size` bytes, the count the caller says it wrote, so an append never lands after bytes the
+ * caller did not write. The checks writeContainedOutputFile makes run before the open; the opened
+ * file must be the one checked, and the root and its folders are checked again before the write.
+ * The data is synced before this resolves, so a run.json written after it never indexes bytes the
+ * disk may not hold.
+ */
+export declare function appendContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: Uint8Array, size: number): Promise<void>;
+/**
+ * Removes a single-link regular file or an empty folder inside the root. Nothing at the path, or a
+ * folder on it missing, is not an error. A link, a hard-linked file or a folder that holds anything
+ * is refused and kept.
+ */
+export declare function removeContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<void>;
 /**
  * A file in a run directory or a preflight journal. verify reads every run file whole to scan it,
  * and a frame whole to check it, so this covers the largest screenshot src/evidence/image.ts
@@ -99,6 +114,17 @@ export declare function readContainedRegularFile(rootInput: PreparedOutputRoot,
  * after it was opened is never read whole.
  */
 export declare function readOpenedAtMost(handle: FileHandle, maxBytes: number): Promise<Buffer | null>;
+/**
+ * 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, 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

@@ -1,5 +1,5 @@
 import { constants } from "node:fs";
-import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { lstat, mkdir, open, realpath, rename, rmdir, unlink, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { assertDirectoryIdentity, assertRegularFileOrMissing, isPathInside, prepareHumanishStorageDirectory, resolveExistingHumanishStorageDirectory, validatePreparedRunArtifactPaths, validatePreparedRunRootIdentity, } from "./paths.js";
@@ -150,6 +150,70 @@ export async function createContainedOutputFile(rootInput, relativePath, data) {
     }
     await handle.close();
 }
+/**
+ * Appends `data` to an existing single-link regular file inside the root that holds exactly
+ * `size` bytes, the count the caller says it wrote, so an append never lands after bytes the
+ * caller did not write. The checks writeContainedOutputFile makes run before the open; the opened
+ * file must be the one checked, and the root and its folders are checked again before the write.
+ * The data is synced before this resolves, so a run.json written after it never indexes bytes the
+ * disk may not hold.
+ */
+export async function appendContainedOutputFile(rootInput, relativePath, data, size) {
+    const filePath = await prepareContainedOutputFile(rootInput, relativePath);
+    const root = await resolveOutputRoot(rootInput);
+    await assertContainedDirectoryChain(root, path.dirname(filePath));
+    const before = await lstat(filePath, { bigint: true });
+    if (!before.isFile() || before.nlink > 1n)
+        throw new Error(`${relativePath} is not a single-link regular file.`);
+    // O_NONBLOCK: a file swapped for a FIFO after the lstat fails the open at once (no reader), where
+    // a blocking open would wait for a reader and hold up every later write in the run's queue.
+    // Writes to a regular file ignore it.
+    const handle = await open(filePath, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const after = await handle.stat({ bigint: true });
+        if (!after.isFile() || after.nlink > 1n || after.dev !== before.dev || after.ino !== before.ino)
+            throw new Error(`${relativePath} changed while it was opened.`);
+        if (after.size !== BigInt(size))
+            throw new Error(`${relativePath} holds ${after.size} bytes, not ${size}.`);
+        if ((await resolveOutputRoot(rootInput)) !== root)
+            throw new Error("Output root changed after it was prepared.");
+        await assertContainedDirectoryChain(root, path.dirname(filePath));
+        const { bytesWritten } = await handle.write(data, 0, data.length);
+        if (bytesWritten !== data.length)
+            throw new Error(`${relativePath} was not appended in full.`);
+        await handle.datasync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Removes a single-link regular file or an empty folder inside the root. Nothing at the path, or a
+ * folder on it missing, is not an error. A link, a hard-linked file or a folder that holds anything
+ * is refused and kept.
+ */
+export async function removeContainedOutputFile(rootInput, relativePath) {
+    assertSafeRelativeOutputPath(relativePath, false);
+    const root = await resolveOutputRoot(rootInput);
+    const candidate = path.resolve(root, normalizeRelativeOutputPath(relativePath));
+    if (!isPathInside(root, candidate) || candidate === root)
+        throw new Error("Output file must stay inside its selected root.");
+    let stats;
+    try {
+        await assertContainedDirectoryChain(root, path.dirname(candidate));
+        stats = await lstat(candidate, { bigint: true });
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (stats.isDirectory())
+        return rmdir(candidate);
+    if (!stats.isFile() || stats.nlink > 1n)
+        throw new Error(`${relativePath} is not a single-link regular file.`);
+    await unlink(candidate);
+}
 // The most humanish reads of one file of each kind. A larger file is refused unread.
 /**
  * A file in a run directory or a preflight journal. verify reads every run file whole to scan it,
@@ -240,6 +304,42 @@ export async function readOpenedAtMost(handle, maxBytes) {
         chunks.push(chunk.subarray(0, bytesRead));
     }
 }
+/**
+ * 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, 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, start) };
+    }
+    catch {
+        return { status: "refused", reason: "unreadable", limit: length };
+    }
+    finally {
+        await opened.handle.close().catch(() => { });
+    }
+}
+/**
+ * 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 < bytes.length) {
+        const { bytesRead } = await handle.read(bytes, total, bytes.length - total, start + total);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return bytes.subarray(0, total);
+}
 /** The caller owns this checked descriptor and must close it after reading/streaming. */
 export async function openContainedRegularFile(rootInput, relativePath) {
     const opened = await openContained(rootInput, relativePath);

package/dist/run/evidence-files.d.ts

@@ -1,3 +1,4 @@
+import { type BigIntStats } from "node:fs";
 import { type PreparedOutputRoot } from "./contained-output.js";
 /**
  * Analysis inputs are retained local artifacts, never URLs or caller-selected outputs. The path is
@@ -17,6 +18,8 @@ export declare function decodesToPlainRelativePath(value: string, maxLength: num
  * authority to select another file or initiate a network request.
  */
 export declare function readBoundedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<Buffer | null>;
+/** The fields of a file's lstat that sameFile compares: which file it is, its size and times. */
+export type FileStamp = Pick<BigIntStats, "dev" | "ino" | "size" | "mtimeNs" | "ctimeNs">;
 /**
  * After a bounded read returned nothing: true when the file is absent, false when something is
  * there that could not be read. Errors other than ENOENT propagate.
@@ -25,6 +28,7 @@ export declare function pathMissing(filePath: string): Promise<boolean>;
 export type BoundedFileResult = {
     state: "read";
     bytes: Buffer;
+    stamp: FileStamp;
 } | {
     state: "limit";
     size: bigint;
@@ -37,6 +41,13 @@ export declare function readBoundedFileResult(root: PreparedOutputRoot, relative
  * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
  * same size and times, from the first check to the last. Size refusals are distinguished only after
  * the same checks. `relativePath` uses `/`, and any name a contained read accepts
- * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did. A read
+ * returns the stamp it held the file to.
  */
 export declare function readUnchangedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;
+/**
+ * True when the file readUnchangedFile would read at `relativePath` is still the file `stamp`
+ * describes: it passes the same root, parent and leaf checks, before and after its lstat matches
+ * the stamp. Opens nothing.
+ */
+export declare function isUnchangedFile(root: PreparedOutputRoot, relativePath: string, stamp: FileStamp): Promise<boolean>;

package/dist/run/evidence-files.js

@@ -99,47 +99,19 @@ export async function readBoundedFileResult(root, relativePath, maxBytes) {
  * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
  * same size and times, from the first check to the last. Size refusals are distinguished only after
  * the same checks. `relativePath` uses `/`, and any name a contained read accepts
- * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did. A read
+ * returns the stamp it held the file to.
  */
 export async function readUnchangedFile(root, relativePath, maxBytes) {
-    if (!isSafeRelativeFilePath(relativePath) ||
-        relativePath.includes("\\") ||
-        !Number.isSafeInteger(maxBytes) ||
-        maxBytes < 1)
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
         return unavailable;
-    const validateRoot = async () => {
-        if ("physicalRunRoot" in root) {
-            await validatePreparedRunRootIdentity(root);
-            return root.physicalRunRoot;
-        }
-        await assertPreparedSelectedOutputDirectory(root);
-        return root.physicalPath;
-    };
     try {
-        const physicalRoot = await validateRoot();
-        const candidate = path.join(physicalRoot, relativePath);
-        if (!isPathInside(physicalRoot, candidate) || candidate === physicalRoot)
-            return unavailable;
-        const validateParents = async () => {
-            let current = physicalRoot;
-            for (const segment of relativePath.split("/").slice(0, -1)) {
-                current = path.join(current, segment);
-                const info = await lstat(current);
-                if (!info.isDirectory() || info.isSymbolicLink())
-                    throw new Error("Unsafe analysis input directory.");
-            }
-        };
-        await validateParents();
-        const before = await lstat(candidate, { bigint: true });
-        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n)
-            return unavailable;
-        if ((await realpath(candidate)) !== candidate)
+        const located = await locateContainedFile(root, relativePath);
+        if (located === null)
             return unavailable;
+        const { candidate, before, stillSameFile } = located;
         if (before.size > BigInt(maxBytes)) {
-            if ((await validateRoot()) !== physicalRoot)
-                return unavailable;
-            await validateParents();
-            if (!sameFile(before, await lstat(candidate, { bigint: true })))
+            if (!(await stillSameFile(before)))
                 return unavailable;
             return { state: "limit", size: before.size };
         }
@@ -153,12 +125,10 @@ export async function readUnchangedFile(root, relativePath, maxBytes) {
                 !sameFile(before, await handle.stat({ bigint: true })) ||
                 bytes.length !== Number(before.size))
                 return unavailable;
-            if ((await validateRoot()) !== physicalRoot)
-                return unavailable;
-            await validateParents();
-            if (!sameFile(before, await lstat(candidate, { bigint: true })))
+            if (!(await stillSameFile(before)))
                 return unavailable;
-            return { state: "read", bytes };
+            const { dev, ino, size, mtimeNs, ctimeNs } = before;
+            return { state: "read", bytes, stamp: { dev, ino, size, mtimeNs, ctimeNs } };
         }
         finally {
             await handle.close();
@@ -168,3 +138,63 @@ export async function readUnchangedFile(root, relativePath, maxBytes) {
         return unavailable;
     }
 }
+/**
+ * True when the file readUnchangedFile would read at `relativePath` is still the file `stamp`
+ * describes: it passes the same root, parent and leaf checks, before and after its lstat matches
+ * the stamp. Opens nothing.
+ */
+export async function isUnchangedFile(root, relativePath, stamp) {
+    try {
+        const located = await locateContainedFile(root, relativePath);
+        return (located !== null && sameFile(stamp, located.before) && (await located.stillSameFile(stamp)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The contained single-link regular file at `relativePath`: its path, its lstat, and a recheck that
+ * the root, its parents and the leaf are unchanged since. Null for a path or leaf a read refuses;
+ * a root or parent that fails its check throws.
+ */
+async function locateContainedFile(root, relativePath) {
+    if (!isSafeRelativeFilePath(relativePath) || relativePath.includes("\\"))
+        return null;
+    const validateRoot = async () => {
+        if ("physicalRunRoot" in root) {
+            await validatePreparedRunRootIdentity(root);
+            return root.physicalRunRoot;
+        }
+        await assertPreparedSelectedOutputDirectory(root);
+        return root.physicalPath;
+    };
+    const physicalRoot = await validateRoot();
+    const candidate = path.join(physicalRoot, relativePath);
+    if (!isPathInside(physicalRoot, candidate) || candidate === physicalRoot)
+        return null;
+    const validateParents = async () => {
+        let current = physicalRoot;
+        for (const segment of relativePath.split("/").slice(0, -1)) {
+            current = path.join(current, segment);
+            const info = await lstat(current);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error("Unsafe analysis input directory.");
+        }
+    };
+    await validateParents();
+    const before = await lstat(candidate, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n)
+        return null;
+    if ((await realpath(candidate)) !== candidate)
+        return null;
+    return {
+        candidate,
+        before,
+        stillSameFile: async (stamp) => {
+            if ((await validateRoot()) !== physicalRoot)
+                return false;
+            await validateParents();
+            return sameFile(stamp, await lstat(candidate, { bigint: true }));
+        },
+    };
+}

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 = {}) {