humanish 0.113.0 → 0.114.0

package/dist/feedback/draft.js

@@ -8,6 +8,8 @@ import { hashAnalysisValue } from "../analysis/validation.js";
 import { formatParticipantOutcomes, formatRunTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
 import { isFeedbackIdempotencyKey } from "../run/feedback-shape.js";
+import { runNoteFile } from "../run/note-files.js";
+import { formatRunTime, runParticipantCaptions } from "../run/notes.js";
 import { isRecord } from "../run/type-guards.js";
 import { feedbackProofCommands, projectFeedbackAcceptanceProof } from "./proof.js";
 export const FEEDBACK_SCHEMA = "humanish.feedback.v1";
@@ -224,6 +226,54 @@ function citedImpressions(bundle, evidence) {
             : [{ streamId: item.streamId, kind: impression.kind, text: impression.text }];
     });
 }
+/**
+ * The draft with the run's reviewer notes and each note's file cited. The caller passes the set it
+ * read and checked for sharing (readNotesForSharing).
+ */
+export function withReviewerNotes(draft, notes, bundle, runRoot) {
+    if (notes === null || notes.notes.length === 0)
+        return draft;
+    const captions = runParticipantCaptions(bundle);
+    const ordered = [...notes.notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
+    return {
+        ...draft,
+        evidence: [
+            ...draft.evidence,
+            ...ordered.map((note) => ({
+                path: path.join(runRoot, runNoteFile(note.id)),
+                kind: "review",
+                note: `Reviewer note at ${formatRunTime(note.atMs)}, added while reviewing the recording.`,
+            })),
+        ],
+        reviewer_notes: ordered.map((note) => ({
+            id: note.id,
+            at: formatRunTime(note.atMs),
+            at_ms: note.atMs,
+            participant: note.participant,
+            participant_caption: note.participant === null ? null : (captions.get(note.participant) ?? note.participant),
+            author: note.author,
+            text: note.text,
+        })),
+    };
+}
+function reviewerNotesSection(draft) {
+    if (!draft.reviewer_notes?.length)
+        return "";
+    const items = draft.reviewer_notes.map((note) => {
+        const [first = "", ...rest] = note.text.split("\n");
+        return [
+            `- ${note.at}, ${note.participant_caption ?? "whole run"}, ${note.author}: ${first}`,
+            ...rest.map((line) => `  ${line}`),
+        ].join("\n");
+    });
+    return `## Reviewer notes
+
+Notes a person added while reviewing the recording. They are not participant feedback.
+
+${items.join("\n")}
+
+`;
+}
 export function isUsableFeedbackCandidate(candidate) {
     if (!isRecord(candidate) ||
         candidate.schema !== "humanish.feedback-candidate.v1" ||
@@ -262,7 +312,7 @@ ${draft.expected}
 
 ${draft.actual}
 
-## Evidence
+${reviewerNotesSection(draft)}## Evidence
 
 ${draft.evidence.map((item) => `- ${item.kind} ${runRelative(draft, item.path)}: ${item.note}`).join("\n")}
 

package/dist/feedback/export-bundle.js

@@ -10,7 +10,7 @@ import { renderObserver } from "../observer/render.js";
 import { buildObserverData } from "../observer/data.js";
 import { inventorySandboxIds, scrubSandboxIdBytes } from "../run/sandbox-ids.js";
 import { containsSensitive, redactSandboxIds, redactScreenshot, redactText, } from "../evidence/redaction.js";
-import { decodeEscapes } from "../evidence/encoded-text.js";
+import { decodeEscapes, utf8ReadingOf } from "../evidence/encoded-text.js";
 import { readPlainText } from "../evidence/plain-text.js";
 import { streamScreenshotPaths } from "../verify/artifacts.js";
 import { verifyRunPrepared } from "../verify/verify.js";
@@ -149,7 +149,7 @@ function assertNoInlineRaster(text) {
     // Decode the escapes verify decodes (decodeEscapes) before checking. Unknown embedded bytes are
     // refused: copying a text extension must not smuggle untransformed pixels.
     const decoded = decodeEscapes(text);
-    if (containsSensitive(text) || containsSensitive(decoded))
+    if ([text, decoded, utf8ReadingOf(text, decoded) ?? ""].some(containsSensitive))
         throw new Error("Decoded text contains a secret-shaped value or private path; export refused.");
     if (/data\s*:\s*(?:image\/|application\/|text\/|[^,\s]*;base64,|,)/i.test(decoded) ||
         /iVBORw0KGgo|\/9j\/[A-Za-z0-9+/]|R0lGOD|UklGR[A-Za-z0-9+/]{4}|<svg\b/i.test(decoded)) {

package/dist/feedback/export.js

@@ -19,6 +19,8 @@ import { verifyRun } from "../verify/verify.js";
 import {} from "../run/bundle.js";
 import { exportRedactedBundle } from "./export-bundle.js";
 import { loadAnalysis } from "../analysis/load.js";
+import { readNotesForSharing } from "../run/notes.js";
+import { cli } from "../cli/invocation.js";
 import { analysisSharingProblems } from "../analysis/sharing.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "../analysis/evidence.js";
 import { readBoundedFile } from "../run/evidence-files.js";
@@ -96,8 +98,13 @@ export async function exportRun(cwdInput, runInput, options = {}, deps = {}) {
     if (analysisCheck === "downgraded")
         shareReady = false;
     warnings.push(...analysis.warnings);
+    const notes = await checkedNotes(runPaths, verified, inlined, options, warnings);
+    if (notes.check === "blocked")
+        return exportFailure(cwd, runInput, "HUMANISH_EXPORT_SHARE_SAFETY_BLOCKED", `The run's reviewer notes hold text that looks like a secret, a token or a local path, which verify may not have seen if a note was added or changed after it ran. Run \`${cli(`verify --run ${runId}`)}\`, fix the note files in notes/, and export again.`, verified.shareSafety);
+    if (notes.check === "downgraded")
+        shareReady = false;
     const watermarked = !shareReady || omittedRecording;
-    const output = renderExportHtml(inlined, analysis, assets, verified, watermarked, omittedRecording);
+    const output = renderExportHtml(inlined, { analysis, notes: notes.notes }, assets, verified, watermarked, omittedRecording);
     const bytes = Buffer.byteLength(output, "utf8");
     const maxBytes = options.maxBytes ?? DEFAULT_EXPORT_MAX_BYTES;
     if (bytes > maxBytes) {
@@ -334,11 +341,48 @@ async function recheckAnalysis(runPaths, analysis, verified, inlined, options) {
     };
     return "downgraded";
 }
+/**
+ * The run's notes for the export, read once within the notes size limit. That snapshot is scanned
+ * as verify scans run text and is the one rendered, so a note added or changed after verify ran cannot
+ * reach the file unchecked. A finding blocks the export, or downgrades it under --local-only.
+ */
+async function checkedNotes(runPaths, verified, inlined, options, warnings) {
+    const { notes, finding } = await readNotesForSharing(runPaths);
+    for (const skipped of notes.skipped)
+        warnings.push(`Reviewer notes: ${skipped}`);
+    if (finding === null)
+        return { notes, check: "ok" };
+    verified.shareSafety = {
+        status: finding === "sensitive" || verified.shareSafety.status === "blocked"
+            ? "blocked"
+            : "local_only",
+        reasons: [
+            ...verified.shareSafety.reasons,
+            finding === "sensitive"
+                ? {
+                    code: "PUBLIC_SAFETY_FINDINGS",
+                    message: "The reviewer notes being exported match secret, token or local-path patterns.",
+                }
+                : {
+                    code: "UNSCANNED_ARTIFACT",
+                    message: "The reviewer notes being exported hold encoded text the scan cannot read.",
+                },
+        ],
+    };
+    if (options.localOnly !== true)
+        return { notes, check: "blocked" };
+    inlined.publicSafety.share = {
+        status: verified.shareSafety.status,
+        verifiedAt: new Date().toISOString(),
+        reasons: verified.shareSafety.reasons.map((reason) => reason.code),
+    };
+    return { notes, check: "downgraded" };
+}
 /** The portable Observer HTML, with the local-only banner when the export is watermarked. */
-function renderExportHtml(inlined, analysis, assets, verified, watermarked, omittedRecording) {
+function renderExportHtml(inlined, review, assets, verified, watermarked, omittedRecording) {
     const output = renderObserverHtml(inlined, {
         snapshot: true,
-        analysis,
+        ...review,
         assets,
     });
     if (!watermarked)

package/dist/feedback/feedback.js

@@ -6,8 +6,10 @@ import path from "node:path";
 import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
+import { readNotesForSharing } from "../run/notes.js";
+import { cli } from "../cli/invocation.js";
 import { verifyRunPrepared } from "../verify/verify.js";
-import { buildAnalysisDraft, buildDraft, isUsableFeedbackCandidate, renderMarkdown, } from "./draft.js";
+import { buildAnalysisDraft, buildDraft, isUsableFeedbackCandidate, renderMarkdown, withReviewerNotes, } from "./draft.js";
 const FEEDBACK_RESULT_SCHEMA = "humanish.feedback-result.v1";
 function summarizeCandidates(bundle) {
     return bundle.feedbackCandidates
@@ -90,6 +92,14 @@ async function draftFeedbackBound(cwdInput, runInput, options = {}) {
             },
         };
     }
+    // The notes the draft includes are this set, checked here: a note can be added or changed after
+    // verify read the run.
+    const shared = await readNotesForSharing(context.preparedRunPaths);
+    if (shared.finding !== null)
+        return {
+            context,
+            result: notesRefusal(cwd, runInput, context.storedRunId, verified, shared.finding),
+        };
     const candidates = summarizeCandidates(context.loaded.bundle);
     if (options.candidate !== undefined &&
         !candidates.some((item) => item.id === options.candidate)) {
@@ -111,9 +121,11 @@ async function draftFeedbackBound(cwdInput, runInput, options = {}) {
         };
     }
     const independent = options.analysis !== undefined || options.finding !== undefined;
-    const draft = independent
+    const built = independent
         ? await buildAnalysisDraft(context, options)
         : buildDraft(context.loaded.bundle, context.loaded.bundlePath, options.candidate);
+    const draft = built &&
+        withReviewerNotes(built, shared.notes, context.loaded.bundle, path.dirname(context.loaded.bundlePath));
     if (!draft)
         return {
             context,
@@ -143,6 +155,34 @@ async function draftFeedbackBound(cwdInput, runInput, options = {}) {
         },
     };
 }
+/** The refusal of a draft whose reviewer notes, as read for it, hold what verify's scan flags. */
+function notesRefusal(cwd, runInput, runId, verified, finding) {
+    return {
+        schema: FEEDBACK_RESULT_SCHEMA,
+        ok: false,
+        cwd,
+        run: runInput,
+        shareSafety: {
+            status: "blocked",
+            reasons: [
+                ...verified.shareSafety.reasons,
+                finding === "sensitive"
+                    ? {
+                        code: "PUBLIC_SAFETY_FINDINGS",
+                        message: "The reviewer notes the draft would include match secret, token or local-path patterns.",
+                    }
+                    : {
+                        code: "UNSCANNED_ARTIFACT",
+                        message: "The reviewer notes the draft would include hold encoded text the scan cannot read.",
+                    },
+            ],
+        },
+        error: {
+            code: "HUMANISH_FEEDBACK_SHARE_SAFETY_BLOCKED",
+            message: `The run's reviewer notes hold text that looks like a secret, a token or a local path, so no draft was written. Run \`${cli(`verify --run ${runId}`)}\` and fix the note files in notes/.`,
+        },
+    };
+}
 export async function verifyFeedback(cwdInput, runInput, options = {}) {
     return (await verifyFeedbackBound(cwdInput, runInput, options)).result;
 }

package/dist/observer/artifact.d.ts

@@ -1,4 +1,5 @@
 import type { LoadedAnalysis } from "../analysis/types.js";
+import type { RunNotes } from "../run/notes.js";
 import { type ObserverData } from "./data.js";
 /**
  * Resolve (and in a repo checkout, build) the Observer artifact before any run or
@@ -19,5 +20,9 @@ export type ObserverExportAssets = Record<string, {
 export declare function renderObserverHtml(data: ObserverData, options?: {
     snapshot?: boolean;
     analysis?: LoadedAnalysis;
+    /** The run's reviewer notes, shown read-only unless `notesToken` is set. */
+    notes?: RunNotes | null;
+    /** The serving process's token for adding a note. Only a loopback server's page carries it. */
+    notesToken?: string;
     assets?: ObserverExportAssets;
 }): string;

package/dist/observer/artifact.js

@@ -159,7 +159,7 @@ function renderExportAssets(assets) {
     })
         .join("");
 }
-function renderObserverAppHtml(data, snapshot, analysis, assets) {
+function renderObserverAppHtml(data, snapshot, analysis, notes, assets) {
     const artifact = loadObserverArtifact();
     // A renderer-owned boot marker, outside the untrusted run-data contract. Only
     // portable HTML exports opt out of a live feed; ordinary served pages still poll.
@@ -168,6 +168,7 @@ function renderObserverAppHtml(data, snapshot, analysis, assets) {
         : artifact)
         .replace(OBSERVER_DATA_SLOT, () => `<script id="observer-data" type="application/json">${escapeJsonScript(data)}</script>`)
         .replace(/<script id="study-analysis" type="application\/json">[\s\S]*?<\/script>/, () => `<script id="study-analysis" type="application/json">${escapeJsonScript(analysis)}</script>`)
+        .replace(/<script id="run-notes" type="application\/json">[\s\S]*?<\/script>/, () => `<script id="run-notes" type="application/json">${escapeJsonScript(notes)}</script>`)
         .replace("</body>", () => `${renderExportAssets(assets)}</body>`)
         .replace(/<title>[^<]*<\/title>/, () => `<title>humanish Observer · ${escapeHtml(data.run.runId)}</title>`);
 }
@@ -207,7 +208,22 @@ export function renderObserverHtml(data, options = {}) {
             },
         };
     }
-    return renderObserverAppHtml(withObserverEndings(data), options.snapshot === true, projectShareCheckedAnalysis(analysis), options.assets ?? {});
+    // A snapshot is a file anyone may open later, so it never carries a server's token.
+    const write = options.notesToken !== undefined && options.snapshot !== true
+        ? { token: options.notesToken }
+        : null;
+    return renderObserverAppHtml(withObserverEndings(data), options.snapshot === true, projectShareCheckedAnalysis(analysis), {
+        // A run without notes renders the slot as before notes existed.
+        notes: options.notes == null ||
+            (options.notes.notes.length === 0 && options.notes.skipped.length === 0)
+            ? null
+            : {
+                runId: options.notes.runId,
+                notes: options.notes.notes,
+                skipped: options.notes.skipped.length,
+            },
+        write,
+    }, options.assets ?? {});
 }
 function escapeHtml(value) {
     return value.replace(/[&<>"']/g, (char) => {

package/dist/observer/notes-route.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { PreparedRunArtifactPaths } from "../run/paths.js";
+export declare const NOTES_PATH = "/api/notes";
+export interface NotesWriterOptions {
+    /** An exposed server refuses every note and gives its pages no token. */
+    exposed: boolean;
+    /** The port the server listens on, once it does. */
+    port(): number;
+    /** The run's paths when this server serves it, otherwise null. */
+    resolveRun(runId: string): Promise<PreparedRunArtifactPaths | null>;
+    /** Renders the run's saved Observer page again after a note is added. */
+    refresh(prepared: PreparedRunArtifactPaths): Promise<unknown>;
+}
+export interface NotesWriter {
+    /** The token for a page this server renders for `request`, or undefined when it takes no notes. */
+    pageToken(request: Pick<IncomingMessage, "headers">): string | undefined;
+    handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+    /** Resolves once every saved page a note started rendering again is written. */
+    settled(): Promise<void>;
+}
+export declare function createNotesWriter(options: NotesWriterOptions): NotesWriter;

package/dist/observer/notes-route.js

@@ -0,0 +1,140 @@
+// POST /api/notes, the one write an Observer server accepts: a reviewer note on a run it serves.
+// A server takes it only while it listens on loopback and is not exposed, with the token it put in
+// the page it rendered, and from that page's own origin. Every other request is refused before its
+// body is read past 16 KiB. A page from another site can send a POST to a loopback port, but it
+// cannot read the token from the page or send this origin, and a name rebound to 127.0.0.1 arrives
+// with its own Host.
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { addRunNote, MAX_NOTE_TEXT, } from "../run/notes.js";
+import { isRecord } from "../run/type-guards.js";
+import { cli } from "../cli/invocation.js";
+import { hostAllowed } from "./http.js";
+export const NOTES_PATH = "/api/notes";
+const TOKEN_HEADER = "x-humanish-notes-token";
+const MAX_BODY_BYTES = 16 * 1024;
+/** The HTTP status for a refusal from the notes store. */
+const STORE_STATUS = {
+    HUMANISH_NOTE_INVALID: 400,
+    HUMANISH_NOTE_UNKNOWN_PARTICIPANT: 400,
+    HUMANISH_NOTE_OUTSIDE_RUN: 400,
+    HUMANISH_NOTE_NO_CLOCK: 409,
+    HUMANISH_INVALID_RUN_BUNDLE: 409,
+    HUMANISH_NOTES_UNREADABLE: 409,
+    HUMANISH_NOTES_FULL: 409,
+    HUMANISH_NOTE_ID_TAKEN: 409,
+};
+/** The Host values a loopback page uses for this port. */
+function loopbackHosts(port) {
+    return new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+}
+function reply(response, status, body, close = false) {
+    response.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        ...(status === 405 ? { allow: "POST" } : {}),
+        // A refused request's body is never read, so the connection cannot carry another request.
+        ...(close ? { connection: "close" } : {}),
+    });
+    response.end(`${JSON.stringify(body)}\n`);
+}
+function refuse(response, status, code, message) {
+    reply(response, status, { ok: false, error: { code, message } }, true);
+}
+/** The body, or null once it passes MAX_BODY_BYTES; reading stops there. */
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        const onData = (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                request.off("data", onData);
+                request.pause();
+                resolve(null);
+                return;
+            }
+            chunks.push(chunk);
+        };
+        request.on("data", onData);
+        request.once("end", () => resolve(Buffer.concat(chunks)));
+        request.once("error", reject);
+    });
+}
+function sameToken(sent, token) {
+    if (typeof sent !== "string")
+        return false;
+    const left = Buffer.from(sent);
+    const right = Buffer.from(token);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/** The note in a request body, or null when the body is not one. */
+function noteInput(body) {
+    let value;
+    try {
+        value = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value) ||
+        typeof value.runId !== "string" ||
+        typeof value.atMs !== "number" ||
+        typeof value.text !== "string" ||
+        !(value.participant === undefined ||
+            value.participant === null ||
+            typeof value.participant === "string"))
+        return null;
+    return {
+        runId: value.runId,
+        atMs: value.atMs,
+        participant: typeof value.participant === "string" ? value.participant : null,
+        text: value.text,
+    };
+}
+export function createNotesWriter(options) {
+    const token = randomBytes(32).toString("base64url");
+    // Renders run one after another, so an older render cannot overwrite a newer one.
+    let refreshes = Promise.resolve();
+    return {
+        pageToken(request) {
+            return !options.exposed && hostAllowed(request.headers.host, loopbackHosts(options.port()))
+                ? token
+                : undefined;
+        },
+        async handle(request, response) {
+            if (request.method !== "POST")
+                return refuse(response, 405, "HUMANISH_NOTES_METHOD", "Notes are added with POST.");
+            if (options.exposed)
+                return refuse(response, 403, "HUMANISH_NOTES_EXPOSED", `This Observer is shared beyond this machine, so it does not take notes. Add notes from an Observer served on 127.0.0.1, or with \`${cli("notes <run> --add")}\`.`);
+            const host = request.headers.host?.trim().toLowerCase();
+            if (host === undefined ||
+                !hostAllowed(host, loopbackHosts(options.port())) ||
+                request.headers.origin !== `http://${host}`)
+                return refuse(response, 403, "HUMANISH_NOTES_ORIGIN", "A note can only come from the Observer page this server rendered, at the address it was opened from. Open the Observer from the address humanish printed and add the note there.");
+            if (!sameToken(request.headers[TOKEN_HEADER], token))
+                return refuse(response, 403, "HUMANISH_NOTES_TOKEN", "The request does not carry this server's note token, which changes each time the server starts. Reload the Observer page and add the note again.");
+            if (!/^application\/json(?:\s*;|$)/i.test(request.headers["content-type"] ?? ""))
+                return refuse(response, 415, "HUMANISH_NOTES_BODY", "A note is sent as JSON with runId, atMs, participant and text.");
+            const tooLarge = () => refuse(response, 413, "HUMANISH_NOTES_TOO_LARGE", `The request is larger than ${MAX_BODY_BYTES / 1024} KiB. A note holds at most ${MAX_NOTE_TEXT} characters.`);
+            if (Number(request.headers["content-length"] ?? 0) > MAX_BODY_BYTES)
+                return tooLarge();
+            const body = await readBody(request);
+            if (body === null)
+                return tooLarge();
+            const input = noteInput(body);
+            if (input === null)
+                return refuse(response, 400, "HUMANISH_NOTES_BODY", "A note is a JSON object with runId, atMs (milliseconds on the run clock), participant (a stream id or null) and text.");
+            const prepared = await options.resolveRun(input.runId).catch(() => null);
+            if (prepared === null)
+                return refuse(response, 404, "HUMANISH_RUN_NOT_FOUND", "This server does not serve that run, so it cannot take a note for it.");
+            const added = await addRunNote(prepared, input);
+            if (!added.ok)
+                return refuse(response, STORE_STATUS[added.error.code], added.error.code, added.error.message);
+            reply(response, 201, added);
+            refreshes = refreshes.then(() => options.refresh(prepared).then(() => undefined, () => undefined));
+        },
+        settled() {
+            return refreshes;
+        },
+    };
+}

package/dist/observer/pinned-files.d.ts

@@ -14,7 +14,14 @@ export interface PinnedDirectory {
     /** When set, a file's bytes are served only if this accepts their sha256. */
     readonly admitsContent?: (relativePath: string, sha256: string) => boolean;
 }
-export declare function readContainedFile(root: PinnedDirectory, filePathInput: string): Promise<Buffer | null>;
+/**
+ * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
+ * file larger than that is refused from its opened size and the read stops there, so a large file
+ * is never held in memory.
+ */
+export declare function readContainedFile(root: PinnedDirectory, filePathInput: string, options?: {
+    maxBytes?: number;
+}): Promise<Buffer | null>;
 export declare function openContainedFile(root: PinnedDirectory, filePathInput: string): Promise<{
     handle: FileHandle;
     size: number;

package/dist/observer/pinned-files.js

@@ -6,12 +6,21 @@ import { constants as fsConstants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
 import { isPathInside, isSafeRunIdSegment } from "../run/paths.js";
-export async function readContainedFile(root, filePathInput) {
+/**
+ * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
+ * file larger than that is refused from its opened size and the read stops there, so a large file
+ * is never held in memory.
+ */
+export async function readContainedFile(root, filePathInput, options = {}) {
     const opened = await openContainedFile(root, filePathInput);
     if (!opened)
         return null;
     try {
-        const body = await opened.handle.readFile();
+        const body = options.maxBytes === undefined
+            ? await opened.handle.readFile()
+            : await readAtMost(opened.handle, opened.size, options.maxBytes);
+        if (body === null)
+            return null;
         // A write that landed during the read changed the file's mtime and ctime.
         if (root.admitsFile !== undefined &&
             !root.admitsFile(relativeToRoot(root, filePathInput), await opened.handle.stat({ bigint: true }))) {
@@ -41,7 +50,9 @@ export async function openContainedFile(root, filePathInput) {
         const expectedStats = await inspectContainedRegularFile(root, filePath);
         if (!expectedStats)
             return null;
-        handle = await open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        // O_NONBLOCK: a leaf swapped for a FIFO after the checks above opens at once, without waiting
+        // for a writer, and the descriptor checks below refuse it.
+        handle = await open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
         const openedStats = await handle.stat({ bigint: true });
         if (!openedStats.isFile() ||
             openedStats.nlink !== 1n ||
@@ -68,6 +79,24 @@ export async function openContainedFile(root, filePathInput) {
         return null;
     }
 }
+/** At most `maxBytes` from the start of an opened file, or null when it holds more. */
+async function readAtMost(handle, size, maxBytes) {
+    if (size > maxBytes)
+        return null;
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes + 1 - total));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+        if (bytesRead === 0)
+            return Buffer.concat(chunks, total);
+        total += bytesRead;
+        // The file grew past the limit after it was opened.
+        if (total > maxBytes)
+            return null;
+        chunks.push(chunk.subarray(0, bytesRead));
+    }
+}
 /** The sha256 of an opened file, read by position so the handle's own offset is untouched. */
 export async function sha256OfOpenedFile(handle) {
     const hash = createHash("sha256");