humanish 0.115.0 → 0.117.0

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;

package/dist/run/reclaim.js

@@ -8,10 +8,11 @@
 // reclaim-receipt.json is written before the first kill and after each one, so an exit at any
 // point leaves a record of every sandbox not yet confirmed gone. `--check` asks E2B the same
 // questions and kills nothing.
+import { e2bAccount, e2bConnection } from "../substrates/e2b/connection.js";
 import { E2B_DEBUG_ENV, e2bDebugMode, loadE2BDesktopModule, } from "../substrates/e2b/sdk.js";
-import { containedPathAbsent, readContainedRegularFile, } from "./contained-output.js";
+import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "./contained-output.js";
 import { discardPreflightJournal, listPreflightJournals, preflightReclaimDecision, } from "./preflight-receipts.js";
-import { readRunJsonIfExists, resolveRunPath } from "./locate.js";
+import { readRunJsonIfExists, resolveRunPath, runJsonValue } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { RUN_STATUS_FILE } from "./status.js";
 import { isRecord } from "./type-guards.js";
@@ -80,7 +81,7 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
         return {
             ...base,
             runId,
-            error: { code: "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE", message: UNREADABLE_MESSAGE },
+            error: { code: "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE", message: reclaimed.message },
         };
     const { state, receiptCount, outcomes, tagSearch, createsInFlight } = reclaimed;
     return {
@@ -105,8 +106,14 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
  * whatever its records say.
  */
 async function recordedNoSandbox(runPaths) {
-    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
-    const status = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    const bundleRead = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const statusRead = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    // A record that is there and refused could say anything, so neither shortcut applies and
+    // reclaim runs in full. A missing one says nothing, as before.
+    if (bundleRead.status === "refused" || statusRead.status === "refused")
+        return undefined;
+    const bundle = runJsonValue(bundleRead);
+    const status = runJsonValue(statusRead);
     const records = [bundle, status].filter(isRecord);
     const reason = records.length > 0 && records.every((record) => record.mode === "dry-run")
         ? "dry-run"
@@ -118,15 +125,18 @@ async function recordedNoSandbox(runPaths) {
             : undefined;
     if (reason === undefined)
         return undefined;
-    if (!(await containedPathAbsent(runPaths, RECLAIM_RECEIPT_ARTIFACT))) {
-        const earlier = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+    const earlierRead = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
+    if (earlierRead.status !== "missing") {
+        const earlier = runJsonValue(earlierRead);
         if (!isRecord(earlier) || !Array.isArray(earlier.outcomes) || earlier.outcomes.length > 0)
             return undefined;
     }
-    if (await containedPathAbsent(runPaths, SANDBOX_RECEIPTS_ARTIFACT))
+    const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    if (journal.status === "missing")
         return reason;
-    const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
-    return journal !== null && journal.toString("utf8").trim() === "" ? reason : undefined;
+    return journal.status === "read" && journal.bytes.toString("utf8").trim() === ""
+        ? reason
+        : undefined;
 }
 /** The execution failure kinds that leave a sandbox or a provider's resources unconfirmed. */
 const CLEANUP_KINDS = new Set(["sandbox-cleanup", "provider-cleanup"]);
@@ -190,7 +200,7 @@ export async function reclaimPreflightSandboxes(cwd, hooks = {}) {
         const reclaimed = await reclaimRoot(journal.root, journal.id, hooks, warnings);
         if (reclaimed.kind === "unreadable") {
             // The receipt may name a live sandbox; the journal stays for a later reclaim.
-            warnings.push(`Preflight ${journal.id} left alone: ${UNREADABLE_MESSAGE}`);
+            warnings.push(`Preflight ${journal.id} left alone: ${reclaimed.message}`);
             states.push("unknown");
             continue;
         }
@@ -241,15 +251,28 @@ const E2B_DEBUG_REFUSAL = {
     message: `${E2B_DEBUG_ENV}=true puts the E2B SDK in debug mode, where Sandbox.kill reports success without contacting E2B. Nothing was killed and the receipts were kept; unset ${E2B_DEBUG_ENV} and run reclaim again.`,
 };
 const UNREADABLE_MESSAGE = "sandbox-receipts.ndjson is present but could not be read safely (not a single regular file, or a read error). Nothing was killed and the receipts were kept; check the file, then run reclaim again.";
+/**
+ * Why reclaim stopped before it killed or wrote anything: the receipts journal, or the receipt an
+ * earlier reclaim wrote, is there and cannot be read.
+ */
+function unreadableMessage(file, refusal) {
+    if (file === SANDBOX_RECEIPTS_ARTIFACT && refusal.reason !== "too-large")
+        return UNREADABLE_MESSAGE;
+    const kept = file === SANDBOX_RECEIPTS_ARTIFACT ? "the receipts were kept" : "the receipt was kept";
+    return `${refusalText(file, refusal)}. Nothing was killed and ${kept}; check the file, then run reclaim again.`;
+}
 /**
  * Find and stop (or, for `--check`, look up) every sandbox one directory owns: its receipts, the
  * creates this process reported, and E2B's tagged list, each once by exact id.
  */
 async function reclaimRoot(root, label, hooks, warnings) {
-    const bytes = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT);
-    if (bytes === null && !(await containedPathAbsent(root, SANDBOX_RECEIPTS_ARTIFACT)))
-        return { kind: "unreadable" };
-    const journal = bytes === null ? "" : bytes.toString("utf8");
+    const journalRead = await readContainedRegularFile(root, SANDBOX_RECEIPTS_ARTIFACT, RUN_ARTIFACT_MAX_BYTES);
+    if (journalRead.status === "refused")
+        return {
+            kind: "unreadable",
+            message: unreadableMessage(SANDBOX_RECEIPTS_ARTIFACT, journalRead),
+        };
+    const journal = journalRead.status === "read" ? journalRead.bytes.toString("utf8") : "";
     const receipts = parseSandboxReceipts(journal);
     const owners = parseSandboxOwners(journal, label);
     const check = hooks.check === true;
@@ -259,7 +282,8 @@ async function reclaimRoot(root, label, hooks, warnings) {
     let e2b;
     let moduleError;
     try {
-        e2b = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        const module = await (hooks.loadModule ?? loadE2BDesktopModule)();
+        e2b = e2bAccount(module, e2bConnection(hooks.env ?? process.env));
     }
     catch (error) {
         moduleError = `Cannot load @e2b/desktop to reach E2B: ${redactText(toErrorMessage(error))}`;
@@ -269,6 +293,9 @@ async function reclaimRoot(root, label, hooks, warnings) {
     // An earlier reclaim may have killed a sandbox no receipt names (the signal handler's creates
     // and tag finds). Its outcome is carried forward, so a later reclaim never erases that record.
     const earlier = check ? [] : await earlierOutcomes(root, label);
+    // The new receipt replaces the old one, so an old one that cannot be read stops reclaim here.
+    if (!Array.isArray(earlier))
+        return { kind: "unreadable", message: unreadableMessage(RECLAIM_RECEIPT_ARTIFACT, earlier) };
     const set = targetSet({
         e2b,
         check,

package/dist/run/run-clock.d.ts

@@ -0,0 +1,50 @@
+import type { ActorTraceItem } from "../actors/contract.js";
+import type { RunDesktopRecording } from "../evidence/desktop-recording-types.js";
+/** What the clock reads from a stream. A run.json stream and an Observer stream both have it. */
+export interface ClockStream {
+    actor?: {
+        items: readonly ActorTraceItem[];
+    };
+    liveActor?: {
+        items: readonly ActorTraceItem[];
+    };
+    recording?: RunDesktopRecording;
+}
+/** Where the run clock starts and ends, in epoch ms. */
+export interface RunClock {
+    startMs: number;
+    endMs: number;
+    /** Every moment on the clock, ascending without repeats, for keyboard seeking. */
+    boundariesMs: number[];
+}
+/** A desktop video's place on the run clock, in epoch ms. */
+export interface RecordingInterval {
+    startMs: number;
+    endMs: number;
+    recording: RunDesktopRecording;
+}
+/**
+ * A stream's recorded trace items: the finished actor's, else the flush of a participant still
+ * running, so every reader of a live run sees the items grow.
+ */
+export declare function traceItems(stream: ClockStream): readonly ActorTraceItem[];
+/**
+ * Whether a trace item is a capture, a frame of the participant's replay: a screenshot, or a
+ * scripted action that carries its own screenshot. A notice can cite an earlier screenshot for
+ * context, and does not capture it again.
+ */
+export declare function isCapture<Item extends Pick<ActorTraceItem, "kind" | "screenshotRef">>(item: Item): item is Item & {
+    screenshotRef: NonNullable<ActorTraceItem["screenshotRef"]>;
+};
+/**
+ * A participant's capture times in epoch ms, in recorded order. Null when a capture has no stamp
+ * or a stamp goes back: such a participant adds nothing to the run clock, and its replay runs at
+ * an average pace. Times are never made up from the actor's duration.
+ */
+export declare function captureTimes(stamps: readonly (number | undefined)[]): number[] | null;
+/** Where a desktop video sits on the run clock; null without a readable start and a length. */
+export declare function recordingInterval(recording: RunDesktopRecording | undefined): RecordingInterval | null;
+/** The run clock of every stream of a run, or null when none has a timed capture or a video. */
+export declare function runClock(streams: readonly ClockStream[]): RunClock | null;
+/** A run clock time or span in whole minutes and seconds: `02:31`. Minutes go past 59. */
+export declare function formatRunTime(ms: number): string;

package/dist/run/run-clock.js

@@ -0,0 +1,66 @@
+// The run clock: the Observer's study timeline, and the clock a reviewer note's time counts from.
+// It runs from the first to the last moment any participant recorded: a timed capture, or the start
+// or end of a desktop video. The Observer bundles this module, so it imports types only
+// (docs/decisions/0002-observer-is-one-self-contained-file.md).
+/**
+ * A stream's recorded trace items: the finished actor's, else the flush of a participant still
+ * running, so every reader of a live run sees the items grow.
+ */
+export function traceItems(stream) {
+    return stream.actor?.items ?? stream.liveActor?.items ?? [];
+}
+/**
+ * Whether a trace item is a capture, a frame of the participant's replay: a screenshot, or a
+ * scripted action that carries its own screenshot. A notice can cite an earlier screenshot for
+ * context, and does not capture it again.
+ */
+export function isCapture(item) {
+    return (item.kind === "screenshot" || item.kind === "ui_action") && Boolean(item.screenshotRef);
+}
+/**
+ * A participant's capture times in epoch ms, in recorded order. Null when a capture has no stamp
+ * or a stamp goes back: such a participant adds nothing to the run clock, and its replay runs at
+ * an average pace. Times are never made up from the actor's duration.
+ */
+export function captureTimes(stamps) {
+    const times = [];
+    for (const time of stamps) {
+        if (time === undefined || !Number.isFinite(time) || time < (times.at(-1) ?? -Infinity))
+            return null;
+        times.push(time);
+    }
+    return times;
+}
+/** Where a desktop video sits on the run clock; null without a readable start and a length. */
+export function recordingInterval(recording) {
+    if (!recording)
+        return null;
+    const startMs = Date.parse(recording.startedAt);
+    const endMs = startMs + recording.durationMs;
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || recording.durationMs <= 0)
+        return null;
+    return { startMs, endMs, recording };
+}
+/** The run clock of every stream of a run, or null when none has a timed capture or a video. */
+export function runClock(streams) {
+    const moments = new Set();
+    for (const stream of streams) {
+        const stamps = traceItems(stream)
+            .filter(isCapture)
+            .map((item) => (item.at === undefined ? Number.NaN : Date.parse(item.at)));
+        for (const time of captureTimes(stamps) ?? [])
+            moments.add(time);
+        const video = recordingInterval(stream.recording);
+        if (video)
+            moments.add(video.startMs).add(video.endMs);
+    }
+    const boundariesMs = [...moments].sort((a, b) => a - b);
+    if (boundariesMs.length === 0)
+        return null;
+    return { startMs: boundariesMs[0], endMs: boundariesMs.at(-1), boundariesMs };
+}
+/** A run clock time or span in whole minutes and seconds: `02:31`. Minutes go past 59. */
+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")}`;
+}

package/dist/run/run.js

@@ -15,7 +15,7 @@ import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./conta
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
 import { RunSecrets } from "./secrets.js";
 import { RUN_STATUS_FILE, beginRunStatus, runStatusOutcome, } from "./status.js";
-import { readRunJsonIfExists } from "./locate.js";
+import { readRunJsonIfExists, runJsonValue } from "./locate.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
     name = "RunLifecycleError";
@@ -166,7 +166,10 @@ function runPublisher(args) {
         });
         await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(publicBundle), "utf8");
         await afterBundle(publicBundle);
-        const status = recorded === undefined ? await readRunJsonIfExists(paths, RUN_STATUS_FILE) : undefined;
+        // The run writes its own status.json; one it refuses renders as a missing one does.
+        const status = recorded === undefined
+            ? runJsonValue(await readRunJsonIfExists(paths, RUN_STATUS_FILE))
+            : undefined;
         await writeContainedOutputFile(paths, "review.json", json(publicBundle.review), "utf8");
         await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle, status), "utf8");
         const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");