humanish 0.112.0 → 0.114.0

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/keys/key-resolution.js

@@ -245,6 +245,8 @@ export function missingKeyHint(name) {
             return `run \`${cli("keys set openai")}\``;
         case "ANTHROPIC_API_KEY":
             return `run \`${cli("keys set anthropic")}\``;
+        case "AGENTMAIL_API_KEY":
+            return `run \`${cli("keys set agentmail")}\``;
         default:
             return `run \`${cli(`keys set ${name}`)}\``;
     }

package/dist/keys/key-status.d.ts

@@ -0,0 +1,37 @@
+import { type KeyResolutionDeps, type KeySourceProbe } from "./key-resolution.js";
+interface KeyStatusRow extends KeySourceProbe {
+    /** What humanish uses the key for, in a few words. */
+    use: string;
+}
+export declare function keyStatus(args: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    deps?: KeyResolutionDeps;
+}): Promise<KeyStatusRow[]>;
+/** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
+export declare function otherStoredKeys(env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): string[];
+export declare function formatKeyStatus(rows: readonly KeyStatusRow[], otherStored?: readonly string[]): string;
+interface MissingKeysOutcome {
+    stored: string[];
+    /** Keys left unset because the person pressed Enter without a value. */
+    skipped: string[];
+    /** Keys whose value the store refused, with the reason. */
+    rejected?: Array<{
+        name: string;
+        message: string;
+    }>;
+    /** The key whose prompt was cancelled. No later key was asked for. */
+    stoppedAt?: string;
+}
+/**
+ * `humanish keys set` with no key named: ask for each missing key in turn and store each answer in
+ * the user store. An empty answer skips that key; a cancelled prompt (null) stops the walk and
+ * keeps what was already stored.
+ */
+export declare function askForMissingKeys(args: {
+    rows: readonly KeyStatusRow[];
+    env: NodeJS.ProcessEnv;
+    deps?: KeyResolutionDeps;
+    prompt: (label: string) => Promise<string | null>;
+}): Promise<MissingKeysOutcome>;
+export {};

package/dist/keys/key-status.js

@@ -0,0 +1,68 @@
+// `humanish keys`: which provider keys are set and where each comes from, through the same chain a
+// live command resolves. Never a value.
+import { cli } from "../cli/invocation.js";
+import { listUserKeys, probeKeySources, setUserKey, } from "./key-resolution.js";
+/**
+ * The keys a person sets for humanish, in the order the status lists them and `keys set` asks for
+ * them. ANTHROPIC_API_KEY is left out: a Claude Code participant runs on its own login and never
+ * receives it. CODEX_API_KEY is an alternative spelling of the OpenAI key for terminal studies.
+ */
+const STATUS_KEYS = [
+    { name: "E2B_API_KEY", use: "hosted desktops" },
+    { name: "OPENAI_API_KEY", use: "participant model and analysis" },
+    { name: "GH_TOKEN", use: "private repository subjects" },
+    { name: "AGENTMAIL_API_KEY", use: "email in studies" },
+];
+export async function keyStatus(args) {
+    const probes = await probeKeySources(STATUS_KEYS.map((key) => key.name), {
+        cwd: args.cwd,
+        env: args.env,
+        ...(args.deps === undefined ? {} : { deps: args.deps }),
+    });
+    return probes.map((probe, index) => ({ ...probe, use: STATUS_KEYS[index].use }));
+}
+/** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
+export function otherStoredKeys(env, deps = {}) {
+    const listed = new Set(STATUS_KEYS.map((key) => key.name));
+    return listUserKeys(env, deps).filter((name) => !listed.has(name));
+}
+export function formatKeyStatus(rows, otherStored = []) {
+    const lines = rows.map((row) => `${row.name} (${row.use}): ${row.source === null ? `missing; ${row.hint}` : `set, from ${row.source}`}`);
+    if (otherStored.length > 0)
+        lines.push(`Also in the user store: ${otherStored.join(", ")}. humanish does not use ${otherStored.length === 1 ? "it" : "them"} today.`);
+    const missing = rows.some((row) => row.source === null);
+    lines.push("", missing
+        ? `Values are never printed. \`${cli("keys set")}\` asks for each missing key in turn.`
+        : "Values are never printed.");
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * `humanish keys set` with no key named: ask for each missing key in turn and store each answer in
+ * the user store. An empty answer skips that key; a cancelled prompt (null) stops the walk and
+ * keeps what was already stored.
+ */
+export async function askForMissingKeys(args) {
+    const outcome = { stored: [], skipped: [] };
+    for (const row of args.rows) {
+        if (row.source !== null)
+            continue;
+        const value = await args.prompt(`${row.name} for ${row.use}`);
+        if (value === null)
+            return { ...outcome, stoppedAt: row.name };
+        if (value === "") {
+            outcome.skipped.push(row.name);
+            continue;
+        }
+        try {
+            setUserKey(row.name, value, args.env, args.deps);
+            outcome.stored.push(row.name);
+        }
+        catch (error) {
+            (outcome.rejected ??= []).push({
+                name: row.name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return outcome;
+}

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");

package/dist/observer/render.js

@@ -12,12 +12,14 @@ 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/notes.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 { createNotesWriter, NOTES_PATH } 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 +116,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 +182,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 +218,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 +244,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 +278,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 +290,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 +316,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 */