humanish 0.113.0 → 0.114.0

package/dist/analysis/service.js

@@ -17,6 +17,7 @@ import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalys
 import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
 import { keepRejectedAnalysisOutput } from "./diagnostics.js";
 import { loadAnalysis } from "./load.js";
+import { admittingMaxCost, costRefusalText, refusedCost } from "./admission.js";
 import { hashAnalysisValue } from "./validation.js";
 import { ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -188,17 +189,19 @@ function analyzeConfigRefusal(config) {
 }
 /** The result when admission refuses the attempt, or when a dry run stops after admission. */
 function admissionOnlyResult(base, config) {
-    if (!base.admission.allowed)
+    if (!base.admission.allowed) {
+        const cost = refusedCost(base.admission);
         return {
             ...base,
             ok: false,
             error: {
                 code: base.admission.error ?? "analysis_admission_denied",
-                message: base.admission.error === "analysis_budget_exceeded"
-                    ? "The conservative admission estimate exceeds --max-cost. No provider request was sent."
+                message: cost
+                    ? `${costRefusalText(cost)} To run it, raise the cap: humanish analyze --run ${base.run} --max-cost ${admittingMaxCost(cost)}`
                     : "The analysis input or configuration did not pass admission. No provider request was sent.",
             },
         };
+    }
     return {
         ...base,
         ok: true,

package/dist/cli/commands/analyze.js

@@ -29,7 +29,7 @@ export function registerAnalyzeCommand(parent, io) {
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--provider <name>", "Analyst: openai (default) or restricted codex account. No provider fallback.")
-        .option("--max-cost <usd>", "Required for OpenAI, also with --dry-run: send nothing when the estimated cost in USD is above this. The estimate is not a billing cap. Unsupported for Codex.")
+        .option("--max-cost <usd>", "Required for OpenAI, also with --dry-run: send nothing when the expected cost in USD, plus a 10% margin, is above this. It does not limit billing. Unsupported for Codex.")
         .option("--model <id>", "Supported vision model. OpenAI uses high effort; qualified Codex account analysis uses low effort.", DEFAULT_ANALYSIS_MODEL)
         .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
         .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", String(DEFAULT_ANALYSIS_TIMEOUT_MS))
@@ -125,7 +125,7 @@ async function handleAnalyze(io, options, command) {
             if (value.ok && value.dryRun && selected.config?.provider === "codex")
                 return "Local evidence and configuration passed admission. Codex CLI, login and model access were not checked. Dollar cost and output-token ceiling are unknown. No provider request sent.\n";
             if (value.ok && value.dryRun)
-                return `Admission estimate: $${value.admission?.estimatedCostUsd ?? "unknown"}; output allowance: ${value.admission?.outputTokenAllowance ?? "unknown"} tokens including reasoning. No request sent.\n`;
+                return admittedDryRunText(value.admission);
             const lines = [];
             if (value.artifactPath)
                 lines.push(`${value.reused ? "Reused" : "Saved"} ${value.status} analysis: ${value.artifactPath}`);
@@ -231,3 +231,8 @@ async function handleAnalyzeCorrect(io, options, command) {
         io.setExitCode(2);
     }
 }
+/** An admitted dry run's costs: the expected cost, the worst case and the cap it was admitted under. */
+function admittedDryRunText(admission) {
+    const usd = (value) => value === null || value === undefined ? "unknown" : `$${value.toFixed(2)}`;
+    return `Expected cost: ${usd(admission?.estimatedCostUsd)}. Worst case: ${usd(admission?.worstCaseCostUsd)}, if the analyst writes its whole ${admission?.outputTokenAllowance ?? "unknown"}-token output allowance, reasoning included. Admitted under the $${admission?.maxCostUsd ?? "unknown"} cap. No request sent.\n`;
+}

package/dist/cli/commands/notes.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerNotesCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/notes.js

@@ -0,0 +1,144 @@
+import { renderObserver } from "../../observer/render.js";
+import { loadRunBundlePrepared, resolveRunPath } from "../../run/locate.js";
+import { addRunNote, formatRunTime, readRunNotes, runParticipantCaptions, } from "../../run/notes.js";
+import { streamParticipantIdOf } from "../../run/participant-records.js";
+import { resolvePhysicalCwd, runIdOf } from "../../run/paths.js";
+import { runNotFoundMessage } from "../../run/run-not-found.js";
+import { cli } from "../invocation.js";
+import { CWD_OPTION_DESCRIPTION, humanError, JSON_OPTION_DESCRIPTION, writeResult, } from "../io.js";
+const NOTES_RESULT_SCHEMA = "humanish.notes-result.v1";
+export function registerNotesCommand(parent, io) {
+    parent
+        .command("notes")
+        .description("List the reviewer notes on a run, or add one at a moment of its recording. A note's time counts from the run's first timed capture, as the Observer's study timeline shows it.")
+        .summary("List or add reviewer notes on a run.")
+        // The text is read from the words after the run, not declared, so the root command list
+        // stays as narrow as its other rows and an unquoted note still arrives whole.
+        .usage("[options] <run> [text...]")
+        .argument("<run>", "Run id, or latest.")
+        .allowExcessArguments(true)
+        .option("--add", "Add a note. Its text is the words after the run; --at gives the moment.")
+        .option("--at <mm:ss>", "With --add: the moment, in minutes and seconds, such as 02:31.")
+        .option("--participant <id>", "With --add: the participant's id from the study, or its stream id. Leave it out for a note on the whole run.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  humanish notes latest",
+        '  humanish notes latest --add --at 02:31 "The save button was hidden here."',
+        '  humanish notes <runId> --add --at 00:45 --participant <id> "They gave up."',
+        "",
+        "Each note is saved in the run directory as notes/<id>.json. Text that looks like a secret",
+        "or a local path is replaced before it is saved, and verify scans notes like other run text.",
+    ].join("\n"))
+        .action((run, options, command) => {
+        const words = command.args.slice(1);
+        return handleNotes(io, run, words.length > 0 ? words.join(" ") : undefined, options, command);
+    });
+}
+/** Minutes and seconds as the Observer shows them, `02:31`, in milliseconds; null otherwise. */
+function parseRunTime(value) {
+    const match = /^(\d{1,4}):([0-5]\d)$/.exec(value.trim());
+    return match ? (Number(match[1]) * 60 + Number(match[2])) * 1000 : null;
+}
+const byRunTime = (notes) => [...notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
+async function handleNotes(io, run, text, options, command) {
+    const base = {
+        schema: NOTES_RESULT_SCHEMA,
+        cwd: options.cwd,
+        run,
+        notes: [],
+        participants: [],
+        warnings: [],
+    };
+    const fail = (code, message) => {
+        writeResult(command, io, { ...base, ok: false, error: { code, message } }, formatNotesHuman);
+        io.setExitCode(2);
+    };
+    const adding = options.add === true;
+    if (!adding && (text !== undefined || options.at !== undefined))
+        return fail("HUMANISH_NOTES_OPTION_CONFLICT", `Adding a note needs --add: ${cli(`notes ${run} --add --at 02:31 "text"`)}.`);
+    if (adding && (options.at === undefined || text === undefined))
+        return fail("HUMANISH_NOTES_OPTION_CONFLICT", `--add needs --at and the note's text: ${cli(`notes ${run} --add --at 02:31 "text"`)}.`);
+    const atMs = options.at === undefined ? null : parseRunTime(options.at);
+    if (adding && atMs === null)
+        return fail("HUMANISH_NOTE_INVALID_TIME", `--at ${options.at ?? ""} is not a time on the run clock. Give minutes and seconds from the run's first capture, as the Observer shows them, such as 02:31.`);
+    const cwd = await resolvePhysicalCwd(options.cwd);
+    const prepared = await resolveRunPath(cwd, run).catch(() => null);
+    if (!prepared)
+        return fail("HUMANISH_RUN_NOT_FOUND", await runNotFoundMessage(cwd, run));
+    const runId = runIdOf(prepared);
+    let added;
+    const warnings = [];
+    if (adding && atMs !== null && text !== undefined) {
+        const result = await addRunNote(prepared, {
+            atMs,
+            participant: options.participant ?? null,
+            text,
+        });
+        if (!result.ok)
+            return fail(result.error.code, result.error.message);
+        added = result.note;
+        if (result.scrubbed)
+            warnings.push("Part of the note looked like a secret or a local path, so it was replaced before the note was saved.");
+        // The saved Observer page shows notes read-only, so it is rendered again with the new one.
+        const rendered = await renderObserver(cwd, runId, { open: false, expectedRun: prepared })
+            .then((observer) => observer.ok)
+            .catch(() => false);
+        if (!rendered)
+            warnings.push(`The note is saved, but the run's saved Observer page could not be rendered again. ${cli(`observe --run ${runId}`)} shows it.`);
+    }
+    const notes = await readRunNotes(prepared);
+    // A note file that cannot be read is named and left as it is; the others are listed.
+    warnings.push(...notes.skipped);
+    const result = {
+        ...base,
+        ok: true,
+        run: runId,
+        notes: byRunTime(notes.notes),
+        participants: await participantsOf(cwd, prepared),
+        ...(added === undefined ? {} : { added }),
+        warnings,
+    };
+    writeResult(command, io, result, formatNotesHuman);
+    io.setExitCode(0);
+}
+/** The run's participants with their captions; none when its run.json cannot be read. */
+async function participantsOf(cwd, prepared) {
+    const loaded = await loadRunBundlePrepared(cwd, prepared).catch(() => null);
+    if (!loaded)
+        return [];
+    const captions = runParticipantCaptions(loaded.bundle);
+    return loaded.bundle.streams.map((stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        return {
+            id: stream.id,
+            ...(participantId === undefined ? {} : { participantId }),
+            caption: captions.get(stream.id) ?? stream.id,
+        };
+    });
+}
+/** Who a note is about, as a person reads it. */
+function participantName(result, participant) {
+    if (participant === null)
+        return "whole run";
+    return result.participants.find((entry) => entry.id === participant)?.caption ?? participant;
+}
+function noteLine(note, name, width) {
+    const head = `  ${formatRunTime(note.atMs)}  ${name.padEnd(width)}  `;
+    const [first = "", ...rest] = note.text.split("\n");
+    return [`${head}${note.author}: ${first}`, ...rest.map((line) => `         ${line}`)].join("\n");
+}
+function formatNotesHuman(result) {
+    if (!result.ok)
+        return humanError(result.error);
+    const warnings = result.warnings.map((warning) => `warning: ${warning}\n`).join("");
+    if (result.added)
+        return `Added a note at ${formatRunTime(result.added.atMs)} ${result.added.participant === null ? "on the whole run" : `for ${participantName(result, result.added.participant)}`} to run ${result.run}. The Observer marks it on the study timeline, and ${cli(`notes ${result.run}`)} lists every note.\n${warnings}`;
+    if (result.notes.length === 0)
+        return `Run ${result.run} has no reviewer notes. Add one: ${cli(`notes ${result.run} --add --at 00:30 "text"`)}\n${warnings}`;
+    const names = result.notes.map((note) => participantName(result, note.participant));
+    const width = Math.max(...names.map((name) => name.length));
+    return `${[`Reviewer notes on run ${result.run}: ${result.notes.length}`, ...result.notes.map((note, index) => noteLine(note, names[index], width))].join("\n")}\n${warnings}`;
+}

package/dist/cli/commands/observe.js

@@ -152,7 +152,7 @@ async function observeRun(io, options, command) {
         ...(openResult.command ? { openCommand: openResult.command } : {}),
         warnings: [
             ...rendered.warnings,
-            "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
+            "Observer is served over loopback http on 127.0.0.1; only this run's bundle directory is exposed, and the one change the page can make is adding a reviewer note.",
             ...(openResult.warning ? [openResult.warning] : []),
         ],
     };

package/dist/cli/commands/study-run.js

@@ -7,6 +7,7 @@ import { warnAndQueue } from "../deprecations.js";
 import { planStudy, resolveStudyDryRun } from "../../study/plan.js";
 import { keyNamesOf } from "../../study/requirements.js";
 import { routeOf } from "../../study/plan.js";
+import { computerUseParticipantCount } from "../../study/routing.js";
 import { computerUseRouteRun } from "./study-route-computer-use.js";
 import { runRoute } from "./study-route-run.js";
 import { scriptedRouteRun } from "./study-route-scripted.js";
@@ -130,7 +131,7 @@ export async function runStudyCommand(args) {
                 // Surface it so the invoker (who may not be the manifest author) knows executable code ran.
                 args.io.writeErr(`warning: review scorer ${scorer.provenance.ref} (${scorer.provenance.source}) is code that humanish loaded and ran in this process. Review it as you would any code you run.\n`);
             }
-            const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route);
+            const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route, computerUseParticipantCount(config));
             if (analysisBudget && resolveStudyDryRun(config, args.options.dryRun, true) === false) {
                 args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
             }

package/dist/cli/findings.js

@@ -2,6 +2,7 @@
 // `humanish.analysis-findings.v1` projection and its text. The analysis artifact stays the record;
 // this reads the version `analyze show` selects and never starts an analysis.
 import path from "node:path";
+import { admittingMaxCost, costRefusalText } from "../analysis/admission.js";
 import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
@@ -199,9 +200,11 @@ export function analysisFindings(source) {
         const outcome = analysisOutcomeText(job);
         return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
     }
+    if (job?.state === "skipped" && job.admission)
+        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${costRefusalText(job.admission)}`, cli(`analyze --run ${source.runId}${source.cwdFlag} --max-cost ${admittingMaxCost(job.admission)}`));
     if (job?.state === "skipped") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
-        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run prints its cost estimate; run it again with a --max-cost above the estimate." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
+        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run says why, and for a cost refusal names the --max-cost that admits it." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
             ? null
             : `${analyzeCommand(source, undefined)}${refused ? " --dry-run" : ""}`);
     }

package/dist/cli/io.d.ts

@@ -138,4 +138,5 @@ export declare function analysisOutcomeText(analysis: {
     state: string;
     reason: string | null;
 }): string;
+/** Preserve the run's own result while making requested post-processing failures machine-visible. */
 export declare function automaticAnalysisEnvelope<T>(result: T): T;

package/dist/cli/io.js

@@ -1,5 +1,5 @@
-import { automaticAnalysisSucceeded, defaultAnalysisOverBudget, } from "../analysis/automatic-completion.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js";
+import { admittingMaxCost, costRefusalText, refusedCost, } from "../analysis/admission.js";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
@@ -188,13 +188,14 @@ export function writeResult(command, io, result, formatHuman) {
         writeHuman(command, io, formatHuman(output));
         if (output !== null && typeof output === "object" && "automaticAnalysis" in output) {
             const analysis = output.automaticAnalysis;
-            if (analysis)
+            const cost = analysis?.result?.admission && refusedCost(analysis.result.admission);
+            if (cost)
+                io.writeOut(`analysis: refused before it started. ${refusedAnalysisText(cost, analysis.result?.run ?? "latest")}\n`);
+            else if (analysis)
                 io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
             const rejected = analysis?.result?.rejectedOutputPath;
             if (rejected)
                 io.writeOut(`analysis: ${analysis.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}\n`);
-            if (defaultAnalysisOverBudget(output))
-                io.writeOut(overBudgetAnalysisHint(output));
         }
     }
     markInvocationEnvelopeWritten(command);
@@ -286,7 +287,7 @@ const ANALYSIS_REASON_TEXT = {
     AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE: "skipped because the run's evidence could not be read",
     AUTOMATIC_ANALYSIS_ALREADY_REQUESTED: "skipped because this run's analysis was already requested",
     AUTOMATIC_ANALYSIS_BUSY: "skipped because another analysis is running",
-    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "not started because its configuration or question was refused",
+    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "refused before it started: its configuration, question, evidence or cost did not pass admission",
     AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "not started because the run's cleanup was not confirmed",
     AUTOMATIC_ANALYSIS_REUSED: "complete, reusing an earlier analysis of the same evidence",
     AUTOMATIC_ANALYSIS_LIMITATIONS: "partial, because it covered only part of the evidence",
@@ -305,13 +306,11 @@ export function analysisOutcomeText(analysis) {
         return analysis.state;
     return ANALYSIS_REASON_TEXT[analysis.reason] ?? `${analysis.state} (${analysis.reason})`;
 }
-/** Preserve the run's own result while making requested post-processing failures machine-visible. */
-function overBudgetAnalysisHint(result) {
-    const estimate = result.automaticAnalysis?.result?.admission?.estimatedCostUsd ?? null;
-    const suggested = Math.ceil(estimate ?? DEFAULT_ANALYSIS_MAX_COST_USD + 1);
-    const shown = estimate === null ? "" : ` ($${estimate.toFixed(2)})`;
-    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: ${cli(`analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}`)}\n`;
+/** What a refused analysis would cost and the command that runs it with a cap that admits it. */
+function refusedAnalysisText(cost, runId) {
+    return `${costRefusalText(cost)} To run it, raise the cap: ${cli(`analyze --run ${runId} --max-cost ${admittingMaxCost(cost)}`)}`;
 }
+/** Preserve the run's own result while making requested post-processing failures machine-visible. */
 export function automaticAnalysisEnvelope(result) {
     if (result === null ||
         typeof result !== "object" ||

package/dist/cli/program.js

@@ -13,6 +13,7 @@ import { registerCommsCommands } from "./commands/comms.js";
 import { registerFeedbackCommands } from "./commands/feedback.js";
 import { registerStudyCommands } from "./commands/study.js";
 import { registerMigrateCommand } from "./commands/migrate.js";
+import { registerNotesCommand } from "./commands/notes.js";
 import { registerObserveCommand } from "./commands/observe.js";
 import { registerCleanupCommand, registerExportCommand, registerReclaimCommand, registerReviewCommand, registerRunCommand, registerRunsCommand, registerRuntimeCommands, registerStatsCommand, registerVerifyCommand, } from "./commands/runs.js";
 import { registerDoctorCommand, registerInitCommand, registerKeysCommand, registerTelemetryCommand, } from "./commands/setup.js";
@@ -392,6 +393,7 @@ export function createProgram(io = {}) {
     registerVerifyCommand(program, cliIo);
     registerReviewCommand(program, cliIo);
     registerAnalyzeCommand(program, cliIo);
+    registerNotesCommand(program, cliIo);
     registerFeedbackCommands(program, cliIo);
     registerExportCommand(program, cliIo);
     registerRunsCommand(program, cliIo);

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 {};