humanish 0.112.0 → 0.114.0

package/dist/cli/update-check.js

@@ -0,0 +1,203 @@
+// Tells a person when a newer humanish is published, as npm, gh and the Vercel CLI do. A command
+// only reads a small cache and prints at most one line from it; the registry request runs in a
+// detached process that writes the cache for a later command, so the check never delays or fails
+// the command that started it.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { disabledByEnvironment } from "./telemetry.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_DIST_TAGS = "https://registry.npmjs.org/-/package/humanish/dist-tags";
+/** Next to telemetry.json, under the same XDG rule the key store uses. */
+function updateCachePath(env, home = homedir()) {
+    const declared = env.XDG_CONFIG_HOME?.trim();
+    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
+        ? declared
+        : path.join(home, ".config");
+    return path.join(configHome, "humanish", "update-check.json");
+}
+function readUpdateCache(cachePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return {};
+        const record = parsed;
+        const text = (field) => typeof record[field] === "string" ? record[field] : undefined;
+        const cache = {};
+        const checkedAt = text("checkedAt");
+        const latest = text("latest");
+        const notifiedAt = text("notifiedAt");
+        if (checkedAt !== undefined)
+            cache.checkedAt = checkedAt;
+        if (latest !== undefined && parseVersion(latest) !== undefined)
+            cache.latest = latest;
+        if (notifiedAt !== undefined)
+            cache.notifiedAt = notifiedAt;
+        return cache;
+    }
+    catch {
+        return {};
+    }
+}
+function writeUpdateCache(cachePath, cache) {
+    mkdirSync(path.dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+function parseVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+    return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `candidate` is a higher release than `installed`. */
+function isNewer(candidate, installed) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(installed);
+    if (a === undefined || b === undefined)
+        return false;
+    for (let index = 0; index < 3; index += 1)
+        if (a[index] !== b[index])
+            return a[index] > b[index];
+    return false;
+}
+/** True when `timestamp` is missing, unreadable, or at least a day before `now`. */
+function dayPassed(timestamp, now) {
+    const then = timestamp === undefined ? Number.NaN : Date.parse(timestamp);
+    return Number.isNaN(then) || now - then >= DAY_MS;
+}
+const truthy = (value) => value !== undefined &&
+    value.trim() !== "" &&
+    value.trim() !== "0" &&
+    value.trim().toLowerCase() !== "false";
+/**
+ * Only a person at a terminal is told, and only when nothing has switched the check off. A pipe,
+ * CI and a JSON document have a program reading them. A study participant runs the version the
+ * study chose, and a notice would send it to another. The telemetry switches turn this off too:
+ * someone who opted out of telemetry expects no unprompted requests.
+ */
+function checkAllowed(context) {
+    const env = context.env;
+    return (context.terminal &&
+        !context.json &&
+        !context.ownCheckout &&
+        !truthy(env.CI) &&
+        !truthy(env.HUMANISH_NO_UPDATE_CHECK) &&
+        !truthy(env.HUMANISH_STUDY_PARTICIPANT) &&
+        !disabledByEnvironment(env));
+}
+/**
+ * The one line to print after a command when the cache names a newer humanish, at most once a day.
+ * Records that it was shown. Every failure inside is swallowed: an update notice is never a reason
+ * for a command to fail.
+ */
+export function checkForUpdate(context) {
+    try {
+        if (!checkAllowed(context))
+            return undefined;
+        const cachePath = updateCachePath(context.env, context.home);
+        const cache = readUpdateCache(cachePath);
+        const stamp = new Date(context.now).toISOString();
+        const next = { ...cache };
+        // Stamped before the request starts, so an offline machine asks once a day rather than on
+        // every command. The request writes `latest` when it succeeds.
+        const refresh = dayPassed(cache.checkedAt, context.now);
+        if (refresh)
+            next.checkedAt = stamp;
+        const latest = cache.latest;
+        const notice = latest !== undefined &&
+            isNewer(latest, context.installed) &&
+            dayPassed(cache.notifiedAt, context.now)
+            ? `humanish ${context.installed} is out of date; the latest is ${latest}. Run npx humanish@latest to use it.`
+            : undefined;
+        if (notice !== undefined)
+            next.notifiedAt = stamp;
+        if (refresh || notice !== undefined)
+            writeUpdateCache(cachePath, next);
+        if (refresh)
+            context.startRefresh(cachePath);
+        return notice;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The version the last successful check recorded, compared with `installed`, for `doctor`. Reads the
+ * cache only; undefined until a check has succeeded on this machine.
+ */
+export function recordedVersion(installed, env, home) {
+    const cache = readUpdateCache(updateCachePath(env, home));
+    if (cache.latest === undefined)
+        return undefined;
+    const checked = cache.checkedAt === undefined ? "" : ` (checked ${cache.checkedAt.slice(0, 10)})`;
+    return isNewer(cache.latest, installed)
+        ? {
+            newer: true,
+            message: `${installed} installed; ${cache.latest} is the latest${checked}. Run npx humanish@latest to use it.`,
+        }
+        : { newer: false, message: `${installed} installed, the latest published${checked}` };
+}
+/**
+ * Ask the npm registry for humanish's `latest` dist-tag and record it in the cache. The detached
+ * worker runs this. The request is a GET with an Accept header and nothing else: no machine id,
+ * installed version, command or path. A failed or malformed answer leaves the cache as it was.
+ */
+export async function refreshUpdateCache(args) {
+    try {
+        const fetchFn = args.fetchFn ?? globalThis.fetch;
+        const response = await fetchFn(REGISTRY_DIST_TAGS, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(args.timeoutMs ?? 3_000),
+        });
+        if (!response.ok)
+            return;
+        const body = await response.json();
+        const latest = body !== null && typeof body === "object"
+            ? body.latest
+            : undefined;
+        if (typeof latest !== "string" || parseVersion(latest) === undefined)
+            return;
+        const now = (args.now ?? Date.now)();
+        writeUpdateCache(args.cachePath, {
+            ...readUpdateCache(args.cachePath),
+            checkedAt: new Date(now).toISOString(),
+            latest,
+        });
+    }
+    catch {
+        // Offline, slow or refused: the next check is a day away either way.
+    }
+}
+/** What the worker's environment keeps: how this machine reaches the network, and no credentials. */
+const WORKER_ENV_NAMES = [
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "NO_PROXY",
+    "https_proxy",
+    "http_proxy",
+    "no_proxy",
+    "NODE_USE_ENV_PROXY",
+    "NODE_EXTRA_CA_CERTS",
+    "SYSTEMROOT",
+];
+/**
+ * Start the worker that runs refreshUpdateCache, detached and unreferenced so this process exits
+ * without waiting for it. A source checkout has no built worker, and nothing starts.
+ */
+export function startRefreshWorker(cachePath) {
+    const worker = fileURLToPath(new URL("./update-check-worker.js", import.meta.url));
+    if (!existsSync(worker))
+        return;
+    const env = Object.fromEntries(WORKER_ENV_NAMES.flatMap((name) => {
+        const value = process.env[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+    const child = spawn(process.execPath, [worker, cachePath], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env,
+    });
+    child.on("error", () => { });
+    child.unref();
+}

package/dist/evidence/encoded-text.d.ts

@@ -1,5 +1,17 @@
-/** Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. */
+/**
+ * Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. Each
+ * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`;
+ * decodeEscapesUtf8 reads it as `café`. A scan checks both: either reading can split a value that
+ * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
+ */
 export declare function decodeEscapes(text: string): string;
+/** decodeEscapes with each run of percent escapes read as UTF-8. */
+export declare function decodeEscapesUtf8(text: string): string;
+/**
+ * The UTF-8 reading of text's escapes when it differs from decodeEscapes, which it can only where
+ * a percent escape holds a byte of 0x80 or more.
+ */
+export declare function utf8ReadingOf(text: string, decoded: string): string | undefined;
 /** How scanEncodedText reads text. */
 export interface EncodedTextScanOptions {
     /** Do not count an encoded binary run as opaque. */
@@ -14,7 +26,8 @@ export interface EncodedTextScan {
     readonly opaque: boolean;
 }
 /**
- * Scans text for secrets as written, after decodeEscapes and transfer escapes, and inside each
+ * Scans text for secrets as written, after decodeEscapes (also with percent escapes read as UTF-8)
+ * and transfer escapes, and inside each
  * base64 (standard, URL-safe or line-wrapped) and hex run. A run that decodes to text is scanned in
  * turn. A run that decodes to an archive, or to other binary past MIN_OPAQUE_BASE64_RUN characters,
  * is opaque unless the caller allows opaque runs.

package/dist/evidence/encoded-text.js

@@ -44,13 +44,74 @@ function codePoint(value, original) {
         ? String.fromCodePoint(value)
         : original;
 }
-/** Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. */
+// The length of the UTF-8 sequence a lead byte starts, or 0 for a byte that starts none.
+function sequenceLength(lead) {
+    if (lead < 0x80)
+        return 1;
+    if (lead >= 0xc2 && lead <= 0xdf)
+        return 2;
+    if (lead >= 0xe0 && lead <= 0xef)
+        return 3;
+    if (lead >= 0xf0 && lead <= 0xf4)
+        return 4;
+    return 0;
+}
+/**
+ * A run of percent escapes read as UTF-8, as a browser reads a URL. A byte that starts no valid
+ * sequence stands for itself, the character with that code, as decodeEscapes reads every byte.
+ */
+function decodePercentRun(run) {
+    const bytes = Buffer.from(run.replace(/%/g, ""), "hex");
+    let text = "";
+    for (let at = 0; at < bytes.length;) {
+        const length = sequenceLength(bytes[at]);
+        const sequence = length > 0 ? bytes.subarray(at, at + length) : undefined;
+        const decoded = sequence?.length === length ? sequence.toString("utf8") : undefined;
+        // Node writes the replacement character for an overlong form, a surrogate half or a bad
+        // continuation byte, so a sequence counts only when its character encodes back to its bytes.
+        if (decoded !== undefined && Buffer.from(decoded, "utf8").equals(sequence)) {
+            text += decoded;
+            at += length;
+        }
+        else {
+            text += String.fromCharCode(bytes[at]);
+            at += 1;
+        }
+    }
+    return text;
+}
+function decodePercentBytes(run) {
+    return Buffer.from(run.replace(/%/g, ""), "hex").toString("latin1");
+}
+/**
+ * Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. Each
+ * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`;
+ * decodeEscapesUtf8 reads it as `café`. A scan checks both: either reading can split a value that
+ * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
+ */
 export function decodeEscapes(text) {
+    return decodeWith(text, decodePercentBytes);
+}
+/** decodeEscapes with each run of percent escapes read as UTF-8. */
+export function decodeEscapesUtf8(text) {
+    return decodeWith(text, decodePercentRun);
+}
+/**
+ * The UTF-8 reading of text's escapes when it differs from decodeEscapes, which it can only where
+ * a percent escape holds a byte of 0x80 or more.
+ */
+export function utf8ReadingOf(text, decoded) {
+    if (!/%[89a-f][0-9a-f]/i.test(text))
+        return undefined;
+    const utf8 = decodeEscapesUtf8(text);
+    return utf8 === decoded ? undefined : utf8;
+}
+function decodeWith(text, percent) {
     return text
         .replace(/\\u([0-9a-f]{4})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
         .replace(/\\x([0-9a-f]{2})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
         .replace(/\\\//g, "/")
-        .replace(/%([0-9a-f]{2})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
+        .replace(/(?:%[0-9a-f]{2})+/gi, percent)
         .replace(/&#x([0-9a-f]{1,6});?/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
         .replace(/&#(\d{1,7});?/g, (match, digits) => codePoint(Number.parseInt(digits, 10), match))
         .replace(/&([a-z]+);/gi, (match, name) => ASCII_ENTITIES[name.toLowerCase()] ?? match);
@@ -215,7 +276,8 @@ function inspectDecoded(bytes, run, options, depth) {
     };
 }
 /**
- * Scans text for secrets as written, after decodeEscapes and transfer escapes, and inside each
+ * Scans text for secrets as written, after decodeEscapes (also with percent escapes read as UTF-8)
+ * and transfer escapes, and inside each
  * base64 (standard, URL-safe or line-wrapped) and hex run. A run that decodes to text is scanned in
  * turn. A run that decodes to an archive, or to other binary past MIN_OPAQUE_BASE64_RUN characters,
  * is opaque unless the caller allows opaque runs.
@@ -223,10 +285,12 @@ function inspectDecoded(bytes, run, options, depth) {
 export function scanEncodedText(text, options = {}, depth = 0) {
     const matches = matcherOf(options);
     const decoded = decodeEscapes(text);
+    const utf8 = utf8ReadingOf(text, decoded);
     const expanded = decodeTransferEscapes(decoded);
     // A decoding that returns the same string would match the same way, so it is not matched again.
     if (matches(text) ||
         (decoded !== text && matches(decoded)) ||
+        (utf8 !== undefined && matches(utf8)) ||
         (expanded !== decoded && matches(expanded)))
         return SENSITIVE;
     const runs = [];
@@ -277,7 +341,7 @@ export function scanEncodedText(text, options = {}, depth = 0) {
 // Bump when scanEncodedText, decodeEscapes or the sensitive patterns change what they return. The
 // cache lives in one process, so the version guards results across a hot reload or a test that
 // swaps the scanner.
-const ENCODED_SCAN_VERSION = 3;
+const ENCODED_SCAN_VERSION = 4;
 // Distinct files one process verifies in a burst (a run's files, a serve library's runs).
 const SCAN_CACHE_LIMIT = 256;
 const scanCache = new Map();

package/dist/evidence/secret-scrub.d.ts

@@ -1,6 +1,6 @@
 /**
  * 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, 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.
  */

package/dist/evidence/secret-scrub.js

@@ -27,7 +27,7 @@ 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, 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,8 +52,29 @@ 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);
     return [value, ...escaped, ...binary.filter((form) => form.length >= MIN_ENCODED_FORM)];
 }
+/**
+ * Whether [at, end) overlaps a marker. The markers are one regex's matches, so they are sorted and
+ * disjoint: only the first marker that ends after `at` can also start before `end`.
+ */
+function overlapsMarker(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] < end;
+}
 /** Every occurrence of every form, outside the markers, merged where they overlap or touch. */
 function secretSpans(text, forms) {
     const markers = [];
@@ -65,7 +86,7 @@ function secretSpans(text, forms) {
     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))
+            if (!overlapsMarker(markers, at, end))
                 spans.push([at, end]);
         }
     }

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/notes.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

@@ -8,6 +8,8 @@ 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 { formatRunTime, runParticipantCaptions } from "../run/notes.js";
 import { isRecord } from "../run/type-guards.js";
 import { feedbackProofCommands, projectFeedbackAcceptanceProof } from "./proof.js";
 export const FEEDBACK_SCHEMA = "humanish.feedback.v1";
@@ -161,6 +163,7 @@ export async function buildAnalysisDraft(context, options) {
             `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}` : ""}`),
+            ...citedImpressions(bundle, evidence).map(({ streamId, kind, text }) => `Participant ${streamId} said at the end (${kind.replaceAll("_", " ")}): ${text}`),
             `Next check: ${finding.nextStep}`,
             correction
                 ? `Human review: ${correction.status}. ${correction.reason}`
@@ -206,6 +209,71 @@ export async function buildAnalysisDraft(context, options) {
         ],
     };
 }
+/**
+ * The participant impressions among a finding's cited evidence. Only an impression whose text the
+ * cited entry carries whole is quoted, so the draft repeats nothing the analysis share check did
+ * not read.
+ */
+function citedImpressions(bundle, evidence) {
+    return evidence.flatMap((item) => {
+        const impressions = bundle.streams.find((stream) => stream.id === item.streamId)?.actor
+            ?.impressions;
+        const impression = impressions?.status === "collected"
+            ? impressions.items.find((entry) => entry.messageId === item.eventId)
+            : undefined;
+        return impression === undefined || !item.text.includes(impression.text)
+            ? []
+            : [{ 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 = [...notes.notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
+    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" ||
@@ -244,7 +312,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, utf8ReadingOf } from "../evidence/encoded-text.js";
 import { readPlainText } from "../evidence/plain-text.js";
 import { streamScreenshotPaths } from "../verify/artifacts.js";
 import { verifyRunPrepared } from "../verify/verify.js";
@@ -149,7 +149,7 @@ 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 ([text, decoded, utf8ReadingOf(text, decoded) ?? ""].some(containsSensitive))
         throw new Error("Decoded text contains a secret-shaped value or private path; export refused.");
     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)) {

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/notes.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) {
@@ -334,11 +341,48 @@ async function recheckAnalysis(runPaths, analysis, verified, inlined, options) {
     };
     return "downgraded";
 }
+/**
+ * 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, finding } = 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: "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)