humanish 0.114.0 → 0.116.0

package/dist/run/note-files.js

@@ -1,29 +1,46 @@
 // Reviewer notes on disk: one file per note, notes/<id>.json (humanish.run-note.v1) in the run
-// directory. A note is written once, to a temporary file that link(2) gives its name only when
-// nothing holds that name, and is never rewritten, so a writer never reads or replaces another
-// writer's note and no lock is needed. An id starts
-// with its creation time, so the files sort in the order they were added, and ends in random
-// bits. Readers list notes/ and read each file within MAX_NOTE_FILE_BYTES, skipping and naming
-// anything that is not a readable note of the run.
+// directory. A note is written once, by creating its name only when nothing holds it, and is never
+// rewritten, so a writer never reads or replaces another writer's note and no lock is needed. An
+// id starts with its creation time, so the files sort in the order they were added, and ends in
+// random bits. Readers list notes/ and read each file within MAX_NOTE_FILE_BYTES, skipping and
+// naming anything that is not a readable note of the run, including a note still being written.
 import { randomBytes } from "node:crypto";
 import { lstat, opendir } from "node:fs/promises";
 import path from "node:path";
+import { z } from "zod";
 import { scanEncodedTextCached } from "../evidence/encoded-text.js";
 import { readBoundedFileResult } from "./evidence-files.js";
-import { runIdOf } from "./paths.js";
-import { isNodeError, isRecord } from "./type-guards.js";
+import { MAX_NOTE_TEXT, MAX_RUN_NOTES, NOTE_FIELD_LIMITS, NOTE_ID, } from "./note-shape.js";
+import { runIdOf, validatePreparedRunRootIdentity, } from "./paths.js";
+import { isNodeError } from "./type-guards.js";
 const RUN_NOTE_SCHEMA = "humanish.run-note.v1";
 export const RUN_NOTES_DIR = "notes";
 /** The bytes one note file may hold: 2000 characters of text with JSON escapes, and its fields. */
 export const MAX_NOTE_FILE_BYTES = 16 * 1024;
-/** The notes one run keeps. A reader reads this many and names the rest. */
-export const MAX_RUN_NOTES = 500;
-export const MAX_NOTE_TEXT = 2000;
 /** The entries a reader lists in notes/ before it stops. */
 const MAX_LISTED_ENTRIES = 2 * MAX_RUN_NOTES;
-const NOTE_ID = /^note-\d{8}t\d{9}z-[0-9a-f]{12}$/;
-/** A temporary file of a write in progress, or of one a stopped writer left. Never a note. */
+/** A temporary file of the atomic writer, or one a 0.114.0 note writer left. Never a note. */
 const WRITE_IN_PROGRESS = /^\.humanish-write-/;
+const text = (max) => z.string().min(1).max(max);
+const timestamp = text(NOTE_FIELD_LIMITS.timestamp).refine((value) => Number.isFinite(Date.parse(value)));
+/** A note file. Fields a later release adds are dropped on reading, so they never hide a note. */
+const runNoteFileSchema = z.object({
+    schema: z.literal(RUN_NOTE_SCHEMA),
+    runId: z.string(),
+    id: z.string().regex(NOTE_ID),
+    atMs: z.int().min(0),
+    participant: text(NOTE_FIELD_LIMITS.participant).nullable(),
+    nearest: z
+        .object({
+        participant: text(NOTE_FIELD_LIMITS.participant),
+        itemId: text(NOTE_FIELD_LIMITS.itemId),
+    })
+        .nullable(),
+    text: text(MAX_NOTE_TEXT),
+    author: text(NOTE_FIELD_LIMITS.author),
+    createdAt: timestamp,
+    editedAt: timestamp.nullable(),
+});
 /** A new note id: `note-<creation time>-<48 random bits>`, such as `note-20261007t214500123z-…`. */
 export function newRunNoteId(createdAt) {
     const stamp = createdAt.toISOString().replace(/[-:.]/g, "").toLowerCase();
@@ -37,10 +54,8 @@ export function runNoteFile(id) {
 export function encodeRunNote(note, runId) {
     return `${JSON.stringify({ schema: RUN_NOTE_SCHEMA, runId, ...note }, null, 2)}\n`;
 }
-const text = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max;
-const timestamp = (value) => text(value, 64) && Number.isFinite(Date.parse(value));
 /** The note in a note file's bytes, when it is a note of `runId` stored under its own `id`. */
-export function decodeRunNote(bytes, runId, id) {
+function decodeRunNote(bytes, runId, id) {
     let value;
     try {
         value = JSON.parse(bytes.toString("utf8"));
@@ -48,42 +63,17 @@ export function decodeRunNote(bytes, runId, id) {
     catch {
         return null;
     }
-    if (!isRecord(value) ||
-        value.schema !== RUN_NOTE_SCHEMA ||
-        value.runId !== runId ||
-        value.id !== id ||
-        typeof value.atMs !== "number" ||
-        !Number.isSafeInteger(value.atMs) ||
-        value.atMs < 0 ||
-        !(value.participant === null || text(value.participant, 256)) ||
-        !(value.nearest === null ||
-            (isRecord(value.nearest) &&
-                text(value.nearest.participant, 256) &&
-                text(value.nearest.itemId, 256))) ||
-        !text(value.text, MAX_NOTE_TEXT) ||
-        !text(value.author, 80) ||
-        !timestamp(value.createdAt) ||
-        !(value.editedAt === null || timestamp(value.editedAt)))
+    const parsed = runNoteFileSchema.safeParse(value);
+    if (!parsed.success || parsed.data.runId !== runId || parsed.data.id !== id)
         return null;
-    const nearest = isRecord(value.nearest) ? value.nearest : null;
-    return {
-        id,
-        atMs: value.atMs,
-        participant: value.participant,
-        nearest: nearest === null
-            ? null
-            : { participant: String(nearest.participant), itemId: String(nearest.itemId) },
-        text: value.text,
-        author: value.author,
-        createdAt: value.createdAt,
-        editedAt: value.editedAt,
-    };
+    const { schema: _schema, runId: _runId, ...note } = parsed.data;
+    return note;
 }
 /**
  * Up to MAX_LISTED_ENTRIES names in the notes directory at `dir`, or null when there is none.
  * Throws when `dir` is there and is not a plain directory.
  */
-export async function listNoteEntries(dir) {
+async function listNoteEntries(dir) {
     try {
         const stats = await lstat(dir);
         if (!stats.isDirectory() || stats.isSymbolicLink())
@@ -109,7 +99,7 @@ export async function listNoteEntries(dir) {
     return { names, truncated: false };
 }
 /** The note ids to read from a listing of notes/, in creation order, and what was left out. */
-export function noteListing(listing) {
+function noteListing(listing) {
     const ids = [];
     const skipped = [];
     for (const name of listing.names) {
@@ -136,16 +126,32 @@ export async function countRunNotes(prepared) {
     const listing = await listNoteEntries(path.join(prepared.physicalRunRoot, RUN_NOTES_DIR));
     return listing === null ? 0 : noteListing(listing).ids.length + (listing.truncated ? 1 : 0);
 }
+/** The run's note files through the bounded reader, which rechecks the run directory on each read. */
+function boundedNoteFiles(prepared) {
+    return {
+        runId: runIdOf(prepared),
+        async directory() {
+            await validatePreparedRunRootIdentity(prepared);
+            return prepared.physicalRunRoot;
+        },
+        async read(relativePath, maxBytes) {
+            const read = await readBoundedFileResult(prepared, relativePath, maxBytes);
+            return read.state === "read" ? read.bytes : read.state === "limit" ? "limit" : null;
+        },
+    };
+}
 /**
- * The run's notes. Each file is read through the bounded reader, which refuses a link, a special
- * file or anything over MAX_NOTE_FILE_BYTES before reading past the limit; a file it refuses, or
- * that is not a note of this run, is skipped and named in `skipped`.
+ * The run's notes, read from its prepared paths through the bounded reader or through `from`, the
+ * files of a run the caller already holds (the served Observer passes its pinned root's). Each file
+ * is read within MAX_NOTE_FILE_BYTES; a file the reader refuses, or that is not a note of this run,
+ * is skipped and named in `skipped`.
  */
-export async function readRunNotes(prepared) {
-    const runId = runIdOf(prepared);
+export async function readRunNotes(from) {
+    const files = "physicalRunRoot" in from ? boundedNoteFiles(from) : from;
+    const { runId } = files;
     let listing;
     try {
-        listing = await listNoteEntries(path.join(prepared.physicalRunRoot, RUN_NOTES_DIR));
+        listing = await listNoteEntries(path.join(await files.directory(), RUN_NOTES_DIR));
     }
     catch {
         return {
@@ -159,12 +165,12 @@ export async function readRunNotes(prepared) {
     const { ids, skipped } = noteListing(listing);
     const notes = [];
     for (const id of ids) {
-        const read = await readBoundedFileResult(prepared, runNoteFile(id), MAX_NOTE_FILE_BYTES);
-        const note = read.state === "read" ? decodeRunNote(read.bytes, runId, id) : null;
+        const read = await files.read(runNoteFile(id), MAX_NOTE_FILE_BYTES);
+        const note = Buffer.isBuffer(read) ? decodeRunNote(read, runId, id) : null;
         if (note !== null)
             notes.push(note);
         else
-            skipped.push(read.state === "limit"
+            skipped.push(read === "limit"
                 ? `${runNoteFile(id)} is over ${MAX_NOTE_FILE_BYTES / 1024} KiB, so it was skipped.`
                 : `${runNoteFile(id)} is not a readable note of run ${runId}, so it was skipped.`);
     }
@@ -178,7 +184,29 @@ export async function readRunNotes(prepared) {
 export async function readNotesForSharing(prepared) {
     const notes = await readRunNotes(prepared);
     if (notes.notes.length === 0)
-        return { notes, finding: null };
+        return { notes, problem: null };
     const scan = scanEncodedTextCached(JSON.stringify(notes.notes));
-    return { notes, finding: scan.sensitive ? "sensitive" : scan.opaque ? "opaque" : null };
+    if (scan.sensitive)
+        return {
+            notes,
+            problem: {
+                status: "blocked",
+                reason: {
+                    code: "PUBLIC_SAFETY_FINDINGS",
+                    message: "The reviewer notes being shared match secret, token or local-path patterns.",
+                },
+            },
+        };
+    if (scan.opaque)
+        return {
+            notes,
+            problem: {
+                status: "local_only",
+                reason: {
+                    code: "UNSCANNED_ARTIFACT",
+                    message: "The reviewer notes being shared hold encoded text the scan cannot read.",
+                },
+            },
+        };
+    return { notes, problem: null };
 }

package/dist/run/note-shape.d.ts

@@ -0,0 +1,35 @@
+/** The characters a note's text may hold. */
+export declare const MAX_NOTE_TEXT = 2000;
+/** The notes one run keeps. A reader reads this many and names the rest. */
+export declare const MAX_RUN_NOTES = 500;
+/** The characters of a participant id, a trace item id or a timestamp a note records. */
+export declare const NOTE_FIELD_LIMITS: {
+    participant: number;
+    itemId: number;
+    author: number;
+    timestamp: number;
+};
+/** A note id: `note-<creation time>-<48 random bits in hex>`. */
+export declare const NOTE_ID: RegExp;
+/** Where an Observer page sends a note to the loopback server that rendered it. */
+export declare const NOTES_PATH = "/api/notes";
+/** The request header that carries the server's note token. */
+export declare const NOTES_TOKEN_HEADER = "x-humanish-notes-token";
+export interface RunNote {
+    id: string;
+    /** Milliseconds from the run clock's start. */
+    atMs: number;
+    /** The participant's stream id, or null for a note on the whole run. */
+    participant: string | null;
+    /** The latest timed capture or event at or before the moment, with its participant. */
+    nearest: {
+        participant: string;
+        itemId: string;
+    } | null;
+    text: string;
+    author: string;
+    createdAt: string;
+    editedAt: string | null;
+}
+/** Notes in run clock order, the earliest added first at the same moment. */
+export declare function byRunTime(notes: readonly RunNote[]): RunNote[];

package/dist/run/note-shape.js

@@ -0,0 +1,20 @@
+// A reviewer note as the server keeps it and the Observer shows it: its fields, their limits, and
+// where an Observer page sends a new one. The Observer bundles this module, so it has no runtime imports
+// (observer/tests/contract-lock.test.ts checks that); the server validates notes against these
+// limits with zod in note-files.ts and notes-route.ts.
+/** The characters a note's text may hold. */
+export const MAX_NOTE_TEXT = 2000;
+/** The notes one run keeps. A reader reads this many and names the rest. */
+export const MAX_RUN_NOTES = 500;
+/** The characters of a participant id, a trace item id or a timestamp a note records. */
+export const NOTE_FIELD_LIMITS = { participant: 256, itemId: 256, author: 80, timestamp: 64 };
+/** A note id: `note-<creation time>-<48 random bits in hex>`. */
+export const NOTE_ID = /^note-\d{8}t\d{9}z-[0-9a-f]{12}$/;
+/** Where an Observer page sends a note to the loopback server that rendered it. */
+export const NOTES_PATH = "/api/notes";
+/** The request header that carries the server's note token. */
+export const NOTES_TOKEN_HEADER = "x-humanish-notes-token";
+/** Notes in run clock order, the earliest added first at the same moment. */
+export function byRunTime(notes) {
+    return [...notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
+}

package/dist/run/notes.d.ts

@@ -1,7 +1,5 @@
-import type { RunBundle } from "./bundle.js";
-import { type RunNote } from "./note-files.js";
+import { type RunNote } from "./note-shape.js";
 import { type PreparedRunArtifactPaths } from "./paths.js";
-export { MAX_NOTE_TEXT, readNotesForSharing, readRunNotes, type RunNote, type RunNotes, } from "./note-files.js";
 export interface RunNoteInput {
     atMs: number;
     participant: string | null;
@@ -21,17 +19,8 @@ export type AddRunNoteResult =
         message: string;
     };
 };
-/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
-export declare function runParticipantCaptions(bundle: RunBundle): Map<string, 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, published 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.
+ * 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.
  */
 export declare function addRunNote(prepared: PreparedRunArtifactPaths, input: RunNoteInput): Promise<AddRunNoteResult>;

package/dist/run/notes.js

@@ -1,16 +1,17 @@
 // 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 { writeNewContainedOutputFile } from "./contained-output.js";
+import { createContainedOutputFile } from "./contained-output.js";
 import { loadRunBundlePrepared } from "./locate.js";
-import { countRunNotes, encodeRunNote, MAX_NOTE_TEXT, MAX_RUN_NOTES, newRunNoteId, runNoteFile, } from "./note-files.js";
-import { streamCaptions } from "./participant-caption.js";
-import { recordedPersonaId, streamParticipantIdOf } from "./participant-records.js";
+import { countRunNotes, encodeRunNote, newRunNoteId, runNoteFile } from "./note-files.js";
+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";
-export { MAX_NOTE_TEXT, readNotesForSharing, readRunNotes, } from "./note-files.js";
 const DEFAULT_AUTHOR = "you";
 /** New ids a note tries when the one before was taken. */
 const PUBLISH_ATTEMPTS = 5;
@@ -18,19 +19,6 @@ const refuse = (code, message) => ({
     ok: false,
     error: { code, message },
 });
-/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
-export function runParticipantCaptions(bundle) {
-    return streamCaptions(bundle.streams.map((stream) => {
-        const participantId = streamParticipantIdOf(stream);
-        const personaId = recordedPersonaId(bundle, stream);
-        return {
-            id: stream.id,
-            label: stream.label,
-            ...(participantId === undefined ? {} : { participantId }),
-            ...(personaId === undefined ? {} : { personaId }),
-        };
-    }));
-}
 /**
  * The stream id a note's participant names: a stream id, or the participant's own id from the study
  * (`charge-nurse`). Both kinds of id are matched, so a name that is one stream's id and another
@@ -51,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 };
         }
@@ -136,20 +77,27 @@ function noteTextProblem(text) {
     return null;
 }
 /**
- * Adds a note as a new file, notes/<id>.json, published 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.
+ * 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.
  */
 export async function addRunNote(prepared, input) {
     const text = scrubNoteText(input.text);
     const problem = noteTextProblem(text);
     if (problem)
         return refuse("HUMANISH_NOTE_INVALID", problem);
-    // Containment checks throw on a link or special file anywhere in the run directory.
-    const loaded = await loadRunBundlePrepared(physicalCwdOf(prepared), prepared).catch(() => null);
+    let loaded;
+    try {
+        loaded = await loadRunBundlePrepared(physicalCwdOf(prepared), prepared);
+    }
+    catch (error) {
+        // The storage check throws on a link or a special file anywhere in the run directory, or on a
+        // run directory that moved.
+        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `No note was added to run ${runIdOf(prepared)}: its directory failed humanish's storage check. ${error instanceof Error ? error.message : String(error)} Fix that in the run directory and add the note again.`);
+    }
     if (!loaded)
-        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `Run ${runIdOf(prepared)} has no run.json humanish can read safely, so no note was added. \`humanish verify --run ${runIdOf(prepared)}\` says what is wrong with it.`);
+        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);
@@ -181,7 +129,7 @@ export async function addRunNote(prepared, input) {
         for (let attempt = 0; attempt < PUBLISH_ATTEMPTS; attempt += 1) {
             const note = { id: newRunNoteId(now), ...fields };
             try {
-                await writeNewContainedOutputFile(prepared, runNoteFile(note.id), encodeRunNote(note, bundle.runId));
+                await createContainedOutputFile(prepared, runNoteFile(note.id), encodeRunNote(note, bundle.runId));
             }
             catch (error) {
                 if (isNodeError(error) && error.code === "EEXIST")

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/participant-records.d.ts

@@ -28,3 +28,5 @@ export declare function eventRecordIdOf(event: RunEvent): string | undefined;
 export declare function streamParticipantIdOf(stream: Pick<RunStream, "laneId">): string | undefined;
 /** The persona recorded for a stream, including dry runs without an actor trace. */
 export declare function recordedPersonaId(bundle: Partial<Pick<RunBundle, "simulations">>, stream: Partial<Pick<RunStream, "simId">>): string | undefined;
+/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
+export declare function runParticipantCaptions(bundle: Pick<RunBundle, "streams" | "simulations">): Map<string, string>;

package/dist/run/participant-records.js

@@ -1,7 +1,9 @@
 // The run bundle's participant records, written and read. A route describes each participant (its
 // record and stream fields, its events) and these functions give them the bundle's saved shape and
-// field names; readers ask them for the ids a saved record carries. This module and run/bundle.ts
-// (its types and bundleHead) and run/streams.ts are where those contract spellings live.
+// field names; readers ask them for the ids a saved record carries and the caption it shows. This
+// module and run/bundle.ts (its types and bundleHead) and run/streams.ts are where those contract
+// spellings live.
+import { streamCaptions } from "./participant-caption.js";
 /** Ids a route chose itself, for routes whose ids are not the `sim-NNN` default. */
 export function participantIdsOf(recordId, streamId) {
     return { recordId, streamId };
@@ -67,3 +69,16 @@ export function recordedPersonaId(bundle, stream) {
         return undefined;
     return bundle.simulations.find((record) => record?.id === stream.simId)?.personaId;
 }
+/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
+export function runParticipantCaptions(bundle) {
+    return streamCaptions(bundle.streams.map((stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        const personaId = recordedPersonaId(bundle, stream);
+        return {
+            id: stream.id,
+            label: stream.label,
+            ...(participantId === undefined ? {} : { participantId }),
+            ...(personaId === undefined ? {} : { personaId }),
+        };
+    }));
+}

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()}`;