humanish 0.113.0 → 0.115.0

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

@@ -10,3 +10,10 @@ export declare function parsePublicOrigin(value: string): {
     host: string;
     scheme: "http" | "https";
 } | null;
+/**
+ * A request body, or null once it passes `limit` bytes. Reading stops at the limit: leaving the
+ * loop destroys the request with its socket detached, so the caller can still answer, and should
+ * send `connection: close`, since the rest of the body is never read. Rejects when the client
+ * aborts.
+ */
+export declare function readBodyAtMost(request: AsyncIterable<Buffer>, limit: number): Promise<Buffer | null>;

package/dist/observer/http.js

@@ -1,7 +1,8 @@
 // Shared HTTP hardening primitives for the serve surfaces. Extracted here so both the live
 // Observer server (src/observer/render.ts) and the run-library server
 // (src/observer/serve.ts) can enforce the identical Host allowlist + security-header posture
-// without a module cycle. This file imports nothing from the serve modules.
+// without a module cycle. The email catch (src/comms/email-catch.ts) reads request bodies through
+// readBodyAtMost too. This file imports nothing from the serve modules.
 export function buildServeSecurityHeaders() {
     return {
         "cache-control": "no-store",
@@ -48,3 +49,20 @@ export function parsePublicOrigin(value) {
         scheme: parsed.protocol === "https:" ? "https" : "http",
     };
 }
+/**
+ * A request body, or null once it passes `limit` bytes. Reading stops at the limit: leaving the
+ * loop destroys the request with its socket detached, so the caller can still answer, and should
+ * send `connection: close`, since the rest of the body is never read. Rejects when the client
+ * aborts.
+ */
+export async function readBodyAtMost(request, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > limit)
+            return null;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks, size);
+}

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

@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { PreparedRunArtifactPaths } from "../run/paths.js";
+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,120 @@
+// 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 { z } from "zod";
+import { MAX_NOTE_TEXT, NOTES_TOKEN_HEADER } from "../run/note-shape.js";
+import { addRunNote } from "../run/notes.js";
+import { cli } from "../cli/invocation.js";
+import { hostAllowed, readBodyAtMost } from "./http.js";
+const MAX_BODY_BYTES = 16 * 1024;
+/**
+ * A request to add a note. Its text, time and participant are checked by addRunNote, which says
+ * what is wrong with each, so this checks only their types.
+ */
+const noteRequestSchema = z.object({
+    runId: z.string(),
+    atMs: z.number(),
+    participant: z
+        .string()
+        .nullish()
+        .transform((participant) => participant ?? null),
+    text: z.string(),
+});
+/** 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);
+}
+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 request in a body, or null when the body is not one. */
+function noteRequest(body) {
+    let value;
+    try {
+        value = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    const parsed = noteRequestSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+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[NOTES_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 readBodyAtMost(request, MAX_BODY_BYTES);
+            if (body === null)
+                return tooLarge();
+            const input = noteRequest(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

@@ -5,13 +5,25 @@ import { createHash } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
+import { readOpenedAtMost } from "../run/evidence-files.js";
 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()
+            : opened.size > options.maxBytes
+                ? null
+                : await readOpenedAtMost(opened.handle, 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 +53,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 ||

package/dist/observer/render.js

@@ -12,12 +12,15 @@ import { loadAnalysis } from "../analysis/load.js";
 import { physicalCwdOf, runIdOf, bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { writeContainedOutputFile } from "../run/contained-output.js";
 import { loadRunBundlePrepared, readRunJsonIfExists } from "../run/locate.js";
+import { readRunNotes } from "../run/note-files.js";
 import { RUN_STATUS_FILE } from "../run/status.js";
 import { verifyRunPrepared } from "../verify/verify.js";
 import { renderObserverHtml } from "./artifact.js";
 import { buildObserverData } from "./data.js";
 import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin } from "./http.js";
 import { listenOnLoopback } from "./listen.js";
+import { NOTES_PATH } from "../run/note-shape.js";
+import { createNotesWriter } from "./notes-route.js";
 import { pinDirectChildDirectory, pinDirectory, readContainedFile, } from "./pinned-files.js";
 import { buildHistoryIndex, matchRunRoute, serveRunPath, writeResponse, } from "./run-routes.js";
 import { cli } from "../cli/invocation.js";
@@ -114,7 +117,7 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
     };
     await writeContainedOutputFile(preparedRunPaths, path.join("observer", "observer-data.json"), `${JSON.stringify(observerData, null, 2)}\n`, "utf8");
     await writeContainedOutputFile(preparedRunPaths, path.join("observer", "study-analysis.json"), `${JSON.stringify(analysis, null, 2)}\n`, "utf8");
-    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "index.html"), renderObserverHtml(observerData, { analysis }), "utf8");
+    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "index.html"), renderObserverHtml(observerData, { analysis, notes: await readRunNotes(preparedRunPaths) }), "utf8");
     await validatePreparedRunArtifactPaths(preparedRunPaths);
     const relativeObserverPath = path.join(preparedRunPaths.relativeRunRoot, "observer", "index.html");
     const relativeObserverDataPath = path.join(preparedRunPaths.relativeRunRoot, "observer", "observer-data.json");
@@ -180,6 +183,16 @@ async function resolveObserverRunSelection(cwd, runInput) {
         return null;
     return { runId: pointer.runId, runRoot, runsRoot };
 }
+/**
+ * The served run history. Exposed watch and selected-run viewers pass `onlyRun` and cannot
+ * enumerate other runs; full-library loopback viewers get the complete project index.
+ */
+async function writeHistory(response, proofRoot, onlyRun) {
+    const history = await buildHistoryIndex(proofRoot);
+    const runs = onlyRun === null ? history.runs : history.runs.filter((run) => run.runId === onlyRun);
+    const listed = onlyRun === null ? history : { latestRunId: runs.length > 0 ? onlyRun : null, runs };
+    writeResponse(response, 200, JSON.stringify(listed, null, 2), "application/json; charset=utf-8");
+}
 export async function serveObserver(result, options = {}) {
     if (!result.ok || !result.observerPath) {
         throw new Error("Cannot serve an observer result that did not render successfully.");
@@ -206,6 +219,14 @@ export async function serveObserver(result, options = {}) {
     const runtimeStreamUrls = () => observerRuntimeStreamUrls.get(result) ?? [];
     const exposed = options.exposed === true;
     const scopedToRun = exposed || options.scope === "run";
+    let port = 0;
+    // Notes are taken for the selected run only, whose paths this server already holds.
+    const notes = createNotesWriter({
+        exposed,
+        port: () => port,
+        resolveRun: async (runId) => (runId === result.run ? preparedRunPaths : null),
+        refresh: (prepared) => renderObserver(cwd, result.run, { open: false, expectedRun: prepared }),
+    });
     // Host allowlist for exposed mode (DNS-rebinding defense, identical to the run-library surface).
     // Seeded with the loopback names after bind; addPublicOrigin extends it with the tunnel/public-url
     // host. Never consulted in loopback (non-exposed) mode.
@@ -224,21 +245,22 @@ export async function serveObserver(result, options = {}) {
                 }
             }
             const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "127.0.0.1"}`);
+            if (url.pathname === NOTES_PATH) {
+                await notes.handle(request, response);
+                return;
+            }
+            // Adding a note is the only write; nothing else is read with another method.
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                writeResponse(response, 405, "Method Not Allowed", "text/plain; charset=utf-8");
+                return;
+            }
             if (url.pathname === "/") {
                 response.writeHead(302, { location: "/observer/index.html" });
                 response.end();
                 return;
             }
             if (url.pathname === "/_humanish/history.json") {
-                const history = await buildHistoryIndex(proofRoot);
-                // Exposed watch and selected-run viewers cannot enumerate other runs. Full-library
-                // loopback viewers retain the complete project index.
-                if (scopedToRun) {
-                    const attachedRuns = history.runs.filter((entry) => entry.runId === result.run);
-                    writeResponse(response, 200, JSON.stringify({ latestRunId: attachedRuns.length > 0 ? result.run : null, runs: attachedRuns }, null, 2), "application/json; charset=utf-8");
-                    return;
-                }
-                writeResponse(response, 200, JSON.stringify(history, null, 2), "application/json; charset=utf-8");
+                await writeHistory(response, proofRoot, scopedToRun ? result.run : null);
                 return;
             }
             if (url.pathname.startsWith("/_humanish/runs/")) {
@@ -257,10 +279,10 @@ export async function serveObserver(result, options = {}) {
                     writeResponse(response, 404, "Run not found", "text/plain; charset=utf-8");
                     return;
                 }
-                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, runRoute.runId === result.run ? runtimeStreamUrls() : [], request);
+                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, runRoute.runId === result.run ? runtimeStreamUrls() : [], request, runRoute.runId === result.run ? notes.pageToken(request) : undefined);
                 return;
             }
-            await serveRunPath(runRoot, decodeURIComponent(url.pathname.slice(1)), response, runtimeStreamUrls(), request);
+            await serveRunPath(runRoot, decodeURIComponent(url.pathname.slice(1)), response, runtimeStreamUrls(), request, notes.pageToken(request));
         }
         catch {
             writeResponse(response, 500, "Observer request failed", "text/plain; charset=utf-8");
@@ -269,7 +291,7 @@ export async function serveObserver(result, options = {}) {
     const server = createServer((request, response) => {
         void handleRequest(request, response);
     });
-    const port = await listenOnLoopback(server, options.port ?? 0);
+    port = await listenOnLoopback(server, options.port ?? 0);
     if (exposed) {
         hostAllowlist.add(`127.0.0.1:${port}`);
         hostAllowlist.add(`localhost:${port}`);
@@ -295,7 +317,10 @@ export async function serveObserver(result, options = {}) {
                 hostAllowlist.add(parsed.host);
             }
         },
-        close: () => closeServer(server),
+        close: async () => {
+            await notes.settled();
+            await closeServer(server);
+        },
     };
 }
 /**

package/dist/observer/run-routes.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PreparedRunArtifactPaths } from "../run/paths.js";
 import type { RunDisplay } from "../run/display.js";
 import { type ObserverData } from "./data.js";
 import { type PinnedDirectory } from "./pinned-files.js";
@@ -10,8 +11,13 @@ export interface ObserverRuntimeStreamUrl {
      *  evidence (keyframe replay/screenshot) instead of rendering "sandbox not found". */
     ended?: boolean;
 }
-/** internal: consumed by src/observer/serve.ts */
-export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers">): Promise<void>;
+/** The run's artifact paths, only when they are still the pinned directory being served. */
+export declare function servedRunPaths(runRoot: PinnedDirectory): Promise<PreparedRunArtifactPaths>;
+/**
+ * internal: consumed by src/observer/serve.ts. `notesToken` goes into the run's Observer page so
+ * it can add notes; a server passes it only for a run it takes notes for.
+ */
+export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers">, notesToken?: string): Promise<void>;
 /** internal: exported for the stream lifecycle tests. */
 export declare function withRuntimeStreamUrls(data: ObserverData, runtimeStreamUrls: ObserverRuntimeStreamUrl[]): ObserverData;
 /** internal: consumed by src/observer/serve.ts */

package/dist/observer/run-routes.js

@@ -9,6 +9,7 @@ import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
 import { isRunOutcome } from "../run/bundle-shape.js";
+import { MAX_NOTE_FILE_BYTES, readRunNotes, RUN_NOTES_DIR, } from "../run/note-files.js";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
@@ -16,7 +17,7 @@ import { buildObserverData, recordedStreamEmbed, withObserverEndings, } from "./
 import { buildArtifactSecurityHeaders } from "./http.js";
 import { assertPinnedDirectory, openContainedFile, pinDirectChildDirectory, readContainedFile, relativeToRoot, sha256OfOpenedFile, } from "./pinned-files.js";
 /** The run's artifact paths, only when they are still the pinned directory being served. */
-async function servedRunPaths(runRoot) {
+export async function servedRunPaths(runRoot) {
     const runId = path.basename(runRoot.physicalPath);
     const cwd = path.dirname(path.dirname(path.dirname(runRoot.physicalPath)));
     const prepared = await bindExistingRunArtifactPaths(cwd, runId);
@@ -57,8 +58,25 @@ async function readServedAnalysisSpend(runRoot) {
         return undefined;
     }
 }
-/** internal: consumed by src/observer/serve.ts */
-export async function serveRunPath(runRoot, relativePath, response, runtimeStreamUrls = [], request) {
+/**
+ * The run's note files as served: each read through the root's checks, so a --safe root's
+ * admission and hash checks apply to every note.
+ */
+function servedNoteFiles(runRoot) {
+    return {
+        runId: path.basename(runRoot.physicalPath),
+        async directory() {
+            await assertPinnedDirectory(runRoot);
+            return runRoot.physicalPath;
+        },
+        read: (relativePath, maxBytes) => readContainedFile(runRoot, path.join(runRoot.physicalPath, relativePath), { maxBytes }),
+    };
+}
+/**
+ * internal: consumed by src/observer/serve.ts. `notesToken` goes into the run's Observer page so
+ * it can add notes; a server passes it only for a run it takes notes for.
+ */
+export async function serveRunPath(runRoot, relativePath, response, runtimeStreamUrls = [], request, notesToken) {
     const root = runRoot.physicalPath;
     const filePath = path.resolve(root, relativePath === "" ? "observer/index.html" : relativePath);
     if (!isPathInside(root, filePath)) {
@@ -87,7 +105,12 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
             return;
         }
         const analysis = await readObserverAnalysis(runRoot);
-        writeResponse(response, 200, renderObserverHtml(observerData, { analysis }), "text/html; charset=utf-8");
+        const notes = await readRunNotes(servedNoteFiles(runRoot));
+        writeResponse(response, 200, renderObserverHtml(observerData, {
+            analysis,
+            notes,
+            ...(notesToken === undefined ? {} : { notesToken }),
+        }), "text/html; charset=utf-8");
         return;
     }
     if (cleanedRelativePath === "observer/observer-data.json") {
@@ -103,7 +126,10 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         writeResponse(response, 200, JSON.stringify(await readObserverAnalysis(runRoot)), "application/json; charset=utf-8");
         return;
     }
-    if (path.extname(filePath).toLowerCase() === ".mp4") {
+    // Every file under notes/ is read within the note limit, whatever its name, so media handling
+    // never streams one.
+    const notePath = derivedRoot === RUN_NOTES_DIR;
+    if (!notePath && path.extname(filePath).toLowerCase() === ".mp4") {
         await serveContainedMedia(runRoot, filePath, response, request);
         return;
     }
@@ -112,7 +138,7 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
         return;
     }
     try {
-        const body = await readContainedFile(runRoot, filePath);
+        const body = await readContainedFile(runRoot, filePath, notePath ? { maxBytes: MAX_NOTE_FILE_BYTES } : {});
         if (!body) {
             writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
             return;

package/dist/observer/serve.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type NotesWriter } from "./notes-route.js";
 import type { PinnedDirectory } from "./pinned-files.js";
 import { type AdmittedRun } from "./run-inventory.js";
 import type { LibraryHistory } from "./library.js";
@@ -70,6 +71,8 @@ export declare function createShareSafetyAdmission(cwd: string, options?: {
 }): ShareSafetyAdmission;
 export interface ServeRequestHandlerOptions {
     proofRoot: PinnedDirectory;
+    /** Takes reviewer notes on loopback; without it the library refuses them. */
+    notes?: NotesWriter;
     safe: boolean;
     admit: (runId: string) => Promise<AdmittedRun | null>;
     hostAllowlist: ReadonlySet<string>;

package/dist/observer/serve.js

@@ -3,7 +3,10 @@ import { runNotFoundMessage } from "../run/run-not-found.js";
 import { createServer } from "node:http";
 import path from "node:path";
 import { pinDirectChildDirectory, pinDirectory } from "./pinned-files.js";
-import { buildHistoryIndex, matchRunRoute, serveRunPath } from "./run-routes.js";
+import { NOTES_PATH } from "../run/note-shape.js";
+import { createNotesWriter } from "./notes-route.js";
+import { renderObserver } from "./render.js";
+import { buildHistoryIndex, matchRunRoute, servedRunPaths, serveRunPath } from "./run-routes.js";
 import { hashRunInventory, inventoryRoot, readRunInventory, } from "./run-inventory.js";
 import { renderLibraryHtml } from "./library.js";
 import { buildServeSecurityHeaders, hostAllowed, parsePublicOrigin, } from "./http.js";
@@ -104,6 +107,13 @@ export function createServeRequestHandler(options) {
             for (const [name, value] of Object.entries(buildServeSecurityHeaders())) {
                 response.setHeader(name, value);
             }
+            if (new URL(request.url ?? "/", "http://127.0.0.1").pathname === NOTES_PATH) {
+                if (options.notes)
+                    await options.notes.handle(request, response);
+                else
+                    writeText(response, 405, "Method Not Allowed");
+                return;
+            }
             const method = request.method ?? "GET";
             if (method !== "GET" && method !== "HEAD") {
                 writeText(response, 405, "Method Not Allowed");
@@ -161,7 +171,7 @@ export function createServeRequestHandler(options) {
                 }
                 // The explicit empty runtimeStreamUrls keeps a future refactor from
                 // reintroducing auth-keyed stream injection on the serve surface.
-                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, [], request);
+                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, [], request, options.notes?.pageToken(request));
                 return;
             }
             writeText(response, 404, "Not found");
@@ -260,8 +270,24 @@ export async function serveObserverLibrary(cwdInput, options) {
     }
     const declaredOrigin = options.publicOrigin ? parsePublicOrigin(options.publicOrigin) : null;
     const hostAllowlist = new Set();
+    let port = 0;
+    const notes = createNotesWriter({
+        exposed: mode !== "loopback",
+        port: () => port,
+        resolveRun: async (runId) => {
+            const pinned = await pinDirectChildDirectory(proofRoot, runId);
+            if (!pinned || (options.safe && (await admission.admit(runId)) === null))
+                return null;
+            return servedRunPaths(pinned);
+        },
+        refresh: (prepared) => renderObserver(cwd, path.basename(prepared.physicalRunRoot), {
+            open: false,
+            expectedRun: prepared,
+        }),
+    });
     const handler = createServeRequestHandler({
         proofRoot,
+        notes,
         safe: options.safe,
         admit: (runId) => admission.admit(runId),
         hostAllowlist,
@@ -276,7 +302,6 @@ export async function serveObserverLibrary(cwdInput, options) {
     const server = createServer((request, response) => {
         void handler(request, response);
     });
-    let port;
     try {
         port = await listenOnLoopback(server, options.port);
     }
@@ -314,6 +339,7 @@ export async function serveObserverLibrary(cwdInput, options) {
                 hostAllowlist.add(parsed.host);
             },
             close: async () => {
+                await notes.settled();
                 const closed = closeServer(server);
                 // Keep-alive sockets would otherwise keep close() pending past the point
                 // the operator believes Ctrl-C tore the server down.