humanish 0.113.0 → 0.115.0

package/dist/evidence/secret-scrub.js

@@ -2,10 +2,14 @@
 // run's warnings. A value is found as written and in the encoded forms an HTTP client, a log line or
 // a JSON body gives it, so a token that reaches the text percent-encoded or base64-encoded is still
 // removed. Pattern redaction (redactText) runs after this and finds secrets by shape.
-import { decodeEscapes } from "./encoded-text.js";
-const REDACTED = "[REDACTED_SECRET]";
-// A marker already in the text, from this scrub or from redactText. No value is matched inside one.
-const MARKER = /\[REDACTED_[A-Z0-9_]+\]/g;
+import { escapeRegExp } from "../run/text.js";
+import { decodeEscapes, latin1RunsAsUtf8, readingsOf } from "./encoded-text.js";
+import { REDACTION_MARKERS } from "./redaction.js";
+const REDACTED = REDACTION_MARKERS.secret;
+// A form wholly inside a marker humanish writes is the marker's own text, as when a value is part
+// of the marker's name. Other bracketed text, such as `[REDACTED_373433393231]`, is searched like
+// any text.
+const MARKER = new RegExp(Object.values(REDACTION_MARKERS).map(escapeRegExp).join("|"), "g");
 // The shortest encoded form searched for. Shorter base64 or hex runs are ordinary text often enough
 // that matching them would redact words. A value itself is searched for at any length.
 const MIN_ENCODED_FORM = 8;
@@ -27,7 +31,9 @@ function base64Middles(bytes, encoding) {
 }
 /**
  * A value as written, and percent-encoded, JSON-escaped once (also with non-ASCII characters as
- * `\u` escapes) and twice, base64 at each byte offset, base64url and hex. Twice, because a JSON event can carry a command's JSON output as a string. An
+ * `\u` escapes) and twice, its UTF-8 bytes read one per character and the reverse, base64 at each
+ * byte offset, base64url and hex. Twice, because a JSON event can carry a command's JSON output as
+ * a string. An
  * escaped form is searched for at any length, as the value is: it holds a backslash or a `%`, so it
  * is not ordinary text.
  */
@@ -52,33 +58,122 @@ export function encodedForms(value) {
         ...base64Middles(bytes, "base64"),
         ...base64Middles(bytes, "base64url"),
     ];
+    // decodeEscapes reads each percent escape as one character, so a percent-encoded non-ASCII value
+    // reads as its UTF-8 bytes one per character, é as é.
+    const bytewise = bytes.toString("latin1");
+    if (bytewise !== value)
+        escaped.push(bytewise);
+    // The mirror: a value such as xéz€ whose characters include bytes that read as UTF-8, written
+    // with them read (xéz€). No reading of the text turns xéz€ back into the value.
+    const mirrored = latin1RunsAsUtf8(value);
+    if (mirrored !== value)
+        escaped.push(mirrored);
     return [value, ...escaped, ...binary.filter((form) => form.length >= MIN_ENCODED_FORM)];
 }
-/** Every occurrence of every form, outside the markers, merged where they overlap or touch. */
-function secretSpans(text, forms) {
+/**
+ * Whether [at, end) lies wholly inside one marker. The markers are one regex's matches, so they are
+ * sorted and disjoint: only the first marker that ends after `at` can hold it.
+ */
+function insideMarker(markers, at, end) {
+    let low = 0;
+    let high = markers.length;
+    while (low < high) {
+        const middle = (low + high) >> 1;
+        if (markers[middle][1] > at)
+            high = middle;
+        else
+            low = middle + 1;
+    }
+    return low < markers.length && markers[low][0] <= at && end <= markers[low][1];
+}
+/**
+ * The Knuth-Morris-Pratt failure table: entry `k` is the length of the longest proper prefix of
+ * the form's first `k` characters that is also their suffix.
+ */
+function failureTable(form) {
+    const table = new Int32Array(form.length + 1);
+    for (let at = 1, length = 0; at < form.length; at += 1) {
+        while (length > 0 && form[at] !== form[length])
+            length = table[length];
+        if (form[at] === form[length])
+            length += 1;
+        table[at + 1] = length;
+    }
+    return table;
+}
+/**
+ * Calls `found` with the start of every occurrence of the form, overlapping ones included, in time
+ * linear in the text. indexOf skips to the next occurrence. After one, the failure table carries
+ * the match on through the occurrences that overlap it, so no character is compared again, until
+ * no prefix of the form is left matched and indexOf takes over.
+ */
+function eachOccurrence(text, form, found) {
+    let table;
+    for (let at = text.indexOf(form); at !== -1;) {
+        found(at);
+        table ??= failureTable(form);
+        let matched = table[form.length];
+        let next = at + form.length;
+        for (; matched > 0 && next < text.length; next += 1) {
+            while (matched > 0 && text[next] !== form[matched])
+                matched = table[matched];
+            if (text[next] === form[matched])
+                matched += 1;
+            if (matched === form.length) {
+                found(next + 1 - form.length);
+                matched = table[form.length];
+            }
+        }
+        at = matched > 0 ? -1 : text.indexOf(form, next);
+    }
+}
+/** Every occurrence of every form not wholly inside a marker, in no order. */
+function occurrences(text, forms) {
     const markers = [];
     for (const match of text.matchAll(MARKER)) {
         const start = match.index ?? 0;
         markers.push([start, start + match[0].length]);
     }
+    const found = [];
+    for (const form of forms)
+        eachOccurrence(text, form, (at) => {
+            if (!insideMarker(markers, at, at + form.length))
+                found.push([at, at + form.length]);
+        });
+    return found;
+}
+/** The occurrences sorted and merged where they overlap or touch. */
+function merged(found) {
+    found.sort((left, right) => left[0] - right[0]);
     const spans = [];
-    for (const form of forms) {
-        for (let at = text.indexOf(form); at !== -1; at = text.indexOf(form, at + 1)) {
-            const end = at + form.length;
-            if (!markers.some(([start, stop]) => at < stop && end > start))
-                spans.push([at, end]);
-        }
-    }
-    spans.sort((left, right) => left[0] - right[0]);
-    const merged = [];
-    for (const span of spans) {
-        const last = merged.at(-1);
+    for (const span of found) {
+        const last = spans.at(-1);
         if (last !== undefined && span[0] <= last[1])
             last[1] = Math.max(last[1], span[1]);
         else
-            merged.push([span[0], span[1]]);
+            spans.push([span[0], span[1]]);
     }
-    return merged;
+    return spans;
+}
+function replaceSpans(text, spans) {
+    let result = "";
+    let cursor = 0;
+    for (const [start, end] of spans) {
+        result += text.slice(cursor, start) + REDACTED;
+        cursor = end;
+    }
+    return result + text.slice(cursor);
+}
+const formsOf = (values) => [
+    ...new Set(values.filter((value) => value.length > 0).flatMap(encodedForms)),
+];
+/**
+ * A check that the text holds one of the values' forms outside the markers in any of its
+ * readingsOf. A scrub's output must pass it.
+ */
+export function holdsSecretValue(values) {
+    const forms = formsOf(values);
+    return (text) => readingsOf(text).some((reading) => occurrences(reading, forms).length > 0);
 }
 /**
  * A scrub that replaces each non-empty value and its encoded forms with `[REDACTED_SECRET]`. Every
@@ -87,19 +182,21 @@ function secretSpans(text, forms) {
  * through decodeEscapes, the decoder verify uses, and returns the decoded text: a warning with
  * percent-encoding, JSON escapes or HTML references shows them decoded, with the values removed.
  * That finds a value written partly encoded, which no single encoded form matches.
+ *
+ * The result's other readingsOf only detect. If one still holds a form, the scrub returns
+ * `[REDACTED_SECRET]` in place of the whole text. That happens for a value encoded twice, which
+ * the decoded text shows encoded once; for a value the UTF-8 or transfer reading holds, such as
+ * one with one of two non-ASCII characters percent-encoded; and for a value that holds part of a
+ * marker, such as `ET]x`, which the marker that replaced it can spell again.
  */
 export function scrubSecretValues(values) {
-    const forms = [...new Set(values.filter((value) => value.length > 0).flatMap(encodedForms))];
+    const forms = formsOf(values);
     if (forms.length === 0)
         return (text) => text;
+    const holds = holdsSecretValue(values);
     return (text) => {
         const decoded = decodeEscapes(text);
-        let result = "";
-        let cursor = 0;
-        for (const [start, end] of secretSpans(decoded, forms)) {
-            result += decoded.slice(cursor, start) + REDACTED;
-            cursor = end;
-        }
-        return result + decoded.slice(cursor);
+        const result = replaceSpans(decoded, merged(occurrences(decoded, forms)));
+        return holds(result) ? REDACTED : result;
     };
 }

package/dist/feedback/draft.d.ts

@@ -1,6 +1,7 @@
 import type { RunBundle, RunFeedbackCandidate } from "../run/bundle.js";
 import type { PreparedRunArtifactPaths } from "../run/paths.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
+import { type RunNotes } from "../run/note-files.js";
 export declare const FEEDBACK_SCHEMA = "humanish.feedback.v1";
 export interface FeedbackDraft {
     schema: typeof FEEDBACK_SCHEMA;
@@ -35,6 +36,19 @@ export interface FeedbackDraft {
     idempotency_key: string;
     proposed_next_state: RunFeedbackCandidate["proposed_next_state"];
     acceptance_proof: string[];
+    /** Notes a person added while reviewing the recording, in run clock order. Absent with none. */
+    reviewer_notes?: Array<{
+        id: string;
+        /** The moment on the run clock, as the Observer shows it: `02:31`. */
+        at: string;
+        at_ms: number;
+        /** The stream id the note file records, or null for a note on the whole run. */
+        participant: string | null;
+        /** The participant's caption, as the Observer names it. */
+        participant_caption: string | null;
+        author: string;
+        text: string;
+    }>;
 }
 export interface FeedbackDraftOptions {
     /** A candidate id from `feedback list`. Absent: the first usable candidate, as before. */
@@ -53,6 +67,11 @@ export interface FeedbackRunContext {
 }
 export declare function buildDraft(bundle: RunBundle, bundlePath: string, candidateId?: string): FeedbackDraft;
 export declare function buildAnalysisDraft(context: FeedbackRunContext, options: FeedbackDraftOptions): Promise<FeedbackDraft | null>;
+/**
+ * The draft with the run's reviewer notes and each note's file cited. The caller passes the set it
+ * read and checked for sharing (readNotesForSharing).
+ */
+export declare function withReviewerNotes(draft: FeedbackDraft, notes: RunNotes | null, bundle: RunBundle, runRoot: string): FeedbackDraft;
 export declare function isUsableFeedbackCandidate(candidate: unknown): candidate is RunFeedbackCandidate;
 export declare function renderMarkdown(draft: FeedbackDraft, repo: string): string;
 export {};

package/dist/feedback/draft.js

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

package/dist/feedback/export-bundle.js

@@ -10,7 +10,7 @@ import { renderObserver } from "../observer/render.js";
 import { buildObserverData } from "../observer/data.js";
 import { inventorySandboxIds, scrubSandboxIdBytes } from "../run/sandbox-ids.js";
 import { containsSensitive, redactSandboxIds, redactScreenshot, redactText, } from "../evidence/redaction.js";
-import { decodeEscapes } from "../evidence/encoded-text.js";
+import { decodeEscapes, 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 (containsSensitive(text) || containsSensitive(decoded))
+    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,6 +19,8 @@ import { verifyRun } from "../verify/verify.js";
 import {} from "../run/bundle.js";
 import { exportRedactedBundle } from "./export-bundle.js";
 import { loadAnalysis } from "../analysis/load.js";
+import { readNotesForSharing } from "../run/note-files.js";
+import { cli } from "../cli/invocation.js";
 import { analysisSharingProblems } from "../analysis/sharing.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "../analysis/evidence.js";
 import { readBoundedFile } from "../run/evidence-files.js";
@@ -96,8 +98,13 @@ export async function exportRun(cwdInput, runInput, options = {}, deps = {}) {
     if (analysisCheck === "downgraded")
         shareReady = false;
     warnings.push(...analysis.warnings);
+    const notes = await checkedNotes(runPaths, verified, inlined, options, warnings);
+    if (notes.check === "blocked")
+        return exportFailure(cwd, runInput, "HUMANISH_EXPORT_SHARE_SAFETY_BLOCKED", `The run's reviewer notes hold text that looks like a secret, a token or a local path, which verify may not have seen if a note was added or changed after it ran. Run \`${cli(`verify --run ${runId}`)}\`, fix the note files in notes/, and export again.`, verified.shareSafety);
+    if (notes.check === "downgraded")
+        shareReady = false;
     const watermarked = !shareReady || omittedRecording;
-    const output = renderExportHtml(inlined, analysis, assets, verified, watermarked, omittedRecording);
+    const output = renderExportHtml(inlined, { analysis, notes: notes.notes }, assets, verified, watermarked, omittedRecording);
     const bytes = Buffer.byteLength(output, "utf8");
     const maxBytes = options.maxBytes ?? DEFAULT_EXPORT_MAX_BYTES;
     if (bytes > maxBytes) {
@@ -281,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,
@@ -292,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.
@@ -315,30 +342,33 @@ 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),
+        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
+ * as verify scans run text and is the one rendered, so a note added or changed after verify ran cannot
+ * reach the file unchecked. A finding blocks the export, or downgrades it under --local-only.
+ */
+async function checkedNotes(runPaths, verified, inlined, options, warnings) {
+    const { notes, problem } = await readNotesForSharing(runPaths);
+    for (const skipped of notes.skipped)
+        warnings.push(`Reviewer notes: ${skipped}`);
+    return {
+        notes,
+        check: problem === null ? "ok" : applySharingProblem(verified, inlined, options, problem),
     };
-    return "downgraded";
 }
 /** The portable Observer HTML, with the local-only banner when the export is watermarked. */
-function renderExportHtml(inlined, analysis, assets, verified, watermarked, omittedRecording) {
+function renderExportHtml(inlined, review, assets, verified, watermarked, omittedRecording) {
     const output = renderObserverHtml(inlined, {
         snapshot: true,
-        analysis,
+        ...review,
         assets,
     });
     if (!watermarked)

package/dist/feedback/feedback.js

@@ -6,8 +6,10 @@ import path from "node:path";
 import { bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { bindExistingManagedHumanishOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
+import { readNotesForSharing } from "../run/note-files.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.problem !== null)
+        return {
+            context,
+            result: notesRefusal(cwd, runInput, context.storedRunId, verified, shared.problem),
+        };
     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,21 @@ 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, problem) {
+    return {
+        schema: FEEDBACK_RESULT_SCHEMA,
+        ok: false,
+        cwd,
+        run: runInput,
+        // 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/.`,
+        },
+    };
+}
 export async function verifyFeedback(cwdInput, runInput, options = {}) {
     return (await verifyFeedbackBound(cwdInput, runInput, options)).result;
 }

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,4 +1,5 @@
 import type { LoadedAnalysis } from "../analysis/types.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
@@ -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;