humanish 0.114.0 → 0.116.0

package/dist/feedback/feedback.js

@@ -4,9 +4,9 @@ import { realpath } from "node:fs/promises";
 import { runNotFoundMessage } from "../run/run-not-found.js";
 import path from "node:path";
 import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
-import { bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
+import { bindExistingManagedHumanishOutputDirectory, ContainedReadRefusedError, LATEST_POINTER_MAX_BYTES, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "../run/contained-output.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
-import { readNotesForSharing } from "../run/notes.js";
+import { readNotesForSharing } from "../run/note-files.js";
 import { cli } from "../cli/invocation.js";
 import { verifyRunPrepared } from "../verify/verify.js";
 import { buildAnalysisDraft, buildDraft, isUsableFeedbackCandidate, renderMarkdown, withReviewerNotes, } from "./draft.js";
@@ -95,10 +95,10 @@ 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)
+    if (shared.problem !== null)
         return {
             context,
-            result: notesRefusal(cwd, runInput, context.storedRunId, verified, shared.finding),
+            result: notesRefusal(cwd, runInput, context.storedRunId, verified, shared.problem),
         };
     const candidates = summarizeCandidates(context.loaded.bundle);
     if (options.candidate !== undefined &&
@@ -156,27 +156,14 @@ 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) {
+function notesRefusal(cwd, runInput, runId, verified, problem) {
     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.",
-                    },
-            ],
-        },
+        // A draft is written only from share_ready evidence, so any problem in its notes refuses it.
+        shareSafety: { status: "blocked", reasons: [...verified.shareSafety.reasons, problem.reason] },
         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/.`,
@@ -221,7 +208,9 @@ async function isSafeFeedbackEvidenceFile(context, evidencePath) {
         path.isAbsolute(relative)) {
         return false;
     }
-    return (await readContainedRegularFile(context.preparedRunPaths, relative)) !== null;
+    // Evidence a draft cites must be readable: a refused file is listed with the missing ones.
+    const read = await readContainedRegularFile(context.preparedRunPaths, relative, RUN_ARTIFACT_MAX_BYTES);
+    return read.status === "read";
 }
 export async function renderIssueMarkdown(cwdInput, runInput, repo, options = {}) {
     const verified = await verifyFeedbackBound(cwdInput, runInput, options);
@@ -266,9 +255,22 @@ export async function listFeedback(cwdInput, runInput) {
             },
         };
     }
-    const draftBytes = await readContainedRegularFile(context.preparedRunPaths, path.join("feedback", "draft.json"));
-    const draft = draftBytes === null ? undefined : JSON.parse(draftBytes.toString("utf8"));
+    const draftRead = await readContainedRegularFile(context.preparedRunPaths, path.join("feedback", "draft.json"), RUN_ARTIFACT_MAX_BYTES);
     const draftPath = path.join(context.preparedRunPaths.relativeRunRoot, "feedback", "draft.json");
+    if (draftRead.status === "refused")
+        return {
+            schema: FEEDBACK_RESULT_SCHEMA,
+            ok: false,
+            cwd,
+            run: runInput,
+            error: {
+                code: "HUMANISH_INVALID_FEEDBACK_DRAFT",
+                message: `The feedback draft could not be read: ${refusalText(draftPath, draftRead)}.`,
+            },
+        };
+    const draft = draftRead.status === "missing"
+        ? undefined
+        : JSON.parse(draftRead.bytes.toString("utf8"));
     return {
         schema: FEEDBACK_RESULT_SCHEMA,
         ok: true,
@@ -297,10 +299,13 @@ async function resolveFeedbackRunContext(cwd, runInput) {
         const runsRoot = await bindExistingManagedHumanishOutputDirectory(physicalCwd, "runs");
         if (!runsRoot)
             return null;
-        const pointerBytes = await readContainedRegularFile(runsRoot, "latest.json");
-        if (!pointerBytes)
+        const pointerRead = await readContainedRegularFile(runsRoot, "latest.json", LATEST_POINTER_MAX_BYTES);
+        if (pointerRead.status === "missing")
             return null;
-        const pointer = JSON.parse(pointerBytes.toString("utf8"));
+        // A pointer that is there and refused names no run, and saying so beats "run not found".
+        if (pointerRead.status === "refused")
+            throw new ContainedReadRefusedError(path.join(".humanish", "runs", "latest.json"), pointerRead);
+        const pointer = JSON.parse(pointerRead.bytes.toString("utf8"));
         if (typeof pointer.runId !== "string" ||
             typeof pointer.path !== "string" ||
             !resolveLatestRunDirectory(physicalCwd, { path: pointer.path, runId: pointer.runId })) {

package/dist/guest/desktop-keys.js

@@ -3,18 +3,35 @@ import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.
 // hand these strings to xdotool, which has a command language, so only names from these tables
 // ever reach it. The guest runtime ships this module, so it lives in src/guest/, which CI's
 // guest-desktop job and scripts/guest-desktop-proof.mjs key on.
+//
+// The tables take the names in OpenAI's computer-use key map, the names @e2b/desktop's press()
+// mapped (the hosted desktop sent keys through it before), and every printable ASCII
+// punctuation character. xdotool finds the key and the Shift level for a keysym itself, so `?`
+// arrives as `question` with Shift held on an American English keymap.
 /** The modifiers a pointer action may hold, keyed by the upper-cased provider name. */
 const modifierNames = Object.freeze({
     CTRL: "ctrl",
     CONTROL: "ctrl",
     ALT: "alt",
+    OPTION: "alt",
     SHIFT: "shift",
     META: "super",
     SUPER: "super",
     CMD: "super",
+    COMMAND: "super",
+    WIN: "super",
+    WINDOWS: "super",
 });
 const keyNames = Object.freeze({
     ...modifierNames,
+    CONTROL_LEFT: "Control_L",
+    CONTROL_RIGHT: "Control_R",
+    ALT_LEFT: "Alt_L",
+    ALT_RIGHT: "Alt_R",
+    SHIFT_LEFT: "Shift_L",
+    SHIFT_RIGHT: "Shift_R",
+    SUPER_LEFT: "Super_L",
+    SUPER_RIGHT: "Super_R",
     ENTER: "Return",
     RETURN: "Return",
     TAB: "Tab",
@@ -24,11 +41,14 @@ const keyNames = Object.freeze({
     " ": "space",
     BACKSPACE: "BackSpace",
     DELETE: "Delete",
+    DEL: "Delete",
     INSERT: "Insert",
     HOME: "Home",
     END: "End",
     PAGEUP: "Prior",
     PAGEDOWN: "Next",
+    PAGE_UP: "Prior",
+    PAGE_DOWN: "Next",
     ARROWUP: "Up",
     ARROWDOWN: "Down",
     ARROWLEFT: "Left",
@@ -37,18 +57,45 @@ const keyNames = Object.freeze({
     DOWN: "Down",
     LEFT: "Left",
     RIGHT: "Right",
+    CAPS_LOCK: "Caps_Lock",
+    NUM_LOCK: "Num_Lock",
+    SCROLL_LOCK: "Scroll_Lock",
+    PAUSE: "Pause",
+    BREAK: "Pause",
+    PRINT: "Print",
+    MENU: "Menu",
+    "!": "exclam",
+    '"': "quotedbl",
+    "#": "numbersign",
+    $: "dollar",
+    "%": "percent",
+    "&": "ampersand",
+    "'": "apostrophe",
+    "(": "parenleft",
+    ")": "parenright",
+    "*": "asterisk",
     "+": "plus",
-    "-": "minus",
-    "=": "equal",
     ",": "comma",
+    "-": "minus",
     ".": "period",
     "/": "slash",
-    "\\": "backslash",
+    ":": "colon",
     ";": "semicolon",
-    "'": "apostrophe",
+    "<": "less",
+    "=": "equal",
+    ">": "greater",
+    "?": "question",
+    "@": "at",
     "[": "bracketleft",
+    "\\": "backslash",
     "]": "bracketright",
+    "^": "asciicircum",
+    _: "underscore",
     "`": "grave",
+    "{": "braceleft",
+    "|": "bar",
+    "}": "braceright",
+    "~": "asciitilde",
 });
 function lookup(table, key) {
     const upper = key.toUpperCase();
@@ -59,9 +106,16 @@ function chord(names) {
         throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     return names.join("+");
 }
+/**
+ * A name that is itself a chord (`Control+a`, `ctrl++`) split at each plus sign that joins two
+ * names. A lone `+` and a trailing `+` after a joining one are the plus key.
+ */
+function chordParts(key) {
+    return key.length > 1 ? key.split(/\+(?!$)/) : [key];
+}
 /** A keypress chord in xdotool syntax. Unknown or repeated keys are refused before dispatch. */
 export function xdotoolChord(keys) {
-    return chord(keys.map((key) => {
+    return chord(keys.flatMap(chordParts).map((key) => {
         if (/^[a-z0-9]$/i.test(key))
             return key.toLowerCase();
         if (/^F(?:[1-9]|1[0-2])$/i.test(key))

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

@@ -1,3 +1,12 @@
+/** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
+export declare const KEY_VENDORS: string[];
+/** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
+export declare const LISTED_KEYS: {
+    name: string;
+    use: string;
+}[];
+/** The keys `humanish doctor` reports on every run, in its row order. */
+export declare const DOCTOR_KEYS: string[];
 export interface ResolvedKeyFill {
     name: string;
     /** Human-readable source label (a path or command name), never a value. */

package/dist/keys/key-resolution.js

@@ -22,43 +22,61 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { loadEnvFile } from "./env-file.js";
 import { cli } from "../cli/invocation.js";
+import { humanishConfigFile } from "../cli/user-config.js";
 import { OPENAI_EGRESS_PLACEHOLDER } from "../routes/terminal/runtime-auth.js";
-/** The only names implicit discovery may fill (and `humanish keys set` may store). Everything
- *  else in an overlay/store file is ignored-and-named: a repo-planted NODE_OPTIONS/LD_PRELOAD
- *  must never enter process env off a file the operator did not explicitly pass (an explicit
- *  --dotenv remains the operator's own full-file load). */
-const KNOWN_PROVIDER_KEYS = [
-    "OPENAI_API_KEY",
-    "ANTHROPIC_API_KEY",
-    "E2B_API_KEY",
-    "GH_TOKEN",
-    "GITHUB_TOKEN",
-    "CODEX_API_KEY",
-    "AGENTMAIL_API_KEY",
+/**
+ * The provider keys, in the order `humanish keys set` names their vendors. Implicit discovery fills
+ * only these names and the user store holds only these. Everything else in an overlay or store file
+ * is ignored and named: a repo-planted NODE_OPTIONS/LD_PRELOAD must never enter process env off a
+ * file the operator did not explicitly pass (an explicit --dotenv remains the operator's own
+ * full-file load). ANTHROPIC_API_KEY is not listed, and doctor does not report it: 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. Doctor reports AGENTMAIL_API_KEY only under `--study`, for
+ * a study whose email connection names it, since a connection may name another variable.
+ */
+const PROVIDER_KEYS = [
+    {
+        name: "OPENAI_API_KEY",
+        vendor: "openai",
+        listed: { order: 2, use: "participant model and analysis" },
+        doctor: true,
+    },
+    {
+        name: "E2B_API_KEY",
+        vendor: "e2b",
+        login: "e2b auth login",
+        listed: { order: 1, use: "hosted desktops" },
+        doctor: true,
+    },
+    { name: "ANTHROPIC_API_KEY", vendor: "anthropic" },
+    {
+        name: "GH_TOKEN",
+        vendor: "github",
+        login: "gh auth login",
+        listed: { order: 3, use: "private repository subjects" },
+        doctor: true,
+    },
+    { name: "GITHUB_TOKEN", spellingOf: "GH_TOKEN" },
+    { name: "CODEX_API_KEY", doctor: true },
+    { name: "AGENTMAIL_API_KEY", vendor: "agentmail", listed: { order: 4, use: "email in studies" } },
 ];
-const PROVIDER_KEY_SET = new Set(KNOWN_PROVIDER_KEYS);
+const PROVIDER_KEY_SET = new Set(PROVIDER_KEYS.map((key) => key.name));
+const providerKey = (name) => PROVIDER_KEYS.find((key) => key.name === name);
+/** The vendor aliases `humanish keys set` accepts. A raw ENV_NAME is also accepted. */
+export const KEY_VENDORS = PROVIDER_KEYS.flatMap((key) => key.vendor === undefined ? [] : [key.vendor]);
+/** The keys `humanish keys` lists, in its order, each with what humanish uses it for. */
+export const LISTED_KEYS = PROVIDER_KEYS.flatMap(({ name, listed }) => listed === undefined ? [] : [{ name, ...listed }])
+    .sort((a, b) => a.order - b.order)
+    .map(({ name, use }) => ({ name, use }));
+/** The keys `humanish doctor` reports on every run, in its row order. */
+export const DOCTOR_KEYS = PROVIDER_KEYS.flatMap(({ name, doctor }) => (doctor ? [name] : []));
 /** An env for a vendor CLI that discovery runs: the caller's, without any provider key name. */
 function withoutProviderKeys(env) {
     return Object.fromEntries(Object.entries(env).filter(([name]) => !PROVIDER_KEY_SET.has(name)));
 }
-/** `humanish keys set <vendor>` aliases; a raw ENV_NAME is also accepted. */
-const KEY_VENDOR_ALIASES = {
-    openai: "OPENAI_API_KEY",
-    e2b: "E2B_API_KEY",
-    anthropic: "ANTHROPIC_API_KEY",
-    github: "GH_TOKEN",
-    agentmail: "AGENTMAIL_API_KEY",
-};
 const PROJECT_OVERLAY_RELATIVE = path.join(".humanish", "local", "provider.env");
 export function userKeyStorePath(env, deps = {}) {
-    const home = deps.homeDir ?? homedir();
-    const declared = env.XDG_CONFIG_HOME?.trim();
-    // The XDG spec: a relative XDG_CONFIG_HOME must be ignored. Honoring one would make the
-    // key store cwd-relative: `humanish keys set` would write a secret into the current repo.
-    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
-        ? declared
-        : path.join(home, ".config");
-    return path.join(configHome, "humanish", "keys.env");
+    return humanishConfigFile(env, "keys.env", deps.homeDir);
 }
 function e2bConfigPath(deps) {
     return path.join(deps.homeDir ?? homedir(), ".e2b", "config.json");
@@ -235,21 +253,10 @@ function storeLabel(env, deps) {
 /** The nearest fill instruction for a missing key. Doctor rows use it, and it is appended to
  *  *_KEYS_MISSING errors so the failure names the fix. */
 export function missingKeyHint(name) {
-    switch (name) {
-        case "E2B_API_KEY":
-            return `run \`e2b auth login\`, or \`${cli("keys set e2b")}\``;
-        case "GH_TOKEN":
-        case "GITHUB_TOKEN":
-            return `run \`gh auth login\`, or \`${cli("keys set github")}\``;
-        case "OPENAI_API_KEY":
-            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}`)}\``;
-    }
+    const named = providerKey(name);
+    const key = named?.spellingOf === undefined ? named : providerKey(named.spellingOf);
+    const set = `\`${cli(`keys set ${key?.vendor ?? name}`)}\``;
+    return key?.login === undefined ? `run ${set}` : `run \`${key.login}\`, or ${set}`;
 }
 /** One shared suffix for *_KEYS_MISSING messages: where discovery looked, and what fills each
  *  missing key. Pure text; never values. */
@@ -281,19 +288,18 @@ export async function probeKeySources(names, args) {
         ...(args.deps === undefined ? {} : { deps: args.deps }),
     });
     const bySource = new Map(fills.map((fill) => [fill.name, fill.source]));
+    const setInEnv = (name) => args.env[name] !== undefined && args.env[name]?.trim() !== "";
     return names.map((name) => {
-        const inEnv = args.env[name] !== undefined && args.env[name]?.trim() !== "" && !placeholder(name);
-        // GH_TOKEN and GITHUB_TOKEN are one credential with two spellings; a doctor row that says
-        // "missing" while GITHUB_TOKEN sits in the env would be wrong.
-        const aliasInEnv = name === "GH_TOKEN" &&
-            args.env.GITHUB_TOKEN !== undefined &&
-            args.env.GITHUB_TOKEN.trim() !== "";
+        const inEnv = setInEnv(name) && !placeholder(name);
+        // A second spelling of the key in the env, such as GITHUB_TOKEN for GH_TOKEN, is the same
+        // credential; a doctor row that says "missing" while it sits in the env would be wrong.
+        const spelling = PROVIDER_KEYS.find((key) => key.spellingOf === name && setInEnv(key.name))?.name;
         const source = inEnv
             ? args.dotenv?.names.includes(name)
                 ? `--dotenv ${args.dotenv.path}`
                 : "process env"
-            : aliasInEnv
-                ? "process env (GITHUB_TOKEN)"
+            : spelling !== undefined
+                ? `process env (${spelling})`
                 : (bySource.get(name) ?? null);
         return {
             name,
@@ -306,9 +312,10 @@ export async function probeKeySources(names, args) {
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Resolve a `humanish keys set` target: a vendor alias or a raw env name. Null = invalid. */
 export function resolveKeyName(vendorOrName) {
-    const alias = KEY_VENDOR_ALIASES[vendorOrName.toLowerCase()];
-    if (alias !== undefined)
-        return alias;
+    const vendor = vendorOrName.toLowerCase();
+    const key = PROVIDER_KEYS.find((candidate) => candidate.vendor === vendor);
+    if (key !== undefined)
+        return key.name;
     return ENV_NAME.test(vendorOrName) ? vendorOrName : null;
 }
 /** Write one key into the user store (0700 dir, 0600 file). Only allowlisted provider names

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

@@ -10,6 +10,8 @@ export declare function keyStatus(args: {
 }): 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[];
+/** The line `humanish keys` prints for one key: what it is for, and its source or how to add it. */
+export declare function keyStatusLine(row: KeyStatusRow): string;
 export declare function formatKeyStatus(rows: readonly KeyStatusRow[], otherStored?: readonly string[]): string;
 interface MissingKeysOutcome {
     stored: string[];

package/dist/keys/key-status.js

@@ -1,33 +1,26 @@
 // `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" },
-];
+import { LISTED_KEYS, listUserKeys, probeKeySources, setUserKey, } from "./key-resolution.js";
 export async function keyStatus(args) {
-    const probes = await probeKeySources(STATUS_KEYS.map((key) => key.name), {
+    const probes = await probeKeySources(LISTED_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 }));
+    return probes.map((probe, index) => ({ ...probe, use: LISTED_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));
+    const listed = new Set(LISTED_KEYS.map((key) => key.name));
     return listUserKeys(env, deps).filter((name) => !listed.has(name));
 }
+/** The line `humanish keys` prints for one key: what it is for, and its source or how to add it. */
+export function keyStatusLine(row) {
+    return `${row.name} (${row.use}): ${row.source === null ? `missing; ${row.hint}` : `set, from ${row.source}`}`;
+}
 export function formatKeyStatus(rows, otherStored = []) {
-    const lines = rows.map((row) => `${row.name} (${row.use}): ${row.source === null ? `missing; ${row.hint}` : `set, from ${row.source}`}`);
+    const lines = rows.map(keyStatusLine);
     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);

package/dist/observer/artifact.d.ts

@@ -1,5 +1,5 @@
 import type { LoadedAnalysis } from "../analysis/types.js";
-import type { RunNotes } from "../run/notes.js";
+import type { RunNotes } from "../run/note-files.js";
 import { type ObserverData } from "./data.js";
 /**
  * Resolve (and in a repo checkout, build) the Observer artifact before any run or

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

@@ -1,6 +1,5 @@
 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;

package/dist/observer/notes-route.js

@@ -5,13 +5,25 @@
 // 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 { 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 } from "./http.js";
-export const NOTES_PATH = "/api/notes";
-const TOKEN_HEADER = "x-humanish-notes-token";
+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,
@@ -40,26 +52,6 @@ function reply(response, status, body, close = false) {
 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;
@@ -67,8 +59,8 @@ function sameToken(sent, token) {
     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) {
+/** 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"));
@@ -76,20 +68,8 @@ function noteInput(body) {
     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,
-    };
+    const parsed = noteRequestSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
 }
 export function createNotesWriter(options) {
     const token = randomBytes(32).toString("base64url");
@@ -111,17 +91,17 @@ export function createNotesWriter(options) {
                 !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))
+            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 readBody(request);
+            const body = await readBodyAtMost(request, MAX_BODY_BYTES);
             if (body === null)
                 return tooLarge();
-            const input = noteInput(body);
+            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);