humanish 0.114.0 → 0.115.0

package/dist/feedback/draft.js

@@ -2,6 +2,7 @@
 // participant's feedback candidate or from a reviewed analysis finding, and its markdown rendering.
 // The commands that resolve the run and read or write drafts are in feedback.ts.
 import path from "node:path";
+import { findingLead } from "../analysis/finding-lead.js";
 import { analysisSharingProblems } from "../analysis/sharing.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { hashAnalysisValue } from "../analysis/validation.js";
@@ -9,7 +10,9 @@ import { formatParticipantOutcomes, formatRunTaskFunnel, participantOutcomeDetai
 import { loadRunBundlePrepared } from "../run/locate.js";
 import { isFeedbackIdempotencyKey } from "../run/feedback-shape.js";
 import { runNoteFile } from "../run/note-files.js";
-import { formatRunTime, runParticipantCaptions } from "../run/notes.js";
+import { byRunTime } from "../run/note-shape.js";
+import { formatRunTime } from "../run/notes.js";
+import { runParticipantCaptions } from "../run/participant-records.js";
 import { isRecord } from "../run/type-guards.js";
 import { feedbackProofCommands, projectFeedbackAcceptanceProof } from "./proof.js";
 export const FEEDBACK_SCHEMA = "humanish.feedback.v1";
@@ -122,8 +125,10 @@ export async function buildAnalysisDraft(context, options) {
     const root = path.dirname(context.loaded.bundlePath);
     const evidenceIds = new Set(finding.observations.flatMap((item) => item.evidenceIds));
     const evidence = analysis.evidence.filter((item) => evidenceIds.has(item.id));
-    const amended = correction?.status === "amended";
-    const claim = amended ? correction.replacementClaim : (finding.headline ?? finding.title);
+    const lead = findingLead(finding, correction);
+    // An analysis written before headlines has no lead, so the amended claim or the title names it.
+    const amendedClaim = correction?.status === "amended" ? correction.replacementClaim : null;
+    const claim = lead?.headline ?? amendedClaim ?? finding.title;
     const firstLine = claim.trim().split(/\r?\n/)[0] || `Reviewed finding ${finding.id}`;
     const summary = Array.from(firstLine).length > 160
         ? Array.from(firstLine).slice(0, 159).join("") + "…"
@@ -147,19 +152,11 @@ export async function buildAnalysisDraft(context, options) {
         summary,
         expected: "Review the cited behavior against the participant assignment and confirm the expected product behavior.",
         actual: [
-            // The plain account leads; an amendment makes it stale, so the draft says so in its place.
-            ...(finding.headline === undefined
-                ? []
-                : amended
-                    ? [
-                        "This finding was corrected in human review. The reviewer's claim above replaces its original headline and account.",
-                        "",
-                    ]
-                    : finding.experience === undefined
-                        ? []
-                        : [finding.experience, ""]),
+            ...(lead?.account ? [lead.account, ""] : []),
             "Independent study analysis; does not replace participant feedback or recorded completion outcomes.",
-            amended ? `Amended claim: ${claim}. Original analysis: ${finding.summary}` : finding.summary,
+            amendedClaim === null
+                ? finding.summary
+                : `Amended claim: ${amendedClaim}. Original analysis: ${finding.summary}`,
             `Impact: ${finding.impact}. ${finding.affectedStreamIds.length} affected / ${finding.exposedStreamIds.length} observed exposed participants. ${finding.exposureReason}`,
             `Recovery: ${finding.recovery}. Confidence: ${finding.confidence}.`,
             ...finding.observations.map((item) => `${item.basis}: ${item.claim}${item.limitation ? ` Limitation: ${item.limitation}` : ""}`),
@@ -234,7 +231,7 @@ export function withReviewerNotes(draft, notes, bundle, runRoot) {
     if (notes === null || notes.notes.length === 0)
         return draft;
     const captions = runParticipantCaptions(bundle);
-    const ordered = [...notes.notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
+    const ordered = byRunTime(notes.notes);
     return {
         ...draft,
         evidence: [

package/dist/feedback/export-bundle.js

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

package/dist/feedback/export.js

@@ -19,7 +19,7 @@ import { verifyRun } from "../verify/verify.js";
 import {} from "../run/bundle.js";
 import { exportRedactedBundle } from "./export-bundle.js";
 import { loadAnalysis } from "../analysis/load.js";
-import { readNotesForSharing } from "../run/notes.js";
+import { readNotesForSharing } from "../run/note-files.js";
 import { cli } from "../cli/invocation.js";
 import { analysisSharingProblems } from "../analysis/sharing.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "../analysis/evidence.js";
@@ -288,7 +288,10 @@ function makePortable(inlined, verified) {
             }
         }
     }
-    // What verify said, in the file, so the chrome can agree with the result envelope.
+    recordShareSafety(inlined, verified);
+}
+/** What verify said, in the file, so the chrome can agree with the result envelope. */
+function recordShareSafety(inlined, verified) {
     const publicSafety = (inlined.publicSafety ?? {});
     inlined.publicSafety = {
         ...publicSafety,
@@ -299,6 +302,23 @@ function makePortable(inlined, verified) {
         },
     };
 }
+/**
+ * Adds a failed sharing check to verify's result. The reason joins verify's reasons and the status
+ * is the worse of the two, as verify grades an analysis. The export is refused unless --local-only,
+ * which writes the new status into the file.
+ */
+function applySharingProblem(verified, inlined, options, problem) {
+    verified.shareSafety = {
+        status: problem.status === "blocked" || verified.shareSafety.status === "blocked"
+            ? "blocked"
+            : "local_only",
+        reasons: [...verified.shareSafety.reasons, problem.reason],
+    };
+    if (options.localOnly !== true)
+        return "blocked";
+    recordShareSafety(inlined, verified);
+    return "downgraded";
+}
 /**
  * Revalidates the analysis against source evidence and its sharing checks. A failed check
  * downgrades share safety, which only --local-only may export.
@@ -322,24 +342,13 @@ async function recheckAnalysis(runPaths, analysis, verified, inlined, options) {
     const analysisSharing = analysisSharingProblems(analysis);
     if (!analysisSharing.sensitive && !analysisSharing.unverified)
         return "ok";
-    verified.shareSafety = {
+    return applySharingProblem(verified, inlined, options, {
         status: analysisSharing.sensitive ? "blocked" : "local_only",
-        reasons: [
-            ...verified.shareSafety.reasons,
-            {
-                code: "ANALYSIS_UNVERIFIED",
-                message: "The exact analysis snapshot being exported did not pass sharing checks.",
-            },
-        ],
-    };
-    if (options.localOnly !== true)
-        return "blocked";
-    inlined.publicSafety.share = {
-        status: verified.shareSafety.status,
-        verifiedAt: new Date().toISOString(),
-        reasons: verified.shareSafety.reasons.map((reason) => reason.code),
-    };
-    return "downgraded";
+        reason: {
+            code: "ANALYSIS_UNVERIFIED",
+            message: "The exact analysis snapshot being exported did not pass sharing checks.",
+        },
+    });
 }
 /**
  * The run's notes for the export, read once within the notes size limit. That snapshot is scanned
@@ -347,36 +356,13 @@ async function recheckAnalysis(runPaths, analysis, verified, inlined, options) {
  * reach the file unchecked. A finding blocks the export, or downgrades it under --local-only.
  */
 async function checkedNotes(runPaths, verified, inlined, options, warnings) {
-    const { notes, finding } = await readNotesForSharing(runPaths);
+    const { notes, problem } = await readNotesForSharing(runPaths);
     for (const skipped of notes.skipped)
         warnings.push(`Reviewer notes: ${skipped}`);
-    if (finding === null)
-        return { notes, check: "ok" };
-    verified.shareSafety = {
-        status: finding === "sensitive" || verified.shareSafety.status === "blocked"
-            ? "blocked"
-            : "local_only",
-        reasons: [
-            ...verified.shareSafety.reasons,
-            finding === "sensitive"
-                ? {
-                    code: "PUBLIC_SAFETY_FINDINGS",
-                    message: "The reviewer notes being exported match secret, token or local-path patterns.",
-                }
-                : {
-                    code: "UNSCANNED_ARTIFACT",
-                    message: "The reviewer notes being exported hold encoded text the scan cannot read.",
-                },
-        ],
-    };
-    if (options.localOnly !== true)
-        return { notes, check: "blocked" };
-    inlined.publicSafety.share = {
-        status: verified.shareSafety.status,
-        verifiedAt: new Date().toISOString(),
-        reasons: verified.shareSafety.reasons.map((reason) => reason.code),
+    return {
+        notes,
+        check: problem === null ? "ok" : applySharingProblem(verified, inlined, options, problem),
     };
-    return { notes, check: "downgraded" };
 }
 /** The portable Observer HTML, with the local-only banner when the export is watermarked. */
 function renderExportHtml(inlined, review, assets, verified, watermarked, omittedRecording) {

package/dist/feedback/feedback.js

@@ -6,7 +6,7 @@ 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 { 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/.`,

package/dist/keys/key-resolution.js

@@ -22,6 +22,7 @@ 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
@@ -41,24 +42,18 @@ const PROVIDER_KEY_SET = new Set(KNOWN_PROVIDER_KEYS);
 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",
-};
+/** `humanish keys set <vendor>` aliases; a raw ENV_NAME is also accepted. A Map, so a name such as
+ * `constructor` is no alias. */
+const KEY_VENDOR_ALIASES = new Map([
+    ["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");
@@ -306,7 +301,7 @@ 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()];
+    const alias = KEY_VENDOR_ALIASES.get(vendorOrName.toLowerCase());
     if (alias !== undefined)
         return alias;
     return ENV_NAME.test(vendorOrName) ? vendorOrName : 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);

package/dist/observer/pinned-files.js

@@ -5,6 +5,7 @@ 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";
 /**
  * The file's bytes, or null when it cannot be read under the root's checks. With `maxBytes`, a
@@ -18,7 +19,9 @@ export async function readContainedFile(root, filePathInput, options = {}) {
     try {
         const body = options.maxBytes === undefined
             ? await opened.handle.readFile()
-            : await readAtMost(opened.handle, opened.size, options.maxBytes);
+            : 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.
@@ -79,24 +82,6 @@ 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,14 +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/notes.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 { createNotesWriter, NOTES_PATH } from "./notes-route.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";

package/dist/observer/run-routes.js

@@ -9,7 +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 { decodeRunNote, listNoteEntries, MAX_NOTE_FILE_BYTES, noteListing, RUN_NOTES_DIR, runNoteFile, } from "../run/note-files.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";
@@ -59,33 +59,18 @@ async function readServedAnalysisSpend(runRoot) {
     }
 }
 /**
- * The run's reviewer notes as served: notes/ listed, and each note file read within
- * MAX_NOTE_FILE_BYTES through the root's checks, so a --safe root's admission and hash checks
- * apply to every note. A file that is not a readable note of the run is skipped and counted.
+ * 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.
  */
-async function readServedNotes(runRoot) {
-    const runId = path.basename(runRoot.physicalPath);
-    let listing;
-    try {
-        await assertPinnedDirectory(runRoot);
-        listing = await listNoteEntries(path.join(runRoot.physicalPath, RUN_NOTES_DIR));
-    }
-    catch {
-        return { runId, notes: [], skipped: [`${RUN_NOTES_DIR} is not a plain folder.`] };
-    }
-    if (listing === null)
-        return { runId, notes: [], skipped: [] };
-    const { ids, skipped } = noteListing(listing);
-    const notes = [];
-    for (const id of ids) {
-        const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, runNoteFile(id)), { maxBytes: MAX_NOTE_FILE_BYTES });
-        const note = bytes === null ? null : decodeRunNote(bytes, runId, id);
-        if (note === null)
-            skipped.push(`${runNoteFile(id)} was skipped.`);
-        else
-            notes.push(note);
-    }
-    return { runId, notes, skipped };
+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
@@ -120,7 +105,7 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
             return;
         }
         const analysis = await readObserverAnalysis(runRoot);
-        const notes = await readServedNotes(runRoot);
+        const notes = await readRunNotes(servedNoteFiles(runRoot));
         writeResponse(response, 200, renderObserverHtml(observerData, {
             analysis,
             notes,

package/dist/observer/serve.js

@@ -3,7 +3,8 @@ 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 { createNotesWriter, NOTES_PATH } from "./notes-route.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";