humanish 0.115.0 → 0.116.0

package/dist/run/evidence-files.js

@@ -2,11 +2,12 @@ import { constants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
 import { isPathInside, validatePreparedRunRootIdentity } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, } from "./contained-output.js";
+import { assertPreparedSelectedOutputDirectory, isSafeRelativeFilePath, readOpenedAtMost, } from "./contained-output.js";
 import { isNodeError } from "./type-guards.js";
 // Reading a file from a retained run directory for analysis: the path must be a plain relative path
 // inside the run, the file a single-link regular file that stays inside it, and the read bounded.
-// Evidence capture, analysis jobs, the analysis store, cost reading and export all read through here.
+// Evidence capture, analysis jobs, the analysis store, cost reading, verify and export all read
+// through here.
 /**
  * Analysis inputs are retained local artifacts, never URLs or caller-selected outputs. The path is
  * percent-decoded up to five times, and each round must still be a plain relative path, so an
@@ -87,29 +88,24 @@ export async function pathMissing(filePath) {
         throw error;
     }
 }
-/**
- * At most `maxBytes` from the start of an opened file, or null when it holds more. It reads by
- * position, in chunks of up to 64 KiB, and stops one byte past the limit, so a file that grew
- * after it was opened is never read whole.
- */
-export async function readOpenedAtMost(handle, maxBytes) {
-    const chunks = [];
-    let total = 0;
-    for (;;) {
-        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
-        const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
-        if (bytesRead === 0)
-            return Buffer.concat(chunks, total);
-        total += bytesRead;
-        if (total > maxBytes)
-            return null;
-        chunks.push(chunk.subarray(0, bytesRead));
-    }
-}
 const unavailable = { state: "unavailable" };
-/** Size refusals are distinguished only after the same contained regular-file checks. */
+/** readUnchangedFile for an analysis input, whose path must also be an evidence path. */
 export async function readBoundedFileResult(root, relativePath, maxBytes) {
-    if (!isEvidencePath(relativePath) || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    return isEvidencePath(relativePath)
+        ? readUnchangedFile(root, relativePath, maxBytes)
+        : unavailable;
+}
+/**
+ * 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.
+ */
+export async function readUnchangedFile(root, relativePath, maxBytes) {
+    if (!isSafeRelativeFilePath(relativePath) ||
+        relativePath.includes("\\") ||
+        !Number.isSafeInteger(maxBytes) ||
+        maxBytes < 1)
         return unavailable;
     const validateRoot = async () => {
         if ("physicalRunRoot" in root) {

package/dist/run/locate.d.ts

@@ -1,14 +1,43 @@
 import { type PreparedRunArtifactPaths } from "./paths.js";
-import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
+import { type ContainedRefusal, type PreparedSelectedOutputDirectory } from "./contained-output.js";
 import type { RunPointer } from "./results.js";
 import { type RunBundle } from "./bundle.js";
+import { type BoundedFileResult } from "./evidence-files.js";
 /** The run input that resolves through latest.json rather than naming a run directory. */
 export declare const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
 export declare function resolveRunPath(cwd: string, runInput: string): Promise<PreparedRunArtifactPaths | null>;
 export declare function readLatest(runsRoot: PreparedSelectedOutputDirectory): Promise<RunPointer | null>;
-export declare function readRunJsonIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<unknown>;
-export declare function readRunTextIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<string | null>;
+/** A run file as text: its text, nothing at the path, or why it was refused. */
+export type RunTextRead = {
+    status: "read";
+    text: string;
+} | {
+    status: "missing";
+} | ContainedRefusal;
+/** A run file as JSON. `value` is undefined when the file is there but is not valid JSON. */
+export type RunJsonRead = {
+    status: "read";
+    value: unknown;
+} | {
+    status: "missing";
+} | ContainedRefusal;
+/**
+ * The JSON, or null for a file that is missing, refused or not valid JSON: for a caller that
+ * treats the three alike, as every reader did before a refusal had its own state.
+ */
+export declare function runJsonValue(read: RunJsonRead): unknown;
+/** A run file as JSON, within RUN_ARTIFACT_MAX_BYTES. */
+export declare function readRunJsonIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<RunJsonRead>;
+/** A run file as text, within RUN_ARTIFACT_MAX_BYTES. */
+export declare function readRunTextIfExists(runPaths: PreparedRunArtifactPaths, ...segments: string[]): Promise<RunTextRead>;
+/**
+ * A run file, read whole through readUnchangedFile: `limit` when it holds more than
+ * RUN_ARTIFACT_MAX_BYTES, `unavailable` when it is missing, unsafe, or changes while it is read.
+ * A `\` in the path reads as `/`.
+ */
+export declare function readSafeRunArtifact(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<BoundedFileResult>;
+/** readSafeRunArtifact's bytes, or null for any file it does not read. */
 export declare function readSafeRunArtifactBytes(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<Buffer | null>;
 export declare function readSafeRunArtifactJson(runPaths: PreparedRunArtifactPaths, relativePath: string): Promise<unknown>;
 export declare function loadRunBundle(cwdInput: string, runInput: string): Promise<{

package/dist/run/locate.js

@@ -1,10 +1,9 @@
-import { lstat } from "node:fs/promises";
 import path from "node:path";
-import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDirectory, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "./paths.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, } from "./contained-output.js";
+import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveExistingRunDirectory, resolveLatestRunDirectory, RUNS_RELATIVE_ROOT, validatePreparedRunArtifactPaths, } from "./paths.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, ContainedReadRefusedError, LATEST_POINTER_MAX_BYTES, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isRunBundle, isRunPointer } from "./bundle-shape.js";
-import { isNodeError } from "./type-guards.js";
+import { readUnchangedFile } from "./evidence-files.js";
 /** The run input that resolves through latest.json rather than naming a run directory. */
 export const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
@@ -33,59 +32,61 @@ export async function resolveRunPath(cwd, runInput) {
     return bindExistingRunArtifactPaths(cwd, runInput);
 }
 export async function readLatest(runsRoot) {
-    const latestPath = path.join(runsRoot.physicalPath, "latest.json");
-    let latestStats;
-    try {
-        latestStats = await lstat(latestPath, { bigint: true });
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === "ENOENT") {
-            return null;
-        }
-        throw error;
-    }
-    if (latestStats.isSymbolicLink() || !latestStats.isFile() || latestStats.nlink !== 1n) {
-        throw new Error("Latest run pointer must be a single-link regular file.");
-    }
-    const bytes = await readContainedRegularFile(runsRoot, "latest.json");
-    if (!bytes) {
-        throw new Error("Latest run pointer changed while it was being read.");
+    const read = await readContainedRegularFile(runsRoot, "latest.json", LATEST_POINTER_MAX_BYTES);
+    if (read.status === "missing")
+        return null;
+    if (read.status === "refused") {
+        if (read.reason === "too-large")
+            throw new ContainedReadRefusedError(path.join(RUNS_RELATIVE_ROOT, "latest.json"), read);
+        throw new Error(read.reason === "not-regular" || read.reason === "directory"
+            ? "Latest run pointer must be a single-link regular file."
+            : "Latest run pointer changed while it was being read.");
     }
     let latest;
     try {
-        latest = JSON.parse(bytes.toString("utf8"));
+        latest = JSON.parse(read.bytes.toString("utf8"));
     }
     catch {
         return null;
     }
     return isRunPointer(latest) ? latest : null;
 }
+/**
+ * The JSON, or null for a file that is missing, refused or not valid JSON: for a caller that
+ * treats the three alike, as every reader did before a refusal had its own state.
+ */
+export function runJsonValue(read) {
+    return read.status === "read" ? (read.value ?? null) : null;
+}
+/** A run file as JSON, within RUN_ARTIFACT_MAX_BYTES. */
 export async function readRunJsonIfExists(runPaths, ...segments) {
-    const text = await readRunTextIfExists(runPaths, ...segments);
-    if (text === null) {
-        return null;
-    }
+    const read = await readRunTextIfExists(runPaths, ...segments);
+    if (read.status !== "read")
+        return read;
     try {
-        return JSON.parse(text);
+        return { status: "read", value: JSON.parse(read.text) };
     }
     catch {
-        return null;
+        return { status: "read", value: undefined };
     }
 }
+/** A run file as text, within RUN_ARTIFACT_MAX_BYTES. */
 export async function readRunTextIfExists(runPaths, ...segments) {
-    const bytes = await readContainedRegularFile(runPaths, segments.join("/"));
-    return bytes?.toString("utf8") ?? null;
+    const read = await readContainedRegularFile(runPaths, segments.join("/"), RUN_ARTIFACT_MAX_BYTES);
+    return read.status === "read" ? { status: "read", text: read.bytes.toString("utf8") } : read;
 }
+/**
+ * A run file, read whole through readUnchangedFile: `limit` when it holds more than
+ * RUN_ARTIFACT_MAX_BYTES, `unavailable` when it is missing, unsafe, or changes while it is read.
+ * A `\` in the path reads as `/`.
+ */
+export async function readSafeRunArtifact(runPaths, relativePath) {
+    return readUnchangedFile(runPaths, relativePath.replace(/\\/g, "/"), RUN_ARTIFACT_MAX_BYTES);
+}
+/** readSafeRunArtifact's bytes, or null for any file it does not read. */
 export async function readSafeRunArtifactBytes(runPaths, relativePath) {
-    const normalized = relativePath.replace(/\\/g, "/");
-    const segments = normalized.split("/");
-    if (path.isAbsolute(relativePath) ||
-        path.win32.isAbsolute(relativePath) ||
-        segments.length === 0 ||
-        segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
-        return null;
-    }
-    return readContainedRegularFile(runPaths, normalized);
+    const read = await readSafeRunArtifact(runPaths, relativePath);
+    return read.state === "read" ? read.bytes : null;
 }
 export async function readSafeRunArtifactJson(runPaths, relativePath) {
     const bytes = await readSafeRunArtifactBytes(runPaths, relativePath);
@@ -112,7 +113,11 @@ export async function loadRunBundlePrepared(cwdInput, runPaths) {
     const cwd = path.resolve(cwdInput);
     await validatePreparedRunArtifactPaths(runPaths);
     const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
-    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const read = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    // A run.json it refuses is no reason to call the run absent: the caller reports why.
+    if (read.status === "refused")
+        throw new ContainedReadRefusedError(RUN_BUNDLE_FILE, read);
+    const bundle = read.status === "read" ? read.value : null;
     if (!isRunBundle(bundle)) {
         return null;
     }

package/dist/run/notes.d.ts

@@ -1,4 +1,3 @@
-import type { RunBundle } from "./bundle.js";
 import { type RunNote } from "./note-shape.js";
 import { type PreparedRunArtifactPaths } from "./paths.js";
 export interface RunNoteInput {
@@ -20,13 +19,6 @@ export type AddRunNoteResult =
         message: string;
     };
 };
-/** A run clock time as the Observer shows it: whole minutes and seconds, `02:31`. */
-export declare function formatRunTime(ms: number): string;
-/** The run clock: the first and last timed capture or desktop video moment, in epoch ms. */
-export declare function runClock(bundle: RunBundle): {
-    startMs: number;
-    endMs: number;
-} | null;
 /**
  * Adds a note as a new file, notes/<id>.json, created under a name nothing holds. It reads no other
  * note and replaces nothing, so notes added at the same time, from any process, are all kept.

package/dist/run/notes.js

@@ -1,6 +1,6 @@
 // Reviewer notes: free text a person adds at a moment of a recorded run. Each note is its own file
-// in the run directory (note-files.ts). A note's time counts from the run clock's start, the
-// first timed capture or desktop video of any participant, which is the Observer's study clock.
+// in the run directory (note-files.ts). A note's time counts from the start of the run clock
+// (run-clock.ts), which is the Observer's study timeline.
 import { cli } from "../cli/invocation.js";
 import { redactText } from "../evidence/redaction.js";
 import { createContainedOutputFile } from "./contained-output.js";
@@ -9,6 +9,7 @@ import { countRunNotes, encodeRunNote, newRunNoteId, runNoteFile } from "./note-
 import { MAX_NOTE_TEXT, MAX_RUN_NOTES } from "./note-shape.js";
 import { runParticipantCaptions, streamParticipantIdOf } from "./participant-records.js";
 import { physicalCwdOf, runIdOf } from "./paths.js";
+import { formatRunTime, runClock, traceItems } from "./run-clock.js";
 import { transientCommsKnownValueScrub } from "./transient-comms-secrets.js";
 import { isNodeError } from "./type-guards.js";
 const DEFAULT_AUTHOR = "you";
@@ -38,59 +39,12 @@ function participantStreamId(bundle, named) {
     const known = bundle.streams.map((stream) => `${captions.get(stream.id)} (${streamParticipantIdOf(stream) ?? stream.id})`);
     return refuse("HUMANISH_NOTE_UNKNOWN_PARTICIPANT", `Run ${bundle.runId} has no participant ${named}. Its participants are ${known.join(", ")}; leave the participant out for a note on the whole run.`);
 }
-/** A run clock time as the Observer shows it: whole minutes and seconds, `02:31`. */
-export function formatRunTime(ms) {
-    const seconds = Math.max(0, Math.floor(ms / 1000));
-    return `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}`;
-}
-/** The run clock: the first and last timed capture or desktop video moment, in epoch ms. */
-export function runClock(bundle) {
-    const moments = bundle.streams.flatMap((stream) => [
-        ...(captureTimes(stream) ?? []),
-        ...recordingMoments(stream),
-    ]);
-    if (moments.length === 0)
-        return null;
-    // A loop, since spreading a long recording's capture times into Math.min can overflow the stack.
-    let startMs = Infinity;
-    let endMs = -Infinity;
-    for (const moment of moments) {
-        startMs = Math.min(startMs, moment);
-        endMs = Math.max(endMs, moment);
-    }
-    return { startMs, endMs };
-}
-function traceItems(stream) {
-    return stream.actor?.items ?? stream.liveActor?.items ?? [];
-}
-const stamp = (item) => item.at === undefined ? Number.NaN : Date.parse(item.at);
-/**
- * A participant's capture times, as the Observer's study clock reads them: only when every capture
- * is stamped and the stamps never go back. Otherwise the participant adds nothing to the clock.
- */
-function captureTimes(stream) {
-    const times = traceItems(stream)
-        .filter((item) => (item.kind === "screenshot" || item.kind === "ui_action") && item.screenshotRef)
-        .map(stamp);
-    const ordered = times.every((time, index) => Number.isFinite(time) && (index === 0 || time >= times[index - 1]));
-    return ordered ? times : null;
-}
-function recordingMoments(stream) {
-    const recording = stream.recording;
-    if (!recording)
-        return [];
-    const startMs = Date.parse(recording.startedAt);
-    const endMs = startMs + recording.durationMs;
-    return Number.isFinite(startMs) && Number.isFinite(endMs) && recording.durationMs > 0
-        ? [startMs, endMs]
-        : [];
-}
 /** The latest stamped trace item at or before `moment`, among the given participants. */
 function nearestItem(streams, moment) {
     let best = null;
     for (const stream of streams)
         for (const item of traceItems(stream)) {
-            const time = stamp(item);
+            const time = item.at === undefined ? Number.NaN : Date.parse(item.at);
             if (Number.isFinite(time) && time <= moment && (best === null || time >= best.time))
                 best = { participant: stream.id, itemId: item.id, time };
         }
@@ -143,7 +97,7 @@ export async function addRunNote(prepared, input) {
     if (!loaded)
         return refuse("HUMANISH_INVALID_RUN_BUNDLE", `Run ${runIdOf(prepared)} has no run.json humanish can read safely, so no note was added. \`${cli(`verify --run ${runIdOf(prepared)}`)}\` says what is wrong with it.`);
     const { bundle } = loaded;
-    const clock = runClock(bundle);
+    const clock = runClock(bundle.streams);
     if (!clock)
         return refuse("HUMANISH_NOTE_NO_CLOCK", `Run ${bundle.runId} has no captures with recorded times, so a note cannot point at a moment of it.`);
     const participant = input.participant === null ? null : participantStreamId(bundle, input.participant);

package/dist/run/outcomes.d.ts

@@ -21,6 +21,30 @@ type ParticipantOutcomeDetail = {
  * goal says where the claim came from, as the run's participant line does.
  */
 export declare function sessionEndingInWords(trace: ActorTrace): string;
+/** The app a participant summary says the participant used. */
+interface SummaryApp {
+    /** "the app", or "the shared app" when every participant uses one instance. */
+    name: string;
+    /** Where the participant's browser ran, such as "in a hosted desktop browser". */
+    place?: string;
+    /** What a participant that never ran would have used, such as the app's URL. Defaults to `name`. */
+    target?: string;
+}
+/** What one participant's session came to when the bundle is written. */
+interface SummarySession {
+    trace?: ActorTrace | undefined;
+    /** Why the run skipped the participant before its session started. */
+    skippedReason?: string | undefined;
+    sessionError?: string | undefined;
+    /** The run is still going and has no outcome for this participant. */
+    inProgress: boolean;
+}
+/**
+ * The sentence a participant's simulation record carries. An ended session, a skip and a session
+ * error each say what happened, in that order; a participant without one is still using the app or
+ * never ran.
+ */
+export declare function participantSummary(name: string, app: SummaryApp, session: SummarySession): string;
 /** "; the gaps list the other 2", or "all 3" when nobody passed. Empty when the gaps list nobody. */
 export declare function gapsListClause(listed: number, total: number): string;
 /** One line a stakeholder can read, with the denominator attached to every number. */

package/dist/run/outcomes.js

@@ -146,6 +146,25 @@ export function sessionEndingInWords(trace) {
             return "ended";
     }
 }
+/**
+ * The sentence a participant's simulation record carries. An ended session, a skip and a session
+ * error each say what happened, in that order; a participant without one is still using the app or
+ * never ran.
+ */
+export function participantSummary(name, app, session) {
+    const where = app.place === undefined ? app.name : `${app.name} ${app.place}`;
+    if (session.trace !== undefined) {
+        const used = app.place === undefined ? where : `${where},`;
+        return `${name} used ${used} and ${sessionEndingInWords(session.trace)}.`;
+    }
+    if (session.skippedReason !== undefined)
+        return `${name} was ${session.skippedReason}.`;
+    if (session.sessionError !== undefined)
+        return `${name} did not finish a session: ${session.sessionError}`;
+    if (session.inProgress)
+        return `${name} is using ${where}.`;
+    return `${name} would use ${app.target ?? app.name}; no session ran.`;
+}
 /** "; the gaps list the other 2", or "all 3" when nobody passed. Empty when the gaps list nobody. */
 export function gapsListClause(listed, total) {
     if (listed <= 0)

package/dist/run/paths.d.ts

@@ -27,6 +27,8 @@ export interface LatestRunPathPointer {
  */
 export declare function isSafeRunIdSegment(runId: string): boolean;
 export declare function resolveRunsRoot(cwdInput: string): string;
+/** The latest-run pointer, `.humanish/runs/latest.json`, which the newest run writes. */
+export declare function resolveLatestRunPointer(cwdInput: string): string;
 export declare function prepareRunArtifactPaths(cwdInput: string, runId: string): Promise<PreparedRunArtifactPaths>;
 /** A new run's id names a directory that already exists. */
 export interface RunIdInUse {

package/dist/run/paths.js

@@ -18,6 +18,10 @@ export function isSafeRunIdSegment(runId) {
 export function resolveRunsRoot(cwdInput) {
     return path.resolve(cwdInput, RUNS_RELATIVE_ROOT);
 }
+/** The latest-run pointer, `.humanish/runs/latest.json`, which the newest run writes. */
+export function resolveLatestRunPointer(cwdInput) {
+    return path.resolve(cwdInput, LATEST_RUN_RELATIVE_PATH);
+}
 function resolveRunDirectory(cwdInput, runId) {
     if (!isSafeRunIdSegment(runId)) {
         throw new Error("Run id must be one non-empty path segment.");
@@ -45,7 +49,7 @@ function resolveRunArtifactPaths(cwdInput, runId) {
     return {
         absoluteRunRoot,
         relativeRunRoot: path.join(RUNS_RELATIVE_ROOT, runId),
-        absoluteLatestPointer: path.resolve(cwdInput, LATEST_RUN_RELATIVE_PATH),
+        absoluteLatestPointer: resolveLatestRunPointer(cwdInput),
         relativeLatestPointer: LATEST_RUN_RELATIVE_PATH,
     };
 }

package/dist/run/preflight-receipts.js

@@ -8,7 +8,7 @@ import { readdir, rmdir, unlink } from "node:fs/promises";
 import { hostname } from "node:os";
 import path from "node:path";
 import { parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT } from "./sandbox-receipts.js";
-import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "./contained-output.js";
 const PREFLIGHT_DIR = "preflight";
 // Written when the probe finished without confirming its kill: the owner no longer holds the
 // sandbox, so reclaim may act even while the owning process lives on.
@@ -54,11 +54,12 @@ export async function openPreflightJournal(cwd, leaseMs) {
     await writeContainedOutputFile(root, OWNER_FILE, `${JSON.stringify(owner)}\n`, "utf8");
     return { id, root, owner };
 }
-function parseOwner(bytes) {
-    if (bytes === null)
+/** The owner record, or undefined when it is missing, refused or malformed: "missing or unreadable". */
+function parseOwner(read) {
+    if (read.status !== "read")
         return undefined;
     try {
-        const value = JSON.parse(bytes.toString("utf8"));
+        const value = JSON.parse(read.bytes.toString("utf8"));
         if (typeof value.hostname !== "string" ||
             typeof value.pid !== "number" ||
             typeof value.createdAt !== "string" ||
@@ -90,7 +91,7 @@ export async function listPreflightJournals(cwd) {
         const root = await bindExistingManagedHumanishOutputDirectory(cwd, PREFLIGHT_DIR, entry.name);
         if (!root)
             continue;
-        const owner = parseOwner(await readContainedRegularFile(root, OWNER_FILE));
+        const owner = parseOwner(await readContainedRegularFile(root, OWNER_FILE, RUN_ARTIFACT_MAX_BYTES));
         journals.push({ id: entry.name, root, ...(owner === undefined ? {} : { owner }) });
     }
     return journals;
@@ -118,10 +119,14 @@ function leaseEndsAt(journal, receipts) {
  * another process). Anything else may be a live probe, and the reason says why it was left.
  */
 export async function preflightReclaimDecision(journal, nowMs) {
-    if ((await readContainedRegularFile(journal.root, ABANDONED_MARKER)) !== null)
+    // Only a marker that reads hands the journal over: one refused (a link, say) keeps it.
+    const marker = await readContainedRegularFile(journal.root, ABANDONED_MARKER, RUN_ARTIFACT_MAX_BYTES);
+    if (marker.status === "read")
         return { reclaim: true };
-    const receipts = await readContainedRegularFile(journal.root, SANDBOX_RECEIPTS_ARTIFACT);
-    const endsAt = leaseEndsAt(journal, receipts === null ? null : receipts.toString("utf8"));
+    // Refused receipts give no lease, as missing ones do; the owner's lease still decides, and
+    // reclaim refuses the unreadable journal before it kills anything.
+    const receipts = await readContainedRegularFile(journal.root, SANDBOX_RECEIPTS_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    const endsAt = leaseEndsAt(journal, receipts.status === "read" ? receipts.bytes.toString("utf8") : null);
     if (endsAt !== undefined && nowMs > endsAt)
         return { reclaim: true };
     const until = endsAt === undefined ? "" : `; its lease ends at ${new Date(endsAt).toISOString()}`;

package/dist/run/project.js

@@ -2,7 +2,7 @@
 // (package.json, humanish/ personas and scenarios) without following links out of it.
 import { lstat, stat } from "node:fs/promises";
 import path from "node:path";
-import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, readContainedRegularFile, } from "./contained-output.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, readContainedRegularFile, refusalText, PROJECT_FILE_MAX_BYTES, } from "./contained-output.js";
 import { isNodeError, isRecord } from "./type-guards.js";
 async function inspectImplicitProjectPath(projectRoot, relativePath) {
     const segments = relativePath.replace(/\\/g, "/").split("/");
@@ -61,11 +61,14 @@ export async function readImplicitProjectFile(projectRoot, relativePath) {
     if (!stats.isFile() || stats.nlink !== 1n) {
         throw new Error(`Implicit project file must be a single-link regular file: ${relativePath}`);
     }
-    const bytes = await readContainedRegularFile(projectRoot, relativePath.replace(/\\/g, "/"));
-    if (!bytes) {
+    const read = await readContainedRegularFile(projectRoot, relativePath.replace(/\\/g, "/"), PROJECT_FILE_MAX_BYTES);
+    if (read.status === "refused" && read.reason === "too-large")
+        throw new Error(`Implicit project file ${refusalText(relativePath, read)}.`);
+    // Gone or swapped since it was inspected above.
+    if (read.status !== "read") {
         throw new Error(`Implicit project file changed while it was being read: ${relativePath}`);
     }
-    return bytes.toString("utf8");
+    return read.bytes.toString("utf8");
 }
 export async function readPackageName(projectRoot) {
     const text = await readImplicitProjectFile(projectRoot, "package.json");

package/dist/run/reclaim-outcomes.d.ts

@@ -1,6 +1,6 @@
 import { type E2BTagSearch } from "../substrates/e2b/sandbox.js";
-import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
-import { type PreparedOutputRoot } from "./contained-output.js";
+import type { E2BAccount } from "../substrates/e2b/connection.js";
+import { type ContainedRefusal, type PreparedOutputRoot } from "./contained-output.js";
 export declare const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
 export declare const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
 /**
@@ -50,7 +50,7 @@ export interface Target {
  * kills leaves a record of each one not yet confirmed gone.
  */
 export declare function targetSet(options: {
-    e2b: E2BDesktopModule | undefined;
+    e2b: E2BAccount | undefined;
     check: boolean;
     requestTimeoutMs: number;
     earlier: ReclaimOutcome[];
@@ -66,16 +66,18 @@ export declare function targetSet(options: {
     finish(outcomes: readonly ReclaimOutcome[], state: ReclaimState): Promise<void>;
 };
 /** Search E2B by each distinct tag set; done only when every search finished. */
-export declare function searchTagSets(e2b: E2BDesktopModule | undefined, tagSets: readonly Record<string, string>[], options: {
+export declare function searchTagSets(e2b: E2BAccount | undefined, tagSets: readonly Record<string, string>[], options: {
     requestTimeoutMs: number;
     unavailable: string;
 }): Promise<E2BTagSearch>;
 export declare const GONE: Set<ReclaimOutcomeState>;
 /**
  * The outcomes an earlier reclaim of this directory recorded, by digest. A receipt written before
- * 0.110 names raw ids, which are digested; an unreadable or foreign receipt carries nothing.
+ * 0.110 names raw ids, which are digested; a missing, malformed or foreign receipt carries
+ * nothing. A receipt that is there and refused is returned as the refusal, so reclaim stops
+ * before its own receipt replaces one it could not read.
  */
-export declare function earlierOutcomes(root: PreparedOutputRoot, label: string): Promise<ReclaimOutcome[]>;
+export declare function earlierOutcomes(root: PreparedOutputRoot, label: string): Promise<ReclaimOutcome[] | ContainedRefusal>;
 export declare function rootState(outcomes: readonly ReclaimOutcome[], check: boolean, searched: boolean): ReclaimState;
 /** Resolves when `settled` does, or after `ms` if given, whichever is first. */
 export declare function settledWithin(settled: Promise<void>, ms: number | undefined): Promise<void>;

package/dist/run/reclaim-outcomes.js

@@ -4,7 +4,7 @@
 // receipt writer. src/run/reclaim.ts decides what to find; this module records what happened.
 import { REDACTED_SANDBOX_ID, redactText, sandboxIdDigest, toErrorMessage, } from "../evidence/redaction.js";
 import { destroyE2BSandbox, findE2BSandboxesByTags, inspectE2BSandbox, } from "../substrates/e2b/sandbox.js";
-import { readContainedRegularFile, writeContainedOutputFile, } from "./contained-output.js";
+import { readContainedRegularFile, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "./contained-output.js";
 import { scrubSandboxIds } from "./sandbox-ids.js";
 import { isRecord } from "./type-guards.js";
 export const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
@@ -122,15 +122,19 @@ const OUTCOME_STATES = new Set([
 ]);
 /**
  * The outcomes an earlier reclaim of this directory recorded, by digest. A receipt written before
- * 0.110 names raw ids, which are digested; an unreadable or foreign receipt carries nothing.
+ * 0.110 names raw ids, which are digested; a missing, malformed or foreign receipt carries
+ * nothing. A receipt that is there and refused is returned as the refusal, so reclaim stops
+ * before its own receipt replaces one it could not read.
  */
 export async function earlierOutcomes(root, label) {
+    const read = await readContainedRegularFile(root, RECLAIM_RECEIPT_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    if (read.status === "refused")
+        return read;
+    if (read.status === "missing")
+        return [];
     let parsed;
     try {
-        const bytes = await readContainedRegularFile(root, RECLAIM_RECEIPT_ARTIFACT);
-        if (bytes === null)
-            return [];
-        parsed = JSON.parse(bytes.toString("utf8"));
+        parsed = JSON.parse(read.bytes.toString("utf8"));
     }
     catch {
         return [];

package/dist/run/reclaim.d.ts

@@ -33,6 +33,11 @@ export interface ReclaimResult {
 export interface ReclaimHooks {
     /** Tests inject a fake @e2b/desktop module; default loads the real one. */
     loadModule?: () => Promise<E2BDesktopModule>;
+    /**
+     * The env whose E2B_API_KEY and E2B_DOMAIN every E2B call carries. Defaults to process.env, where
+     * the CLI put the run's key before the run started.
+     */
+    env?: Readonly<Record<string, string | undefined>>;
     requestTimeoutMs?: number;
     /** Ask E2B whether each sandbox still exists, and kill nothing. */
     check?: boolean;