humanish 0.124.0 → 0.125.0

package/CHANGELOG.md

@@ -8,6 +8,21 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.125.0: Run bundle v3 with live items in append-only files, loadRunBundle, faster repeated verify (2026-10-12)
+
+humanish 0.125.0 keeps each live flush of a long study small, exports the run bundle loader, and
+verifies a finished study faster. Run bundles are now `humanish.run-bundle.v3`: a running
+participant's items so far live in an append-only file under `live/`, and each flush appends only
+the items recorded since the last one. On a synthetic run of 24 participants working 8 hours, a
+flush wrote about 0.23 MB in about 0.24 s, where 0.124.0 wrote up to 120 MB in 3.0 s. A finished
+v3 bundle differs from v2 only in its schema name; 0.124.0 and earlier refuse it by name.
+`loadRunBundle(cwd, run)` returns run.json with every trace and live file joined and checked, for
+v1, v2 and v3 bundles. The five verifies of a finished study read each screenshot once: 10 s in
+all for 1,203 screenshots, down from 35 s. A key in a study's title is redacted from the bundle,
+and one in a persona id or desktop template fails at parse instead of blocking the run.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.125.0)
+
 ## 0.124.0: Small Observer files for long studies, faster verify, closing reports under zero data retention (2026-10-12)
 
 humanish 0.124.0 keeps a long study's Observer files small, checks screenshots about eight times

package/CONTEXT.md

@@ -12,7 +12,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | Term                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                  |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | study               | What a user designs and runs: one YAML file that declares the subject, the actor, the participants and the caps. The file lives at `humanish/studies/<id>.yaml` with schema `humanish.study.v3`, read by `humanish study` and `--study`. humanish refuses a 0.107 `humanish.lab.v2` file, and `humanish migrate` converts it (second table).                                                                                                                                                                                          | `src/study/`; `StudyConfig` in `src/study/types.ts`, parsed by `parseStudy` in `src/study/config.ts`                                                                                                                                                                                                                                                                                                        |
-| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v2`) as the source of truth and each participant's trace in its own file.                                                                                                                                                                                                                                                                                                                                                         | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
+| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v3`) as the source of truth and each participant's trace in its own file.                                                                                                                                                                                                                                                                                                                                                         | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                              |
 | dry run             | A run with no live participant, from `--dry-run` or `mode: dry-run`. humanish writes a synthetic run bundle, review and Observer with no browser, model, keys or provider spend, and tests no product behavior. The `preview` route only dry-runs; "preview" names that route and nothing else.                                                                                                                                                                                                                                       | `runDryRun` in `src/run/dry-run.ts`; `resolveStudyDryRun` in `src/study/plan.ts`                                                                                                                                                                                                                                                                                                                            |
 | participant         | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the study config with `computerUseParticipants` (`src/study/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/study/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
 | persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/study/persona.ts`, `src/study/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                      |

package/README.md

@@ -335,7 +335,7 @@ and the library exports.
 - Breaking changes ship together in one minor release. Its release notes carry a migration
   table: each old form, its new form, and the change to make.
 - The study file and the run bundle carry versioned schemas, `humanish.study.v3` and
-  `humanish.run-bundle.v2`. A breaking change to either one bumps its version.
+  `humanish.run-bundle.v3`. A breaking change to either one bumps its version.
 
 Pin the exact version in `package.json` and read [CHANGELOG.md](CHANGELOG.md) before upgrading.
 
@@ -483,7 +483,7 @@ for the supported library seam.
 
 - run a study: `runStudy`, `RunStudyOptions`, `StudyOutcome`, `StudyResult`, `StudyEvent`, `routeOf`,
   `parseStudy`, `STUDY_SCHEMA`;
-- read a run: `verifyRun`, `renderObserver`, `RunBundle`, `ActorTrace`;
+- read a run: `verifyRun`, `loadRunBundle`, `renderObserver`, `RunBundle`, `ActorTrace`;
 - bring a participant: `ComputerUseProvider`, `ComputerUseExecutor`, `ProviderContext`,
   `createOpenAiResponsesProvider`, `runComputerUseLoop`, `defaultRedactionHooks`;
 - score a run: `AdapterScorerModule` and its scoring contexts.

package/dist/analysis/evidence.js

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { screenshotEvidenceError } from "../evidence/image.js";
 import { runIdOf } from "../run/paths.js";
 import { isRecord } from "../run/type-guards.js";
-import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "../run/bundle.js";
+import { isReadRunBundleSchema, RUN_BUNDLE_FILE } from "../run/bundle.js";
 import { loadStreamTraces } from "../run/stream-trace.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { digestAnalysisInput, hashAnalysisValue, validateAnalysisInputMetadata, } from "./validation.js";
@@ -30,7 +30,7 @@ function parseSource(prepared, bytes) {
         throw new Error("ANALYSIS_SOURCE_TOO_LARGE");
     const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
     if (!isRecord(value) ||
-        (value.schema !== RUN_BUNDLE_SCHEMA && value.schema !== RUN_BUNDLE_V1_SCHEMA) ||
+        !isReadRunBundleSchema(value.schema) ||
         value.runId !== runIdOf(prepared) ||
         !Array.isArray(value.streams) ||
         value.streams.length > EVIDENCE_LIMITS.participants ||

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { parseStudy } from "./study/config.js";
 export { STUDY_SCHEMA } from "./study/types.js";
 export type { StudyConfig } from "./study/types.js";
 export { verifyRun } from "./verify/verify.js";
+export { loadRunBundle } from "./run/locate.js";
 export type { VerifyResult } from "./verify/verify.js";
 export { renderObserver } from "./observer/render.js";
 export type { ObserverResult } from "./observer/render.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export { parseStudy } from "./study/config.js";
 export { STUDY_SCHEMA } from "./study/types.js";
 // Read a run.
 export { verifyRun } from "./verify/verify.js";
+export { loadRunBundle } from "./run/locate.js";
 export { renderObserver } from "./observer/render.js";
 // Bring a participant.
 export { runComputerUseLoop, stableProgressKey } from "./actors/computer-use/loop.js";

package/dist/observer/pinned-files.d.ts

@@ -17,10 +17,12 @@ export interface PinnedDirectory {
 /**
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
  * file larger than that is refused from its opened size and the read stops there, so a large file
- * is never held in memory.
+ * is never held in memory. With `length`, only the file's first `length` bytes are read, or all of
+ * a shorter file.
  */
 export declare function readContainedFile(root: PinnedDirectory, filePathInput: string, options?: {
     maxBytes?: number;
+    length?: number;
 }): Promise<Buffer | null>;
 export declare function openContainedFile(root: PinnedDirectory, filePathInput: string): Promise<{
     handle: FileHandle;

package/dist/observer/pinned-files.js

@@ -5,23 +5,26 @@ import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
-import { readOpenedAtMost } from "../run/contained-output.js";
+import { readOpenedAtMost, readOpenedPrefix } from "../run/contained-output.js";
 import { isPathInside, isSafeRunIdSegment } from "../run/paths.js";
 /**
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
  * file larger than that is refused from its opened size and the read stops there, so a large file
- * is never held in memory.
+ * is never held in memory. With `length`, only the file's first `length` bytes are read, or all of
+ * a shorter file.
  */
 export async function readContainedFile(root, filePathInput, options = {}) {
     const opened = await openContainedFile(root, filePathInput);
     if (!opened)
         return null;
     try {
-        const body = options.maxBytes === undefined
-            ? await opened.handle.readFile()
-            : opened.size > options.maxBytes
-                ? null
-                : await readOpenedAtMost(opened.handle, options.maxBytes);
+        const body = options.length !== undefined
+            ? await readOpenedPrefix(opened.handle, options.length)
+            : options.maxBytes === undefined
+                ? await opened.handle.readFile()
+                : opened.size > options.maxBytes
+                    ? null
+                    : await readOpenedAtMost(opened.handle, options.maxBytes);
         if (body === null)
             return null;
         // A write that landed during the read changed the file's mtime and ctime.

package/dist/observer/run-routes.js

@@ -165,9 +165,10 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
 }
 /** The run's trace files, read through its pinned folder. */
 function pinnedTraceReader(runRoot) {
-    return async (relativePath, maxBytes) => {
+    return async (relativePath, maxBytes, length) => {
         const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, relativePath), {
             maxBytes,
+            ...(length === undefined ? {} : { length }),
         }).catch(() => null);
         return bytes === null ? { refused: `${relativePath} could not be read` } : { bytes };
     };

package/dist/routes/computer-use/live-flush.d.ts

@@ -5,16 +5,21 @@ import type { RunBundle } from "../../run/bundle.js";
 import type { RunStudyHomes } from "../../study/run-study-homes.js";
 import type { DesktopParticipantRun } from "./types.js";
 export interface LiveTraceFlush {
-    /** Record a participant's recorded-so-far items; the bundle rewrite follows on the flush
-     *  schedule. */
+    /**
+     * Record a participant's recorded-so-far items; the bundle write follows on the flush schedule.
+     * Each item is deep-frozen here: the run writer appends an item to the participant's live file
+     * once, so an item edited after it was recorded would leave the file stale. A producer that
+     * needs a different item records a new one.
+     */
     flush: (participantId: string, items: readonly ActorTraceItem[], usage?: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
     /** Stop flushing, clear the timer and wait for an in-flight write. Call it on every exit. */
     stop: () => Promise<void>;
 }
 /**
  * Incremental live flush: as each participant's loop reports its recorded-so-far items,
- * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
- * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
+ * publish the in-progress bundle with per-stream `liveActor` partials so the attached
+ * Observer's 5s poll sees the timeline grow; the run writer appends each participant's new items
+ * to its live file. Throttled (one write per interval, trailing
  * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
  * any snapshot once the final write began, so a late flush cannot resurrect the in-progress
  * bundle. A flush failure is swallowed: mid-run observability must never break the run itself.

package/dist/routes/computer-use/live-flush.js

@@ -2,8 +2,9 @@ import { attachObserverRuntimeStreamUrls } from "../../observer/render.js";
 import {} from "../../observer/run-routes.js";
 /**
  * Incremental live flush: as each participant's loop reports its recorded-so-far items,
- * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
- * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
+ * publish the in-progress bundle with per-stream `liveActor` partials so the attached
+ * Observer's 5s poll sees the timeline grow; the run writer appends each participant's new items
+ * to its live file. Throttled (one write per interval, trailing
  * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
  * any snapshot once the final write began, so a late flush cannot resurrect the in-progress
  * bundle. A flush failure is swallowed: mid-run observability must never break the run itself.
@@ -56,7 +57,9 @@ export function startLiveTraceFlush(args) {
                                         ids: { model },
                                     }),
                                 ...liveMetadataByStream.get(stream.id),
-                                items: [...liveItems],
+                                // The flush's own copy, replaced and never changed, so the run writer compares
+                                // each write's items with the last by identity.
+                                items: liveItems,
                             },
                         };
                 }),
@@ -94,6 +97,8 @@ export function startLiveTraceFlush(args) {
         const streamId = streamIdByParticipant.get(participantId);
         if (streamId === undefined)
             return;
+        for (const item of items)
+            deepFreeze(item);
         liveItemsByStream.set(streamId, items.slice());
         if (metadata !== undefined)
             liveMetadataByStream.set(streamId, metadata);
@@ -112,6 +117,14 @@ export function startLiveTraceFlush(args) {
     };
     return { flush, stop };
 }
+/** `value` and every object and array it holds, frozen. */
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+}
 /**
  * The live desktop views (runtime stream URLs) participants report, attached to whichever Observer shows
  * the run. The URLs carry auth, so they live in memory and on the Observer result, never in run

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,13 @@ 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.
+ */
+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>;
 /** 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,38 @@ 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.
+ */
+export async function readContainedPrefix(rootInput, relativePath, length) {
+    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) };
+    }
+    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. */
+export async function readOpenedPrefix(handle, length) {
+    const bytes = Buffer.allocUnsafe(length);
+    let total = 0;
+    while (total < length) {
+        const { bytesRead } = await handle.read(bytes, total, length - total, 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 }));
+        },
+    };
+}