humanish 0.113.0 → 0.114.0

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

@@ -38,6 +38,13 @@ export declare function prepareContainedOutputDirectory(rootInput: PreparedOutpu
 export declare function prepareContainedOutputDirectoryRoot(rootInput: PreparedOutputRoot, relativePath: string): Promise<PreparedSelectedOutputDirectory>;
 export declare function prepareContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<string>;
 export declare function writeContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string | Uint8Array, encoding?: BufferEncoding): Promise<void>;
+/**
+ * Writes a new file inside the root without ever replacing one: the bytes go to a temporary file,
+ * which link(2) then gives the final name, failing with EEXIST when that name exists, and the
+ * temporary name is removed. writeContainedOutputFile renames instead, which replaces a file that
+ * took the name in the meantime.
+ */
+export declare function writeNewContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
 /** Read one regular file only when both lexical and physical paths stay in root. */
 export declare function readContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<Buffer | null>;
 /**

package/dist/run/contained-output.js

@@ -1,5 +1,5 @@
 import { constants } from "node:fs";
-import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { link, lstat, mkdir, open, realpath, rename, unlink, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { assertDirectoryIdentity, assertRegularFileOrMissing, isPathInside, prepareHumanishStorageDirectory, resolveExistingHumanishStorageDirectory, validatePreparedRunArtifactPaths, validatePreparedRunRootIdentity, } from "./paths.js";
@@ -123,6 +123,40 @@ export async function writeContainedOutputFile(rootInput, relativePath, data, en
         await assertRegularFileOrMissing(filePath, "Selected output files");
     });
 }
+/**
+ * Writes a new file inside the root without ever replacing one: the bytes go to a temporary file,
+ * which link(2) then gives the final name, failing with EEXIST when that name exists, and the
+ * temporary name is removed. writeContainedOutputFile renames instead, which replaces a file that
+ * took the name in the meantime.
+ */
+export async function writeNewContainedOutputFile(rootInput, relativePath, data) {
+    const filePath = await prepareContainedOutputFile(rootInput, relativePath);
+    const root = await resolveOutputRoot(rootInput);
+    const parent = path.dirname(filePath);
+    const revalidate = async () => {
+        if ((await resolveOutputRoot(rootInput)) !== root) {
+            throw new Error("Output root changed after it was prepared.");
+        }
+        await assertContainedDirectoryChain(root, parent);
+    };
+    await revalidate();
+    const temporary = path.join(parent, `.humanish-write-${process.pid}-${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(data, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await revalidate();
+        await link(temporary, filePath);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+    }
+    await assertRegularFileOrMissing(filePath, "Selected output files");
+}
 /** Read one regular file only when both lexical and physical paths stay in root. */
 export async function readContainedRegularFile(rootInput, relativePath) {
     const handle = await openContainedRegularFile(rootInput, relativePath);

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

@@ -0,0 +1,73 @@
+import { type PreparedRunArtifactPaths } from "./paths.js";
+export declare const RUN_NOTES_DIR = "notes";
+/** The bytes one note file may hold: 2000 characters of text with JSON escapes, and its fields. */
+export declare const MAX_NOTE_FILE_BYTES: number;
+/** The notes one run keeps. A reader reads this many and names the rest. */
+export declare const MAX_RUN_NOTES = 500;
+export declare const MAX_NOTE_TEXT = 2000;
+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;
+}
+/** A run's notes as read, in the order they were added, and why any file was skipped. */
+export interface RunNotes {
+    runId: string;
+    notes: RunNote[];
+    skipped: string[];
+}
+/** A new note id: `note-<creation time>-<48 random bits>`, such as `note-20261007t214500123z-…`. */
+export declare function newRunNoteId(createdAt: Date): string;
+/** The note's file, relative to the run directory. */
+export declare function runNoteFile(id: string): string;
+/** The note as its file holds it. */
+export declare function encodeRunNote(note: RunNote, runId: string): string;
+/** The note in a note file's bytes, when it is a note of `runId` stored under its own `id`. */
+export declare function decodeRunNote(bytes: Buffer, runId: string, id: string): RunNote | null;
+/**
+ * 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 declare function listNoteEntries(dir: string): Promise<{
+    names: string[];
+    truncated: boolean;
+} | null>;
+/** The note ids to read from a listing of notes/, in creation order, and what was left out. */
+export declare function noteListing(listing: {
+    names: readonly string[];
+    truncated: boolean;
+}): {
+    ids: string[];
+    skipped: string[];
+};
+/** How many note files notes/ lists, without reading any. Throws when notes/ is unusable. */
+export declare function countRunNotes(prepared: PreparedRunArtifactPaths): Promise<number>;
+/**
+ * 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`.
+ */
+export declare function readRunNotes(prepared: PreparedRunArtifactPaths): Promise<RunNotes>;
+/** What verify's text scan finds in shared notes: a secret-shaped value, or text it cannot read. */
+type NotesFinding = "sensitive" | "opaque";
+/**
+ * The run's notes as a caller is about to share them, read once, with what verify's text scan
+ * finds in that set as it would be shared. The caller shares this set only, so a note added or
+ * changed after verify ran cannot go out unchecked.
+ */
+export declare function readNotesForSharing(prepared: PreparedRunArtifactPaths): Promise<{
+    notes: RunNotes;
+    finding: NotesFinding | null;
+}>;
+export {};

package/dist/run/note-files.js

@@ -0,0 +1,184 @@
+// 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.
+import { randomBytes } from "node:crypto";
+import { lstat, opendir } from "node:fs/promises";
+import path from "node:path";
+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";
+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. */
+const WRITE_IN_PROGRESS = /^\.humanish-write-/;
+/** 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();
+    return `note-${stamp}-${randomBytes(6).toString("hex")}`;
+}
+/** The note's file, relative to the run directory. */
+export function runNoteFile(id) {
+    return `${RUN_NOTES_DIR}/${id}.json`;
+}
+/** The note as its file holds it. */
+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) {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString("utf8"));
+    }
+    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)))
+        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,
+    };
+}
+/**
+ * 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) {
+    try {
+        const stats = await lstat(dir);
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            throw new Error("The notes entry is not a directory.");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const names = [];
+    const listing = await opendir(dir);
+    try {
+        for await (const entry of listing) {
+            if (names.length === MAX_LISTED_ENTRIES)
+                return { names, truncated: true };
+            names.push(entry.name);
+        }
+    }
+    finally {
+        await listing.close().catch(() => undefined);
+    }
+    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) {
+    const ids = [];
+    const skipped = [];
+    for (const name of listing.names) {
+        if (WRITE_IN_PROGRESS.test(name))
+            continue;
+        const id = name.endsWith(".json") ? name.slice(0, -".json".length) : "";
+        if (NOTE_ID.test(id))
+            ids.push(id);
+        else
+            skipped.push(`${RUN_NOTES_DIR}/${name} is not a note file, so it was skipped.`);
+    }
+    ids.sort();
+    if (listing.truncated)
+        skipped.push(`${RUN_NOTES_DIR}/ holds more than ${MAX_LISTED_ENTRIES} entries; only the first ${MAX_LISTED_ENTRIES} were listed.`);
+    if (ids.length > MAX_RUN_NOTES) {
+        const left = ids.length - MAX_RUN_NOTES;
+        skipped.push(`${left} note${left === 1 ? "" : "s"} after the first ${MAX_RUN_NOTES} ${left === 1 ? "was" : "were"} not read.`);
+        ids.length = MAX_RUN_NOTES;
+    }
+    return { ids, skipped };
+}
+/** How many note files notes/ lists, without reading any. Throws when notes/ is unusable. */
+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 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`.
+ */
+export async function readRunNotes(prepared) {
+    const runId = runIdOf(prepared);
+    let listing;
+    try {
+        listing = await listNoteEntries(path.join(prepared.physicalRunRoot, RUN_NOTES_DIR));
+    }
+    catch {
+        return {
+            runId,
+            notes: [],
+            skipped: [`${RUN_NOTES_DIR} in run ${runId} is not a plain folder, so no notes were read.`],
+        };
+    }
+    if (listing === null)
+        return { runId, notes: [], skipped: [] };
+    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;
+        if (note !== null)
+            notes.push(note);
+        else
+            skipped.push(read.state === "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.`);
+    }
+    return { runId, notes, skipped };
+}
+/**
+ * The run's notes as a caller is about to share them, read once, with what verify's text scan
+ * finds in that set as it would be shared. The caller shares this set only, so a note added or
+ * changed after verify ran cannot go out unchecked.
+ */
+export async function readNotesForSharing(prepared) {
+    const notes = await readRunNotes(prepared);
+    if (notes.notes.length === 0)
+        return { notes, finding: null };
+    const scan = scanEncodedTextCached(JSON.stringify(notes.notes));
+    return { notes, finding: scan.sensitive ? "sensitive" : scan.opaque ? "opaque" : null };
+}

package/dist/run/notes.d.ts

@@ -0,0 +1,37 @@
+import type { RunBundle } from "./bundle.js";
+import { type RunNote } from "./note-files.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;
+    text: string;
+}
+export type RunNoteErrorCode = "HUMANISH_INVALID_RUN_BUNDLE" | "HUMANISH_NOTE_INVALID" | "HUMANISH_NOTE_NO_CLOCK" | "HUMANISH_NOTE_UNKNOWN_PARTICIPANT" | "HUMANISH_NOTE_OUTSIDE_RUN" | "HUMANISH_NOTES_UNREADABLE" | "HUMANISH_NOTES_FULL" | "HUMANISH_NOTE_ID_TAKEN";
+export type AddRunNoteResult = 
+/** `scrubbed`: redaction replaced part of the text before it was written. */
+{
+    ok: true;
+    note: RunNote;
+    scrubbed: boolean;
+} | {
+    ok: false;
+    error: {
+        code: RunNoteErrorCode;
+        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.
+ */
+export declare function addRunNote(prepared: PreparedRunArtifactPaths, input: RunNoteInput): Promise<AddRunNoteResult>;

package/dist/run/notes.js

@@ -0,0 +1,198 @@
+// 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.
+import { redactText } from "../evidence/redaction.js";
+import { writeNewContainedOutputFile } 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 { physicalCwdOf, runIdOf } from "./paths.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;
+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
+ * stream's study id is refused, naming both, as is a study id that two streams record. Otherwise
+ * the refusal names the run's participants by caption, with the id to type for each.
+ */
+function participantStreamId(bundle, named) {
+    const captions = runParticipantCaptions(bundle);
+    const matching = bundle.streams.filter((stream) => stream.id === named || streamParticipantIdOf(stream) === named);
+    if (matching.length === 1)
+        return matching[0].id;
+    const described = (stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        return `${captions.get(stream.id)} (stream id ${stream.id}${participantId === undefined ? "" : `, study id ${participantId}`})`;
+    };
+    if (matching.length > 1)
+        return refuse("HUMANISH_NOTE_UNKNOWN_PARTICIPANT", `${named} names ${matching.length} participants in run ${bundle.runId}: ${matching.map(described).join(" and ")}. Name the one you mean by an id only it has.`);
+    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);
+            if (Number.isFinite(time) && time <= moment && (best === null || time >= best.time))
+                best = { participant: stream.id, itemId: item.id, time };
+        }
+    return best === null ? null : { participant: best.participant, itemId: best.itemId };
+}
+/**
+ * The text as it is written: line breaks as `\n`, the run's known values and every secret-shaped
+ * value or local path replaced, as other run text is before it is written.
+ */
+function scrubNoteText(text) {
+    let known;
+    try {
+        known = transientCommsKnownValueScrub()(text);
+    }
+    catch {
+        // A closed run scope refuses to scrub and has dropped its values. The note then gets the
+        // pattern redaction that a separate `humanish notes` process gives it.
+        known = text;
+    }
+    return redactText(known.replace(/\r\n?/g, "\n").trim());
+}
+/** Why the text cannot be a note, or null when it can. */
+function noteTextProblem(text) {
+    if (text.length === 0)
+        return "A note needs some text.";
+    if (text.length > MAX_NOTE_TEXT)
+        return `A note holds at most ${MAX_NOTE_TEXT} characters; this one has ${text.length}. Shorten it and add it again.`;
+    if (/[\u0000-\u0008\u000b-\u001f\u007f]/.test(text))
+        return "A note holds plain text and line breaks; this one has a control character. Remove it and add the note again.";
+    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.
+ */
+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);
+    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.`);
+    const { bundle } = loaded;
+    const clock = runClock(bundle);
+    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);
+    if (participant !== null && typeof participant !== "string")
+        return participant;
+    // The Observer shows whole seconds, so a moment in the second the clock ends is its end.
+    const durationMs = clock.endMs - clock.startMs;
+    if (!Number.isFinite(input.atMs) ||
+        input.atMs < 0 ||
+        Math.floor(input.atMs / 1000) > Math.floor(durationMs / 1000))
+        return refuse("HUMANISH_NOTE_OUTSIDE_RUN", `A note on run ${bundle.runId} needs a moment from 00:00 to ${formatRunTime(durationMs)}, the time its captures cover.`);
+    const atMs = Math.min(Math.round(input.atMs), durationMs);
+    const streams = bundle.streams.filter((stream) => participant === null || stream.id === participant);
+    const now = new Date();
+    const fields = {
+        atMs,
+        participant,
+        nearest: nearestItem(streams, clock.startMs + atMs),
+        text,
+        author: DEFAULT_AUTHOR,
+        createdAt: now.toISOString(),
+        editedAt: null,
+    };
+    try {
+        // A count of the files notes/ lists; no note is read.
+        if ((await countRunNotes(prepared)) >= MAX_RUN_NOTES)
+            return refuse("HUMANISH_NOTES_FULL", `Run ${bundle.runId} already has ${MAX_RUN_NOTES} notes, the most one run keeps.`);
+        // The note appears only under a name nothing holds; a taken name gets a new id.
+        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));
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === "EEXIST")
+                    continue;
+                throw error;
+            }
+            return { ok: true, note, scrubbed: text !== input.text.replace(/\r\n?/g, "\n").trim() };
+        }
+    }
+    catch {
+        return refuse("HUMANISH_NOTES_UNREADABLE", `The notes folder in run ${bundle.runId} is not a plain folder inside the run, so no note was added. Move it out of the run directory and add the note again.`);
+    }
+    return refuse("HUMANISH_NOTE_ID_TAKEN", `Each new id humanish chose for the note was already taken in run ${bundle.runId}'s notes folder, so no note was added. Something else is writing files there; add the note again.`);
+}

package/dist/run/participant-caption.d.ts

@@ -29,3 +29,12 @@ export interface SavedCaptionFacts {
  * recorded persona; a scripted mobile surface also identifies a phone.
  */
 export declare function savedCaption(stream: SavedCaptionFacts): string;
+/** A saved stream, as much of it as `streamCaptions` reads. */
+export interface CaptionedStream extends SavedCaptionFacts {
+    readonly id: string;
+}
+/**
+ * Each stream's caption, by stream id, as the Observer shows it: the saved caption, with the
+ * participant id or the stream id added where two streams would read the same.
+ */
+export declare function streamCaptions(streams: readonly CaptionedStream[]): Map<string, string>;

package/dist/run/participant-caption.js

@@ -58,3 +58,22 @@ export function savedCaption(stream) {
     }
     return label;
 }
+/**
+ * Each stream's caption, by stream id, as the Observer shows it: the saved caption, with the
+ * participant id or the stream id added where two streams would read the same.
+ */
+export function streamCaptions(streams) {
+    const repeated = (labels) => new Set(labels.filter((label, index) => labels.indexOf(label) !== index));
+    const saved = streams.map(savedCaption);
+    const savedTwice = repeated(saved);
+    const qualified = streams.map((stream, index) => savedTwice.has(saved[index])
+        ? `${saved[index]} · ${stream.participantId ?? stream.id}`
+        : saved[index]);
+    const qualifiedTwice = repeated(qualified);
+    return new Map(streams.map((stream, index) => [
+        stream.id,
+        qualifiedTwice.has(qualified[index])
+            ? `${qualified[index]} · ${stream.id}`
+            : qualified[index],
+    ]));
+}

package/dist/study/doctor.js

@@ -368,7 +368,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         ok: true,
         ...(keyed ? {} : { status: "note" }),
         message: keyed
-            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its estimate is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its expected cost plus a 10% margin is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
             : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
     };
 }

package/dist/study/preflight-result.js

@@ -2,11 +2,12 @@
 // preflight-probes.ts both finish through these, so they live below both.
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { digestText } from "../evidence/redaction.js";
+import { computerUseParticipantCount } from "./routing.js";
 /** The schema of `study check` results: whether a study is ready to run on this machine. */
 export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
     const checks = [...ctx.checks, ...(args?.check ? [args.check] : []), ...(args?.checks ?? [])];
-    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route);
+    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route, computerUseParticipantCount(ctx.config));
     return {
         schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),

package/dist/study/summary.js

@@ -15,7 +15,7 @@ import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
 import { inspectStudyManifest } from "./discover.js";
-import { isComputerUseComposition } from "./routing.js";
+import { computerUseParticipantCount, isComputerUseComposition } from "./routing.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { receivingRequiredKey } from "../comms/setup.js";
 import { participantList, declaredParticipantCount } from "./study-fields.js";
@@ -127,7 +127,7 @@ export async function readStudySummary(cwd, study, options = {}) {
             missingKeys = missing;
     }
     // Computed once: a test-then-use pair reads as though the two calls could differ.
-    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route);
+    const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
     const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)

package/docs/contracts/errors.md

@@ -46,8 +46,8 @@ Counts are the distinct quoted codes in `src/` on 2026-10-03.
 The lowercase families are values recorded inside artifacts and receipts, and an artifact keeps
 the code it was written with. Automatic analysis reads two of them back:
 `analysis_admission_estimate_exceeded` becomes the reason `AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED`,
-and `analysis_budget_exceeded` on a default analysis prints the hint to rerun with
-`humanish analyze --max-cost`. Validation also accepts a partial artifact whose error is
+and `analysis_budget_exceeded` records the expected cost, the worst case and the cap on the job,
+and prints them with the command that reruns it, `humanish analyze --run <id> --max-cost <n>`. Validation also accepts a partial artifact whose error is
 `analysis_admission_estimate_exceeded`.
 
 Share-safety reasons in `humanish verify` (`VERIFY_FAILED`, `RAW_SCREENSHOTS` and the rest) are