humanish 0.112.0 → 0.114.0

package/dist/routes/computer-use/local-vm.js

@@ -3,8 +3,9 @@ import path from "node:path";
 import { inboxRecipientFor, } from "./participant-desktop.js";
 import { createLocalFirecrackerDesktop, } from "../../substrates/local/firecracker-desktop.js";
 import { localBrowserDefaults, localBrowserUnsupportedReason, } from "../../substrates/local/runtime-config.js";
-import { prepareLocalRuntime } from "../../substrates/local/runtime.js";
-import { dockerCommandLine } from "../../substrates/local/runtime-host.js";
+import { localRuntimeCapacity, prepareLocalRuntime } from "../../substrates/local/runtime.js";
+import { dockerCommandLine, usesLima } from "../../substrates/local/runtime-host.js";
+import { outOfMemoryMessage } from "../../substrates/local/capacity.js";
 import { checkRestrictedCodexAnalysisReadiness } from "../../analysis/restricted-codex.js";
 import { createRestrictedCodexParticipant } from "../../actors/codex/restricted-participant.js";
 import { withCloseReport } from "./participant-model.js";
@@ -110,6 +111,11 @@ function createLocalParticipantDesktop(context, run, warnings, artifactRoot) {
                         warnings.push("Desktop video/audio recording could not be retained. Screenshots and participant evidence remain available.");
                     }
                 }
+                // Asked before close, which removes the container; the answer comes from Docker's events.
+                if ((await session.killedForMemory?.()) === true) {
+                    evidence.failureCode = "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY";
+                    evidence.desktopFailure = outOfMemoryMessage(usesLima() ? "lima-vm" : "linux-host");
+                }
                 try {
                     evidence.released = (await session.close()).status === "released";
                 }
@@ -180,6 +186,7 @@ export function prepareLocalVmRun(options) {
         options: account ? { ...runOptions, createProvider: accountProvider(state) } : runOptions,
         localVm: {
             desktop: (run, warnings, artifactRoot) => createLocalParticipantDesktop(context, run, warnings, artifactRoot),
+            capacity: () => localRuntimeCapacity(),
             analysisRefusal: () => state.cleanupUnconfirmed ? "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED" : undefined,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         },

package/dist/routes/computer-use/participant-desktop.d.ts

@@ -16,6 +16,12 @@ export type ParticipantDesktopEvidence = {
     /** The substrate confirmed the desktop was released (an E2B kill or a local VM shutdown). The participant
      *  outcome records it as `killed`. */
     released: boolean;
+    /**
+     * Why the desktop itself ended the session, in words a person reads, when the substrate knows:
+     * a local desktop Docker killed for memory. It replaces the session's error for a participant
+     * who did not pass.
+     */
+    desktopFailure?: string;
 } & Pick<ParticipantRunOutcome, "sandboxId" | "sandboxRelease" | "desktopDurationMs" | "desktopResources" | "streamUrlPresent" | "subjectCommit" | "desktopBrowser" | "desktopGeometry" | "stateStepRecords" | "phaseRecords" | "failureCode" | "commsArtifactPath" | "recording">;
 /**
  * The desktop one participant runs on, owned from preparation through final evidence collection.

package/dist/routes/computer-use/participant-execution.js

@@ -107,6 +107,15 @@ export async function runCuaParticipant(spec, deps) {
             });
         }
     }
+    const { released, desktopFailure, ...desktopEvidence } = desktop.snapshot();
+    // A desktop that died under the participant explains the failure better than the transport
+    // error the session saw. A session that passed keeps its result.
+    if (desktopFailure !== undefined) {
+        if (session?.status === "passed")
+            warnings.push(desktopFailure);
+        else
+            sessionError = desktopFailure;
+    }
     if (session)
         await recordParticipantTrace(spec, deps, session, warnings);
     const { noEngagement, selfReportedBlocker, reportedFriction } = judgeParticipantSession(session, deps, warnings);
@@ -116,7 +125,6 @@ export async function runCuaParticipant(spec, deps) {
         providerCleanupError !== undefined ||
         providerPolicyError !== undefined ||
         session?.completionReason === "harness_error";
-    const { released, ...desktopEvidence } = desktop.snapshot();
     return {
         spec,
         ...(session ? { session } : {}),

package/dist/routes/computer-use/rerun-selection.js

@@ -4,42 +4,44 @@ import {} from "../../run/bundle.js";
 import { loadRunBundle } from "../../run/locate.js";
 import {} from "../../run/streams.js";
 import { plural } from "../../run/text.js";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { cli } from "../../cli/invocation.js";
 export async function resolveCuaRerunSelection(args) {
-    const source = await loadRunBundle(args.cwd, args.sourceRunId);
+    const { studyId, sourceRunId } = args;
+    // Every refusal ends with the command that runs the whole study, which is what a user who
+    // reached for a rerun too early wants.
+    const instead = `To run every participant of ${studyId} instead, leave out --rerun-failed-from: ${cli(`watch ${studyId}`)} or ${cli(`run ${studyId}`)}.`;
+    const refuse = (what) => ({ ok: false, message: `${what} ${instead}` });
+    const source = await loadRunBundle(args.cwd, sourceRunId);
     if (!source) {
-        return { ok: false, message: `source run not found or invalid: ${args.sourceRunId}` };
+        const noRuns = sourceRunId === "latest" &&
+            !(await access(path.join(args.cwd, ".humanish", "runs", "latest.json")).then(() => true, () => false));
+        return refuse(noRuns
+            ? "--rerun-failed-from latest found no run: this project has no runs yet, and a rerun repeats the failed participants of an earlier live run."
+            : `--rerun-failed-from ${sourceRunId} names no run humanish can read in this project. ${cli("runs")} lists its runs.`);
     }
     const bundle = source.bundle;
+    const run = `Run ${bundle.runId}${sourceRunId === bundle.runId ? "" : ` (the ${sourceRunId} run)`}`;
+    const notFanout = `${run} is not a live computer-use run with more than one participant, so it has no participants to rerun.`;
     if (bundle.mode !== "live") {
-        return {
-            ok: false,
-            message: `source run ${bundle.runId} is ${bundle.mode}; rerun selection only applies to live CUA fan-out evidence.`,
-        };
+        return refuse(`${run} is a dry run: no participant ran in it, so none can be rerun. A rerun repeats the failed participants of a live run with more than one participant.`);
     }
     const fanoutEvent = bundle.events.some((event) => event.type === "cua-lab.fanout.plan");
-    if (!fanoutEvent || bundle.streams.length < 2) {
-        return { ok: false, message: `source run ${bundle.runId} is not a CUA fan-out run.` };
-    }
+    if (!fanoutEvent || bundle.streams.length < 2)
+        return refuse(notFanout);
     const prior = bundle.streams
         .map(snapshotPriorParticipant)
         .filter((entry) => entry !== null);
     const priorById = new Map(prior.map((entry) => [entry.participantId, entry]));
-    if (priorById.size < 2) {
-        return {
-            ok: false,
-            message: `source run ${bundle.runId} does not expose multiple participant ids.`,
-        };
-    }
+    if (priorById.size < 2)
+        return refuse(notFanout);
     const explicitIds = uniqueIds(args.participantIds ?? []);
     const selectedIds = explicitIds.length > 0
         ? explicitIds
         : prior.filter((entry) => entry.rerunnable).map((entry) => entry.participantId);
-    if (selectedIds.length === 0) {
-        return {
-            ok: false,
-            message: `source run ${bundle.runId} has no participant to rerun: none failed, was blocked, timed out or ended without engaging.`,
-        };
-    }
+    if (selectedIds.length === 0)
+        return refuse(`${run} has no participant to rerun: none failed, was blocked, timed out or ended without engaging.`);
     const missingPrior = selectedIds.filter((id) => !priorById.has(id));
     if (missingPrior.length > 0) {
         return {

package/dist/routes/computer-use/result.js

@@ -98,8 +98,9 @@ function cuaStudyResult(args) {
             };
         }
         const failing = (outcomes ?? []).find((outcome) => !participantOk(outcome));
-        const geometryFailure = (outcomes ?? []).find((outcome) => outcome.failureCode === "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY");
-        const code = geometryFailure?.failureCode ?? "HUMANISH_COMPUTER_USE_FAILED";
+        // A participant whose desktop failed for a known cause gives the run that cause's code.
+        const codedFailure = (outcomes ?? []).find((outcome) => outcome.failureCode !== undefined);
+        const code = codedFailure?.failureCode ?? "HUMANISH_COMPUTER_USE_FAILED";
         return {
             code,
             message: observer.ok

package/dist/routes/computer-use/self-report.js

@@ -200,8 +200,14 @@ export function resolveSelfReportedFriction(session) {
     // reached the goal and described what was hard on the way has reported friction.
     if (session.trace.declaredOutcome === "blocked")
         return session.reason;
+    // Impressions are opinions about the product, not reports of what went wrong in the session.
+    const impressions = new Set(session.trace.impressions?.status === "collected"
+        ? session.trace.impressions.items.map((item) => item.messageId)
+        : []);
     const messages = session.trace.items
-        .filter((item) => item.kind === "message" && item.id !== session.trace.debrief?.messageId)
+        .filter((item) => item.kind === "message" &&
+        item.id !== session.trace.debrief?.messageId &&
+        !impressions.has(item.id))
         .map((item) => item.text?.trim() ?? "")
         .filter((text) => text.length > 0);
     // A custom session may keep its closing report only in reason even when earlier messages exist.

package/dist/routes/computer-use/setup.js

@@ -22,6 +22,7 @@ import {} from "./bundle.js";
 import { packRunLocalTree } from "./local-tree-pack.js";
 import { projectParticipantSubjects, subjectProvenanceArg } from "./subject-projection.js";
 import { participantSubjectEnv, } from "./types.js";
+import { capacityShortfall } from "../../substrates/local/capacity.js";
 import { studyPersonaIds } from "../../study/persona-resolve.js";
 import { refusedResult } from "../../run/study-result.js";
 /** The physical project, bound before any caller hook runs. */
@@ -145,6 +146,11 @@ export async function admitCuaRun(plan, input, config) {
         });
         if (rejection)
             return refuse(rejection.code, rejection.message, descriptor.id);
+        const shortfall = await localCapacityShortfall(input.localVm, participantPlan.concurrency);
+        if (shortfall !== undefined && "refusal" in shortfall)
+            return refuse("HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED", shortfall.refusal, descriptor.id);
+        if (shortfall !== undefined)
+            process.stderr.write(`warning: ${shortfall.warning}\n`);
     }
     // Pack the working tree once per run, on the host, before any sandbox or provider call: every
     // fan-out participant below uploads this same archive, so one archiveSha256 describes every
@@ -192,6 +198,14 @@ export async function admitCuaRun(plan, input, config) {
         },
     };
 }
+/**
+ * Whether a local study's desktops at once fit the local runtime. Read before any desktop: a
+ * desktop past the VM's memory is killed mid-session, after its participant has spent.
+ */
+async function localCapacityShortfall(localVm, desktops) {
+    const capacity = await localVm?.capacity?.();
+    return capacity === undefined ? undefined : capacityShortfall(capacity, desktops);
+}
 /** Starts the run and builds what the participants and the finish read: the deps and the bundle base. */
 export async function startCuaRun(plan, input, admitted, scope) {
     const { cwd, descriptor, participantRuns, participantPlan, publicRepo } = admitted;

package/dist/routes/computer-use/types.d.ts

@@ -1,4 +1,5 @@
 import type { Verdict } from "../../run/judge.js";
+import type { LocalCapacity } from "../../substrates/local/capacity.js";
 import type { RunDesktopRecording } from "../../evidence/desktop-recording-types.js";
 import type { CuaExecutor, CuaLiveMetadata, CuaLoopResult, CuaProvider } from "../../actors/computer-use/loop.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
@@ -38,6 +39,8 @@ export declare const MIN_DERIVED_SESSION_TIMEOUT_MS: number;
  */
 export interface LocalVmInput {
     readonly desktop: ParticipantDesktopFactory;
+    /** How many desktops the local runtime holds, or undefined when it cannot be read. */
+    readonly capacity?: () => Promise<LocalCapacity | undefined>;
     /** The skip reason automatic analysis records instead of running, or undefined to run it. */
     readonly analysisRefusal: () => AutomaticAnalysisRefusal | undefined;
     readonly signal?: AbortSignal;
@@ -182,7 +185,7 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED" | "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
 /** Subject provenance projection: what the actor actually drove. */
 export interface CuaSubjectProjection {
     source: "app-url" | "clone" | "local-tree";

package/dist/routes/shared-world/bundle-records.js

@@ -81,16 +81,17 @@ function sharedWorldStream(ctx, spec, index, view) {
     const { args } = ctx;
     const { name, session, screenshots, lastScreenshot, desktopGeometry, screenshotMode } = view;
     const judged = view.judgment.judgedStatus;
+    const caption = participantCaption({
+        id: spec.planned.id,
+        personaId: spec.persona.id,
+        device: spec.planned.device,
+    });
     return participantStream(spec, {
         ...(spec.evidenceAssignment === undefined
             ? {}
             : { assignment: participantAssignment(spec.evidenceAssignment) }),
         kind: "browser",
-        label: participantCaption({
-            id: spec.planned.id,
-            personaId: spec.persona.id,
-            device: spec.planned.device,
-        }),
+        label: caption,
         status: view.status,
         ...(judged === undefined ? {} : { judgedStatus: judged }),
         transport: "snapshot",
@@ -99,9 +100,9 @@ function sharedWorldStream(ctx, spec, index, view) {
             ? {
                 kind: "screenshot",
                 url: lastScreenshot,
-                title: `Shared plane, persona ${spec.planned.id} (${screenshotMode})`,
+                title: `${caption} (${screenshotMode})`,
             }
-            : { kind: "placeholder", title: `Shared plane, persona ${spec.planned.id}` },
+            : { kind: "placeholder", title: caption },
         ...(desktopGeometry.viewport === undefined
             ? {}
             : {

package/dist/routes/shared-world/bundle.js

@@ -252,7 +252,7 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
     const overlaps = args.judgment.world.overlap;
     const deltas = (stateSeries ?? []).filter((snapshot, i) => i > 0 && snapshot.digest !== (stateSeries ?? [])[i - 1].digest).length;
     const stateSeriesLabel = external
-        ? "stateSeries omitted (no authoritative shared-state proof on the external-public plane)"
+        ? "Shared app state was not recorded because the app is hosted outside humanish"
         : `stateSeries ${plural((stateSeries ?? []).length, "snapshot")}, ${plural(deltas, "delta")}`;
     const convergenceLabel = external
         ? `; lobby convergence ${args.lobbyConvergenceDigest ? "shown (all participants reached one /lobby/CODE)" : "not observed"}`

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/detail.js

@@ -13,7 +13,7 @@ import { estimateActorCostForExecution } from "./pricing.js";
 import { resolveRunPath } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { savedCaption } from "./participant-caption.js";
-import { streamParticipantIdOf } from "./participant-records.js";
+import { recordedPersonaId, streamParticipantIdOf } from "./participant-records.js";
 import { readContainedRegularFile } from "./contained-output.js";
 import { isPathInside, resolvePhysicalCwd } from "./paths.js";
 const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
@@ -43,12 +43,12 @@ function latestThought(trace) {
     }
     return undefined;
 }
-function participantFrom(stream, index) {
+function participantFrom(stream, index, savedPersonaId) {
     // A live run's flush wins over the finished trace: while both exist, the live one is the newer
     // account of what is happening.
     const trace = stream.liveActor ?? stream.actor ?? {};
     const id = stream.id ?? `stream-${index + 1}`;
-    const personaId = trace.persona?.id;
+    const personaId = trace.persona?.id ?? savedPersonaId;
     const participantId = streamParticipantIdOf(stream);
     // Computed once: calling it twice to test-then-use reads as though the two could differ.
     const thought = latestThought(trace);
@@ -140,7 +140,7 @@ export async function readRunDetail(cwdInput, runId) {
         ...(automaticAnalysis === undefined ? {} : { automaticAnalysis }),
         schema: RUN_DETAIL_SCHEMA,
         runId: bundle.runId ?? runId,
-        participants: streams.map(participantFrom),
+        participants: streams.map((stream, index) => participantFrom(stream, index, recordedPersonaId(bundle, stream))),
         ...(isPathInside(cwd, observerAbsolute)
             ? { observerPath: path.relative(cwd, observerAbsolute) }
             : { observerPath: observerAbsolute }),

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 };
+}