humanish 0.106.1 → 0.108.0

package/dist/comms/types.d.ts

@@ -9,7 +9,7 @@ export interface CommsAddress {
     participantId: string;
     /** Runtime-only raw address, e.g. user-07@example.test | +15550137. */
     value: string;
-    /** sha256-short(value) — the only form persisted (redaction.digestText). */
+    /** sha256-short(value): the only form persisted (redaction.digestText). */
     digest: string;
 }
 /** Runtime-only captured raster attachment. Bytes never enter digest-only evidence. */
@@ -22,12 +22,12 @@ export interface CommsInlineImage {
 export interface CommsMessage {
     id: string;
     channel: CommsChannelKind;
-    /** Raw sender — an app-under-test address, or another actor's address. Runtime-only. */
+    /** Raw sender: an app-under-test address, or another actor's address. Runtime-only. */
     from: string;
     /** Resolved recipient inboxes this message was delivered to. */
     to: CommsAddress[];
     subject?: string;
-    /** Runtime-only for real; local-only for fake (never a share path without redaction — #108). */
+    /** Runtime-only for real; local-only for fake (never a share path without redaction). */
     body: string;
     inlineImages?: CommsInlineImage[];
     /** Actionable links extracted from the body (magic-link / invite / reset). Runtime-only. */
@@ -37,7 +37,7 @@ export interface CommsMessage {
     sentAt: number;
     deliveredAt: number;
 }
-/** An actor sending OUT (a reply/compose); recipients are known CommsAddresses. */
+/** An actor sending out (a reply/compose); recipients are known CommsAddresses. */
 export interface OutboundMessage {
     from: CommsAddress;
     to: CommsAddress[];
@@ -45,7 +45,7 @@ export interface OutboundMessage {
     body: string;
     inlineImages?: CommsInlineImage[];
 }
-/** A raw inbound from an INGRESS (the vendor-neutral email catch, an SMTP sink, …): recipients are
+/** A raw inbound from an ingress (the vendor-neutral email catch, an SMTP sink, …): recipients are
  *  raw address strings the bus resolves against its provisioned inboxes. */
 export interface InboundRaw {
     from: string;
@@ -67,7 +67,7 @@ export interface CommsChannel {
     /** Route a composed message from one actor to addressed inboxes. Returns the delivered record. */
     send(message: OutboundMessage): Promise<CommsMessage>;
     /** Route a raw ingress delivery (app-under-test → recipient strings). Returns the messages that
-     *  matched a provisioned inbox (unmatched recipients are dropped — no inbox to deliver to). */
+     *  matched a provisioned inbox (unmatched recipients are dropped; no inbox to deliver to). */
     deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;
     /** New messages delivered to `address` since `since` (exclusive), oldest-first. Drives the surface. */
     poll(address: CommsAddress, since?: number): Promise<CommsMessage[]>;

package/dist/comms/types.js

@@ -1,8 +1,8 @@
-// The addressed message bus for captured mail (#297): the email or SMS a persona receives off the
-// app, as a testable surface. One port, addressed by lane, so the inbox surface and the evidence
+// The addressed message bus for captured mail: the email or SMS a persona receives off the
+// app, as a testable surface. One port, addressed by participant, so the inbox surface and the evidence
 // writer read messages without knowing how they were captured.
 //
-// PUBLIC-SAFETY: raw address values, message bodies, links, and codes are RUNTIME-ONLY. Only the
-// address DIGEST (sha256-short, via redaction.digestText) is ever meant to reach a persisted bundle;
+// Public safety: raw address values, message bodies, links, and codes are runtime-only. Only the
+// address digest (sha256-short, via redaction.digestText) is ever meant to reach a persisted bundle;
 // a verification link / OTP has "no secret shape" (like the lobby code) → literal-scrub + digest.
 export {};

package/dist/evidence/browser-hygiene.d.ts

@@ -1,7 +1,7 @@
 /**
  * Browser chrome that belongs to the host environment (update prompts, password
  * save bubbles, first-run UI) pollutes product evidence. Keep these knobs in one
- * place so browser-backed lanes can prefer product pixels over browser UI.
+ * place so browser-backed routes can prefer product pixels over browser UI.
  */
 export declare const CHROMIUM_EVIDENCE_HYGIENE_FLAGS: readonly ["--disable-background-networking", "--disable-component-update", "--disable-default-apps", "--disable-domain-reliability", "--disable-extensions", "--disable-sync", "--no-default-browser-check", "--no-first-run", "--password-store=basic", "--use-mock-keychain"];
 export declare function chromiumEvidenceProfilePreferencesJson(): string;

package/dist/evidence/browser-hygiene.js

@@ -1,7 +1,7 @@
 /**
  * Browser chrome that belongs to the host environment (update prompts, password
  * save bubbles, first-run UI) pollutes product evidence. Keep these knobs in one
- * place so browser-backed lanes can prefer product pixels over browser UI.
+ * place so browser-backed routes can prefer product pixels over browser UI.
  */
 export const CHROMIUM_EVIDENCE_HYGIENE_FLAGS = [
     "--disable-background-networking",

package/dist/evidence/frame-signature.d.ts

@@ -1,6 +1,6 @@
 /**
  * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
- * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
+ * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, contrast-normalizes that grid, quantizes each
  * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
  * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
  * The hash cannot be reversed to the image, so exposing it in a trace is public-safe.

package/dist/evidence/frame-signature.js

@@ -6,7 +6,7 @@ const SIGNATURE_FALLBACK = "unreadable";
 const ANCHOR_LEVELS = 16;
 /**
  * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
- * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
+ * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, contrast-normalizes that grid, quantizes each
  * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
  * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
  * The hash cannot be reversed to the image, so exposing it in a trace is public-safe.
@@ -65,9 +65,9 @@ function quantizedGrid(data, srcW, srcH) {
         }
     }
     // Stretch this frame's own range across the full scale before quantizing. Without this a light UI
-    // occupies a sliver at the top of 0..255 and quantizes to a near-constant (#383).
+    // occupies a sliver at the top of 0..255 and quantizes to a near-constant.
     //
-    // The endpoints are TRIMMED rather than the raw min/max: a handful of extreme cells must not be
+    // The endpoints are trimmed rather than the raw min/max: a handful of extreme cells must not be
     // able to rescale the whole frame, or a blinking text cursor would rewrite every cell and read as
     // progress forever. Trimming K cells from each end clamps that away while still preserving real
     // structure, which occupies far more cells than K (a row of sidebar text covers dozens).
@@ -81,7 +81,7 @@ function quantizedGrid(data, srcW, srcH) {
 }
 /**
  * The frame's overall brightness, coarsely quantized. Normalization deliberately discards absolute
- * level, so this is prefixed back on for the two cases where absolute level IS the change: a uniform
+ * level, so this is prefixed back on for the two cases where absolute level is the change: a uniform
  * frame (an all-white blank vs an all-black screen normalize identically), and a whole-page dim such
  * as a modal overlay, which preserves relative structure while changing the whole frame. Quantized
  * coarsely so ordinary antialiasing noise cannot move it.

package/dist/evidence/redaction.d.ts

@@ -35,7 +35,7 @@ export interface RedactedScreenshot {
 export interface RedactScreenshotOptions {
     /**
      * Longest emitted edge in pixels. Clamped to [1, 128]: a caller may request a
-     * SMALLER (safer) thumbnail but never a larger one, so no call site can widen
+     * smaller (safer) thumbnail but never a larger one, so no call site can widen
      * the frame back into legibility. Default 96. Blur is not a caller knob: it is
      * an internal safety floor computed from the output size.
      */
@@ -52,7 +52,7 @@ export declare function digestText(text: string, length?: number): string;
 export declare function tailText(value: string, maxChars: number): string;
 /**
  * A redacted, ellipsis-prefixed tail of captured output for a (public-bound)
- * message field. Pattern-redacts the FULL text BEFORE truncating: slicing a tail
+ * message field. Pattern-redacts the full text before truncating: slicing a tail
  * first could cut through a secret's prefix (e.g. drop "sk-proj-") and defeat the
  * pattern matcher on the remainder. Callers should literal-scrub known
  * provisioned values first; this is the pattern pass. Empty output -> "(no output)".
@@ -103,7 +103,7 @@ export declare function scrubLiterals(values: readonly string[]): (text: string)
 /**
  * Coerce an unknown thrown value to its message string. Prefer this over the
  * inline `error instanceof Error ? error.message : String(error)` so error
- * stringification stays uniform. Note: this does NOT redact -- sites that emit
+ * stringification stays uniform. Note: this does not redact; sites that emit
  * to public-bound artifacts must run the result through `redactText` first.
  */
 export declare function toErrorMessage(error: unknown): string;

package/dist/evidence/redaction.js

@@ -101,13 +101,13 @@ export function publicPathForTrace(value, rootCwd) {
 // ---------------------------------------------------------------------------
 // Screenshot redaction.
 //
-// Computer-use lanes capture raw desktop frames that can contain secrets, PII,
+// Computer-use participants capture raw desktop frames that can contain secrets, PII,
 // or a logged-in third-party UI. A raw frame must never reach a public artifact.
 // redactScreenshot is the fail-closed primitive that gates that surface. It
 // always returns a freshly re-encoded, downscaled, box-blurred thumbnail (or a
-// neutral placeholder), and NEVER the source pixels. The "too coarse to read"
+// neutral placeholder), and never the source pixels. The "too coarse to read"
 // invariant is enforced in code, not by defaults: the emitted width is hard-
-// capped (a caller may request a SMALLER thumbnail but never a larger one), and
+// capped (a caller may request a smaller thumbnail but never a larger one), and
 // the blur radius is computed internally with a floor, so neither a caller
 // option nor a natively small frame can widen the output back into legibility.
 // On any uncertainty (non-PNG input, an oversized or unreadable PNG, or any
@@ -241,7 +241,7 @@ export function tailText(value, maxChars) {
 }
 /**
  * A redacted, ellipsis-prefixed tail of captured output for a (public-bound)
- * message field. Pattern-redacts the FULL text BEFORE truncating: slicing a tail
+ * message field. Pattern-redacts the full text before truncating: slicing a tail
  * first could cut through a secret's prefix (e.g. drop "sk-proj-") and defeat the
  * pattern matcher on the remainder. Callers should literal-scrub known
  * provisioned values first; this is the pattern pass. Empty output -> "(no output)".
@@ -321,7 +321,7 @@ export function scrubLiterals(values) {
 /**
  * Coerce an unknown thrown value to its message string. Prefer this over the
  * inline `error instanceof Error ? error.message : String(error)` so error
- * stringification stays uniform. Note: this does NOT redact -- sites that emit
+ * stringification stays uniform. Note: this does not redact; sites that emit
  * to public-bound artifacts must run the result through `redactText` first.
  */
 export function toErrorMessage(error) {

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

@@ -0,0 +1,9 @@
+/**
+ * A scrub that replaces each non-empty value and its encoded forms with `[REDACTED_SECRET]`. Every
+ * occurrence of every form is found on its own, and overlapping finds are merged into one span, so
+ * a value that overlaps another is removed whole wherever each starts. The scrub reads the text
+ * 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.
+ */
+export declare function scrubSecretValues(values: readonly string[]): (text: string) => string;

package/dist/evidence/secret-scrub.js

@@ -0,0 +1,96 @@
+// Literal scrubbing of secret values from text that leaves the host, such as an error quoted in a
+// 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;
+// 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;
+/**
+ * The characters of a value's base64 encoding that do not depend on its neighbours, with 0, 1 or
+ * 2 bytes before it. A prefix byte shares the next character with the value, and so does the byte
+ * after a partial last group, so those characters are dropped.
+ */
+function base64Middles(bytes, encoding) {
+    return [0, 1, 2].map((offset) => {
+        const encoded = Buffer.concat([Buffer.alloc(offset), bytes])
+            .toString(encoding)
+            .replace(/=+$/, "");
+        const total = offset + bytes.length;
+        const start = offset === 0 ? 0 : offset + 1;
+        const end = Math.floor(total / 3) * 4 + (total % 3);
+        return encoded.slice(start, end);
+    });
+}
+/** A value as written, and percent-encoded, JSON-escaped, base64 at each byte offset, base64url and hex. */
+function encodedForms(value) {
+    const bytes = Buffer.from(value, "utf8");
+    const encoded = [
+        JSON.stringify(value).slice(1, -1),
+        bytes.toString("base64"),
+        bytes.toString("base64url"),
+        bytes.toString("hex"),
+        ...base64Middles(bytes, "base64"),
+        ...base64Middles(bytes, "base64url"),
+    ];
+    // encodeURIComponent throws on a lone surrogate. Such a value is still found as written.
+    try {
+        encoded.push(encodeURIComponent(value));
+    }
+    catch {
+        // no percent-encoded form
+    }
+    return [value, ...encoded.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) {
+    const markers = [];
+    for (const match of text.matchAll(MARKER)) {
+        const start = match.index ?? 0;
+        markers.push([start, start + match[0].length]);
+    }
+    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);
+        if (last !== undefined && span[0] <= last[1])
+            last[1] = Math.max(last[1], span[1]);
+        else
+            merged.push([span[0], span[1]]);
+    }
+    return merged;
+}
+/**
+ * A scrub that replaces each non-empty value and its encoded forms with `[REDACTED_SECRET]`. Every
+ * occurrence of every form is found on its own, and overlapping finds are merged into one span, so
+ * a value that overlaps another is removed whole wherever each starts. The scrub reads the text
+ * 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.
+ */
+export function scrubSecretValues(values) {
+    const forms = [...new Set(values.filter((value) => value.length > 0).flatMap(encodedForms))];
+    if (forms.length === 0)
+        return (text) => text;
+    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);
+    };
+}

package/dist/feedback/draft.js

@@ -2,12 +2,13 @@
 // 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 { studyAnalysisSharingProblems } from "../analysis/sharing.js";
-import { loadStudyAnalysis } from "../analysis/load.js";
+import { analysisSharingProblems } from "../analysis/sharing.js";
+import { loadAnalysis } from "../analysis/load.js";
 import { hashAnalysisValue } from "../analysis/validation.js";
-import { formatParticipantOutcomes, formatStudyTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
+import { formatParticipantOutcomes, formatRunTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
 import { isFeedbackIdempotencyKey } from "../run/feedback-shape.js";
+import { isRecord } from "../run/type-guards.js";
 import { feedbackProofCommands, projectFeedbackAcceptanceProof } from "./proof.js";
 export const FEEDBACK_SCHEMA = "humanish.feedback.v1";
 export function buildDraft(bundle, bundlePath, candidateId) {
@@ -48,95 +49,55 @@ export function buildDraft(bundle, bundlePath, candidateId) {
             acceptance_proof: projectFeedbackAcceptanceProof(bundle, candidate),
         };
     }
-    // #392: the fallback below is DRY-RUN-shaped, and it used to be the fallback for every bundle
-    // without a candidate — so a live run whose route filed no participant report got a draft
-    // claiming "no browser behavior was exercised" over 15 screenshots of browser behavior. A live
-    // bundle now gets a draft that describes the run that happened, built from the same review lines
-    // the stakeholder surfaces show (participants and tasks keep their denominators).
-    if (bundle.mode === "live") {
-        const participantEndings = participantOutcomeDetails(bundle.streams);
-        const review = withCuaReviewProvenance(bundle.review, bundle.streams);
-        const actualLines = [
-            review.summary,
-            ...(bundle.review.participants === undefined
-                ? []
-                : [
-                    `Participants: ${formatParticipantOutcomes(bundle.review.participants, participantEndings)}.`,
-                ]),
-            ...(bundle.review.tasks === undefined
-                ? []
-                : [`Tasks: ${formatStudyTaskFunnel(bundle.review.tasks)}.`]),
-        ];
-        return {
-            schema: FEEDBACK_SCHEMA,
-            run_id: bundle.runId,
-            adapter_id: bundle.source.packageName ?? bundle.scenario.id,
-            scenario_id: bundle.scenario.id,
-            persona_id: bundle.persona.id,
-            actor: (bundle.streams ?? []).some((stream) => stream.actor?.lane === "computer-use")
-                ? "computer-use"
-                : "unknown",
-            substrate: "unknown",
-            failure_owner: "unknown",
-            summary: "Live study completed without a participant-reported finding",
-            expected: bundle.scenario.goal,
-            actual: actualLines.join(" "),
-            source_bundle: bundlePath,
-            evidence: [
-                {
-                    path: bundlePath,
-                    kind: "state",
-                    note: "Source run bundle.",
-                },
-                {
-                    path: path.join(path.dirname(bundlePath), "review.md"),
-                    kind: "review",
-                    note: "The run's review: verdict, participants, and gaps.",
-                },
-            ],
-            redaction: {
-                status: "passed",
-                notes: bundle.redaction.notes,
-            },
-            idempotency_key: `humanish:${bundle.runId}:live-run-summary`,
-            proposed_next_state: "study-quality-review",
-            acceptance_proof: [
-                feedbackProofCommands(bundle.runId).verify,
-                feedbackProofCommands(bundle.runId).watch,
-            ],
-        };
-    }
+    // A bundle without a candidate gets a draft that describes the run that happened, built from the
+    // same review lines the stakeholder surfaces show (participants and tasks keep their
+    // denominators). Feedback refuses a dry run before it gets here.
+    const participantEndings = participantOutcomeDetails(bundle.streams);
+    const review = withCuaReviewProvenance(bundle.review, bundle.streams);
+    const actualLines = [
+        review.summary,
+        ...(bundle.review.participants === undefined
+            ? []
+            : [
+                `Participants: ${formatParticipantOutcomes(bundle.review.participants, participantEndings)}.`,
+            ]),
+        ...(bundle.review.tasks === undefined
+            ? []
+            : [`Tasks: ${formatRunTaskFunnel(bundle.review.tasks)}.`]),
+    ];
     return {
         schema: FEEDBACK_SCHEMA,
         run_id: bundle.runId,
-        adapter_id: bundle.source.packageName ?? "synthetic-app",
+        adapter_id: bundle.source.packageName ?? bundle.scenario.id,
         scenario_id: bundle.scenario.id,
         persona_id: bundle.persona.id,
-        actor: "synthetic-dry-run",
-        substrate: "local-filesystem",
-        failure_owner: "harness",
-        summary: "Dry-run contract proof needs product-evidence follow-up",
-        expected: "humanish should produce verified, public-safe evidence before product claims are filed.",
-        actual: "This dry-run produced a contract-proof bundle only; no browser or product behavior was exercised.",
+        actor: (bundle.streams ?? []).some((stream) => stream.actor?.lane === "computer-use")
+            ? "computer-use"
+            : "unknown",
+        substrate: "unknown",
+        failure_owner: "unknown",
+        summary: "Live study completed without a participant-reported finding",
+        expected: bundle.scenario.goal,
+        actual: actualLines.join(" "),
         source_bundle: bundlePath,
         evidence: [
             {
                 path: bundlePath,
                 kind: "state",
-                note: "Synthetic run bundle.",
+                note: "Source run bundle.",
             },
             {
                 path: path.join(path.dirname(bundlePath), "review.md"),
                 kind: "review",
-                note: "Review skeleton labels this as contract proof only.",
+                note: "The run's review: verdict, participants, and gaps.",
             },
         ],
         redaction: {
             status: "passed",
             notes: bundle.redaction.notes,
         },
-        idempotency_key: `humanish:${bundle.runId}:dry-run-contract-proof`,
-        proposed_next_state: "watch",
+        idempotency_key: `humanish:${bundle.runId}:live-run-summary`,
+        proposed_next_state: "study-quality-review",
         acceptance_proof: [
             feedbackProofCommands(bundle.runId).verify,
             feedbackProofCommands(bundle.runId).watch,
@@ -146,10 +107,10 @@ export function buildDraft(bundle, bundlePath, candidateId) {
 export async function buildAnalysisDraft(context, options) {
     if (!options.analysis || !options.finding || options.candidate !== undefined)
         return null;
-    const loaded = await loadStudyAnalysis(context.preparedRunPaths, options.analysis);
+    const loaded = await loadAnalysis(context.preparedRunPaths, options.analysis);
     const analysis = loaded.analysis;
     const finding = analysis?.result?.findings.find((item) => item.id === options.finding);
-    const sharing = studyAnalysisSharingProblems(loaded);
+    const sharing = analysisSharingProblems(loaded);
     if (loaded.state !== "ready" || sharing.sensitive || sharing.unverified || !analysis || !finding)
         return null;
     const correction = loaded.corrections.filter((item) => item.findingId === finding.id).at(-1);
@@ -253,14 +214,14 @@ export function isUsableFeedbackCandidate(candidate) {
         !item.path.includes("://") &&
         !item.path.includes(".."));
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+/** An evidence path inside the run directory, as "run.json" or "screenshots/step-003.png". */
+function runRelative(draft, evidencePath) {
+    const relative = path.relative(path.dirname(draft.source_bundle), evidencePath);
+    return relative === "" || relative.startsWith("..") ? evidencePath : relative;
 }
 export function renderMarkdown(draft, repo) {
     return `This issue was drafted by humanish from a verified humanish run bundle.
 
-It contributes to public-safe simulation harness coverage. The feedback command did not mutate GitHub, commit code, or claim unobserved product behavior.
-
 ## Summary
 
 ${draft.summary}
@@ -275,14 +236,9 @@ ${draft.actual}
 
 ## Evidence
 
-${draft.evidence.map((item) => `- ${item.kind}: \`${item.path}\` - ${item.note}`).join("\n")}
-
-## Filing Notes
+${draft.evidence.map((item) => `- ${item.kind} ${runRelative(draft, item.path)}: ${item.note}`).join("\n")}
 
-- Repository: ${repo}
-- GitHub mutation: not performed
-- Substrate: ${draft.substrate}
-- Production data: not used
+Repository: ${repo}
 
 \`\`\`yaml
 humanish_feedback:

package/dist/feedback/export-bundle.js

@@ -1,4 +1,4 @@
-// The publish boundary for existing raw runs (#136). A derivative is an isolated
+// The publish boundary for existing raw runs. A derivative is an isolated
 // workspace, never a new run in the source history. No provider APIs are involved.
 import { createHash } from "node:crypto";
 import { lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, rmdir } from "node:fs/promises";
@@ -16,7 +16,7 @@ import { verifyRunPrepared } from "../verify/verify.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import {} from "../run/bundle.js";
 import { runIdOf, isPathInside, prepareRunArtifactPaths, validatePreparedRunArtifactPaths, } from "../run/paths.js";
-import { isStudyAnalysisRecordPath } from "../analysis/sharing.js";
+import { isAnalysisRecordPath } from "../analysis/sharing.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 const DERIVATION_SCHEMA = "humanish.redacted-derivation.v1";
 const MAX_FILES = 10_000;
@@ -46,9 +46,9 @@ function jsonBytes(value) {
     return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
 }
 function omittedReason(relative) {
-    if (relative.startsWith("analysis-automatic/") && isStudyAnalysisRecordPath(relative))
+    if (relative.startsWith("analysis-automatic/") && isAnalysisRecordPath(relative))
         return "automatic execution intent and liveness do not transfer to a derivative";
-    if (isStudyAnalysisRecordPath(relative))
+    if (isAnalysisRecordPath(relative))
         return "analysis records bind original evidence hashes; reanalyze the derivative";
     if (relative.startsWith(".analysis-lock/"))
         return "local analysis execution lock";
@@ -477,7 +477,7 @@ async function resolveDestination(cwd, runPaths, runId, options) {
  * it. The raw snapshot is removed before the derivative is built.
  */
 async function verifyFrozenSource(workspace, source, runId) {
-    // Verify the SAME frozen bytes that will be transformed. Verifying the live
+    // Verify the same frozen bytes that will be transformed. Verifying the live
     // source and then rereading run.json permits an ABA edit to contaminate a
     // derivative whose receipt still names the first inventory's hashes.
     // Raw verification bytes stay in private OS temporary storage, even when

package/dist/feedback/export.d.ts

@@ -46,5 +46,9 @@ export interface ExportDeps {
 /** The banner a --local-only export carries. Plain HTML, before the app root, so it renders with JS off. */
 export declare function localOnlyBanner(reasons: string[]): string;
 export declare function exportRun(cwdInput: string, runInput: string, options?: ExportOptions, deps?: ExportDeps): Promise<ExportResult | ExportFailure>;
-export declare function formatExportHuman(result: ExportResult | ExportFailure): string;
+/** Human output; a failure is an error the CLI prints on stderr (HumanOutput in src/cli/io.ts). */
+export declare function formatExportHuman(result: ExportResult): string;
+export declare function formatExportHuman(result: ExportResult | ExportFailure): string | {
+    error: ExportFailure["error"];
+};
 export {};