humanish 0.111.3 → 0.112.0

package/dist/cli/findings.d.ts

@@ -4,14 +4,13 @@ import type { AnalysisArtifact, LoadedAnalysis } from "../analysis/types.js";
 import { type CliIo } from "./io.js";
 export declare const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 type Finding = NonNullable<AnalysisArtifact["result"]>["findings"][number];
+type DesignFinding = NonNullable<NonNullable<AnalysisArtifact["result"]>["designFindings"]>[number];
 /** `ready` and `stale` carry findings; every other state carries none and says why in `message`. */
 type FindingsState = "ready" | "stale" | "running" | "none" | "skipped" | "failed" | "dry_run" | "unavailable";
-interface FindingEvidence {
+interface CitedEvidence {
     id: string;
     streamId: string;
     kind: string;
-    /** How the finding's observations used this item: visual, action, participant_statement, inference. */
-    bases: string[];
     /** Index of the latest retained capture at this item, from 0; null before any capture. */
     frame: number | null;
     /** Time since the first retained capture, not a video offset. */
@@ -20,8 +19,19 @@ interface FindingEvidence {
     /** The capture file relative to the project directory, or null for nonvisual evidence. */
     capture: string | null;
 }
+interface FindingEvidence extends CitedEvidence {
+    /** How the finding's observations used this item: visual, action, participant_statement, inference. */
+    bases: string[];
+}
 interface FindingView {
     id: string;
+    /**
+     * One plain sentence about what happened, and one to three about what the person tried and what
+     * got in the way. Null in analyses written before them. An amended finding keeps the original
+     * text here; `correction.replacementClaim` replaces both.
+     */
+    headline: string | null;
+    experience: string | null;
     title: string;
     summary: string;
     impact: Finding["impact"];
@@ -41,6 +51,22 @@ interface FindingView {
         replacementClaim: string | null;
     } | null;
 }
+interface DesignFindingView {
+    id: string;
+    headline: string;
+    screen: string;
+    notice: string;
+    whyItMatters: string;
+    suggestion: string;
+    severity: DesignFinding["severity"];
+    confidence: DesignFinding["confidence"];
+    seenBy: {
+        streamId: string;
+        label: string;
+    }[];
+    /** Each cited item once; at least one has a capture. */
+    evidence: CitedEvidence[];
+}
 export interface AnalysisFindings {
     schema: typeof ANALYSIS_FINDINGS_SCHEMA;
     runId: string;
@@ -48,7 +74,10 @@ export interface AnalysisFindings {
     /** The stable code behind a state other than ready, when one is recorded. */
     reason: string | null;
     message: string;
-    /** The command that gets findings for this run, or null when none can. */
+    /**
+     * The command that gets findings for this run, or for a dry run the command that starts a live
+     * one. Null when none can.
+     */
     next: string | null;
     analysisId: string | null;
     status: AnalysisArtifact["status"] | null;
@@ -63,6 +92,11 @@ export interface AnalysisFindings {
     summary: string | null;
     /** Highest priority first, as the analysis ranked them. */
     findings: FindingView[];
+    /**
+     * Problems a designer would see in the captures, most severe first. Null when the view carries
+     * no analysis result, or the analysis was written before design findings.
+     */
+    designFindings: DesignFindingView[] | null;
     limitations: string[];
     warnings: string[];
 }
@@ -80,6 +114,17 @@ interface FindingsSource {
      * false`, read when the view is built. Undefined when it does not, or cannot be read.
      */
     analysisOffIn?: string;
+    /** For a dry run, the study a live run can start from, read when the view is built. */
+    liveStudy?: LiveStudy;
+}
+/** A study `run` can start live after a dry run. */
+interface LiveStudy {
+    /** The study argument for `run`: its id, or its path when the run named it by path. */
+    run: string;
+    /** Its id, for the message. */
+    id: string;
+    /** The study file to set `mode: live` in first, when the file still starts as a dry run. */
+    setLiveIn?: string;
 }
 /** The findings view of a run's selected analysis, or why it has none. */
 export declare function analysisFindings(source: FindingsSource): AnalysisFindings;

package/dist/cli/findings.js

@@ -9,6 +9,7 @@ import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
 import { studyProvenanceOf } from "../run/study-provenance.js";
 import { resolveStudyManifest } from "../study/discover.js";
+import { routeOf } from "../study/routing.js";
 import { plural } from "../run/text.js";
 import { shellQuote } from "../substrates/shell.js";
 import { analysisOutcomeText, wantsJson } from "./io.js";
@@ -26,16 +27,10 @@ function analyzeCommand(source, provider) {
         ? `${run} --provider codex`
         : `${run} --max-cost ${DEFAULT_ANALYSIS_MAX_COST_USD}`;
 }
-function evidenceOf(finding, analysis, runRoot) {
-    const bases = new Map();
-    for (const observation of finding.observations)
-        for (const id of observation.evidenceIds) {
-            const set = bases.get(id) ?? new Set();
-            set.add(observation.basis);
-            bases.set(id, set);
-        }
+/** The cited items the analysis evidence resolves, each once, in citation order. */
+function citedEvidence(ids, analysis, runRoot) {
     const byId = new Map(analysis.evidence.map((entry) => [entry.id, entry]));
-    return [...bases].flatMap(([id, used]) => {
+    return [...new Set(ids)].flatMap((id) => {
         const entry = byId.get(id);
         if (!entry)
             return [];
@@ -44,7 +39,6 @@ function evidenceOf(finding, analysis, runRoot) {
                 id,
                 streamId: entry.streamId,
                 kind: entry.kind,
-                bases: [...used],
                 frame: entry.frame,
                 elapsedMs: entry.elapsedMs,
                 at: entry.at,
@@ -53,11 +47,58 @@ function evidenceOf(finding, analysis, runRoot) {
         ];
     });
 }
+function evidenceOf(finding, analysis, runRoot) {
+    const bases = new Map();
+    for (const observation of finding.observations)
+        for (const id of observation.evidenceIds) {
+            const set = bases.get(id) ?? new Set();
+            set.add(observation.basis);
+            bases.set(id, set);
+        }
+    return citedEvidence(bases.keys(), analysis, runRoot).map(({ id, streamId, kind, ...entry }) => ({
+        id,
+        streamId,
+        kind,
+        bases: [...bases.get(id)],
+        ...entry,
+    }));
+}
+const SEVERITY_RANK = {
+    major: 0,
+    moderate: 1,
+    minor: 2,
+};
+/** Most severe first; equal severity keeps the analysis order. */
+function designFindingViews(analysis, runRoot) {
+    const designFindings = analysis.result?.designFindings;
+    if (designFindings === undefined)
+        return null;
+    const labels = new Map(analysis.participants.map((p) => [p.streamId, p.label]));
+    return [...designFindings]
+        .sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
+        .map((finding) => ({
+        id: finding.id,
+        headline: finding.headline,
+        screen: finding.screen,
+        notice: finding.notice,
+        whyItMatters: finding.whyItMatters,
+        suggestion: finding.suggestion,
+        severity: finding.severity,
+        confidence: finding.confidence,
+        seenBy: finding.seenByStreamIds.map((streamId) => ({
+            streamId,
+            label: labels.get(streamId) ?? streamId,
+        })),
+        evidence: citedEvidence(finding.evidenceIds, analysis, runRoot),
+    }));
+}
 function findingView(finding, loaded, runRoot) {
     const labels = new Map(loaded.analysis.participants.map((p) => [p.streamId, p.label]));
     const correction = loaded.corrections.filter((entry) => entry.findingId === finding.id).at(-1);
     return {
         id: finding.id,
+        headline: finding.headline ?? null,
+        experience: finding.experience ?? null,
         title: finding.title,
         summary: finding.summary,
         impact: finding.impact,
@@ -98,14 +139,26 @@ function withoutFindings(source, state, reason, message, next) {
         path: null,
         summary: null,
         findings: [],
+        designFindings: null,
         limitations: [],
         warnings: source.loaded.warnings,
     };
 }
+/** A dry run's view: nothing to analyze, and the command that starts a live run. */
+function dryRunFindings(source) {
+    const opening = "This is a dry run: no participant used the product, so there is nothing to analyze.";
+    const live = source.liveStudy;
+    if (live === undefined)
+        return withoutFindings(source, "dry_run", null, `${opening} Findings come from live runs. The next command lists this project's studies; a study with mode: live runs participants.`, cli(`study list${source.cwdFlag}`));
+    const howLive = live.setLiveIn === undefined
+        ? `the next command runs ${live.id} live.`
+        : `set mode: live in ${live.setLiveIn}, then run the next command.`;
+    return withoutFindings(source, "dry_run", null, `${opening} Findings come from live runs: ${howLive}`, cli(`run ${live.run}${source.cwdFlag}`));
+}
 /** The findings view of a run's selected analysis, or why it has none. */
 export function analysisFindings(source) {
     if (source.mode !== undefined && source.mode !== "live")
-        return withoutFindings(source, "dry_run", null, "This is a dry run: no participant used the product, so there is nothing to analyze. Findings come from live runs.", null);
+        return dryRunFindings(source);
     const loaded = projectShareCheckedAnalysis(source.loaded);
     const analysis = loaded.analysis;
     if (analysis?.result && (loaded.state === "ready" || loaded.state === "stale")) {
@@ -130,6 +183,7 @@ export function analysisFindings(source) {
             path: path.join(source.runRoot, "analysis", analysis.id, "analysis.json"),
             summary: result.summary,
             findings: result.findings.map((finding) => findingView(finding, { ...loaded, analysis }, source.runRoot)),
+            designFindings: designFindingViews(analysis, source.runRoot),
             limitations: result.limitations,
             warnings: loaded.warnings,
         };
@@ -170,6 +224,30 @@ async function studyAnalysisOff(cwd, study) {
         return undefined;
     return resolved.config.review?.analysis === false ? study.path : undefined;
 }
+/**
+ * The study a live run can start from after a dry run: the run's own study when its file runs
+ * live, else the starter study try-live when this project has one that runs live, else the run's
+ * own study once its file is set live. A preview study only dry-runs. Undefined when none applies.
+ */
+async function liveStudyAfterDryRun(cwd, study) {
+    const resolve = async (ref) => {
+        const resolved = await resolveStudyManifest(cwd, ref).catch(() => null);
+        return resolved?.ok ? resolved.config : undefined;
+    };
+    const ownConfig = study === undefined
+        ? undefined
+        : await resolve(study.path ?? study.id).then((config) => config?.id === study.id ? config : undefined);
+    const own = study === undefined
+        ? undefined
+        : { run: study.origin === "explicit" ? (study.path ?? study.id) : study.id, id: study.id };
+    if (own !== undefined && ownConfig?.mode === "live")
+        return own;
+    if ((await resolve("try-live"))?.mode === "live")
+        return { run: "try-live", id: "try-live" };
+    if (own !== undefined && ownConfig !== undefined && study?.path !== undefined)
+        return routeOf(ownConfig) === "preview" ? undefined : { ...own, setLiveIn: study.path };
+    return undefined;
+}
 /**
  * The run's bundle mode and its selected analysis: `analysisId`, or the version `analyze show`
  * defaults to. Null when the run is missing or its storage is unsafe.
@@ -180,16 +258,18 @@ export async function readRunAnalysis(cwd, run, analysisId) {
     if (!prepared)
         return null;
     const bundle = await loadRunBundlePrepared(physical, prepared).catch(() => null);
-    const analysisOffIn = bundle?.bundle.mode === "live"
-        ? await studyAnalysisOff(physical, studyProvenanceOf(bundle.bundle))
-        : undefined;
+    const mode = bundle?.bundle.mode;
+    const study = bundle === null ? undefined : studyProvenanceOf(bundle.bundle);
+    const analysisOffIn = mode === "live" ? await studyAnalysisOff(physical, study) : undefined;
+    const liveStudy = mode !== undefined && mode !== "live" ? await liveStudyAfterDryRun(physical, study) : undefined;
     return {
         runId: runIdOf(prepared),
-        mode: bundle?.bundle.mode,
+        mode,
         runRoot: prepared.relativeRunRoot,
         loaded: await loadAnalysis(prepared, analysisId),
         cwdFlag: cwdFlag(cwd),
         ...(analysisOffIn === undefined ? {} : { analysisOffIn }),
+        ...(liveStudy === undefined ? {} : { liveStudy }),
     };
 }
 /** The view of a run that could not be found. */
@@ -250,20 +330,49 @@ function momentsText(evidence) {
         parts.push(`${plural(unframed, "item")} with no frame`);
     return parts.join(", ");
 }
+/** The capture files, relative to the run directory, in frame order. */
+function captureFiles(evidence, runRoot) {
+    return [
+        ...new Set(evidence
+            .filter((entry) => entry.capture !== null)
+            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
+            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
+    ];
+}
+/**
+ * What a reader sees first: the headline, or the reviewer's claim when a review amended the finding,
+ * since the headline and experience describe the claim it replaced. Null before headlines existed.
+ */
+function leadOf(finding) {
+    const amended = finding.correction?.status === "amended" ? finding.correction : null;
+    if (finding.headline === null)
+        return null;
+    return amended?.replacementClaim
+        ? { headline: amended.replacementClaim, corrected: true }
+        : { headline: finding.headline, corrected: false };
+}
 function findingLines(finding, runRoot) {
     const cited = [...new Set(finding.evidence.map((entry) => entry.streamId))];
     const labels = new Map(finding.affected.map((p) => [p.streamId, p.label]));
     const affectedIds = finding.affected.map((p) => p.streamId);
     const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
-    const captures = [
-        ...new Set(finding.evidence
-            .filter((entry) => entry.capture !== null)
-            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
-            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
-    ];
+    const captures = captureFiles(finding.evidence, runRoot);
     const correction = finding.correction;
+    const lead = leadOf(finding);
     return [
-        `${finding.id} ${finding.title}`,
+        ...(lead === null
+            ? [`${finding.id} ${finding.title}`]
+            : [
+                `${finding.id} ${lead.headline}`,
+                ...(lead.corrected
+                    ? [
+                        "   Corrected in human review. The reviewer's claim replaces the original headline and account.",
+                    ]
+                    : finding.experience === null
+                        ? []
+                        : [`   ${finding.experience}`]),
+                `   evidence: ${finding.title}`,
+            ]),
         `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
         `   ${finding.summary}`,
         `   affected: ${finding.affected.length} of ${plural(finding.exposedCount, "exposed participant")}`,
@@ -281,6 +390,34 @@ function findingLines(finding, runRoot) {
             ]),
     ];
 }
+function designFindingLines(finding, runRoot) {
+    const captures = captureFiles(finding.evidence, runRoot);
+    return [
+        `${finding.id} ${finding.severity}: ${finding.headline}`,
+        `   screen: ${finding.screen}`,
+        `   notice: ${finding.notice}`,
+        `   why it matters: ${finding.whyItMatters}`,
+        `   suggestion: ${finding.suggestion}`,
+        `   seen by: ${finding.seenBy.map((p) => p.label).join(", ")} · confidence: ${finding.confidence}`,
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+    ];
+}
+/** Nothing for an analysis written before design findings. */
+function designSection(view) {
+    const design = view.designFindings;
+    if (design === null)
+        return [];
+    if (design.length === 0)
+        return ["", "design findings: none in the reviewed captures"];
+    return [
+        "",
+        `design findings: ${design.length}, most severe first`,
+        ...design.flatMap((finding, index) => [
+            ...(index === 0 ? [] : [""]),
+            ...designFindingLines(finding, view.runPath ?? ""),
+        ]),
+    ];
+}
 /** The full findings block: the analysis, every finding with its evidence, and its limitations. */
 export function formatFindings(view) {
     if (view.state !== "ready" && view.state !== "stale")
@@ -292,6 +429,7 @@ export function formatFindings(view) {
         ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
         ...(view.summary ? [view.summary] : []),
         ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
+        ...designSection(view),
         ...(view.limitations.length === 0
             ? []
             : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
@@ -305,12 +443,30 @@ export function formatFindingsSummary(view, fullCommand, limit = 3) {
     if (view.state !== "ready" && view.state !== "stale")
         return [`findings: ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
     const shown = view.findings.slice(0, limit);
+    const design = view.designFindings;
     return [
         `findings: ${view.findings.length === 0 ? "none" : view.findings.length}${view.state === "stale" ? " (stale)" : ""}`,
-        ...shown.map((finding) => `- ${finding.id} ${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}: ${finding.title}`),
+        ...shown.map((finding) => {
+            const qualities = `${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}`;
+            const lead = leadOf(finding);
+            if (lead === null)
+                return `- ${finding.id} ${qualities}: ${finding.title}`;
+            return `- ${finding.id} ${lead.headline} (${lead.corrected ? "corrected in human review" : qualities})`;
+        }),
         ...(view.findings.length > limit
             ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
             : []),
+        ...(design === null
+            ? []
+            : [
+                `design findings: ${design.length === 0 ? "none" : design.length}`,
+                ...design
+                    .slice(0, limit)
+                    .map((finding) => `- ${finding.id} ${finding.severity}: ${finding.headline}`),
+                ...(design.length > limit
+                    ? [`- and ${plural(design.length - limit, "more design finding")}`]
+                    : []),
+            ]),
         `all findings: ${fullCommand}`,
     ];
 }

package/dist/cli/io.d.ts

@@ -18,7 +18,8 @@ export declare const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
  * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
- * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
+ * Removed in the first minor release on or after 2026-11-03: deprecated in 0.110.0 on 2026-10-03, it stays at least 30 days and one
+ * minor release.
  */
 export declare function envFileAliasOption(): Option;
 /** The dotenv path a command was given: `--dotenv`, or the `--env-file` alias with its warning. */

package/dist/cli/io.js

@@ -15,12 +15,13 @@ export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response."
 export const CWD_OPTION_DESCRIPTION = "Project directory.";
 export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
 export const DOTENV_OPTION_DESCRIPTION = "Load unset variables from this dotenv file. Values are never printed or saved.";
-const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in 0.112.0.";
+const ENV_FILE_RENAMED = "`--env-file` is now `--dotenv`; `--env-file` is removed in the first minor release on or after 2026-11-03.";
 /**
  * The hidden `--env-file <path>` that `--dotenv` replaced. Node scans the whole argv for
  * `--env-file` before a script runs, and stops only at `--` (src/node_dotenv.cc), so a missing file
  * exits 9 through Node and never reaches humanish. `--dotenv` does not collide.
- * Removed in 0.112.0: deprecated in 0.110.0 on 2026-10-03, it stays 30 days and one minor release.
+ * Removed in the first minor release on or after 2026-11-03: deprecated in 0.110.0 on 2026-10-03, it stays at least 30 days and one
+ * minor release.
  */
 export function envFileAliasOption() {
     return new Option("--env-file <path>").hideHelp().conflicts("dotenv");

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

@@ -1,3 +1,10 @@
+/**
+ * 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
+ * escaped form is searched for at any length, as the value is: it holds a backslash or a `%`, so it
+ * is not ordinary text.
+ */
+export declare function encodedForms(value: string): string[];
 /**
  * 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

package/dist/evidence/secret-scrub.js

@@ -25,25 +25,34 @@ function base64Middles(bytes, encoding) {
         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) {
+/**
+ * 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
+ * escaped form is searched for at any length, as the value is: it holds a backslash or a `%`, so it
+ * is not ordinary text.
+ */
+export function encodedForms(value) {
     const bytes = Buffer.from(value, "utf8");
-    const encoded = [
-        JSON.stringify(value).slice(1, -1),
+    const json = JSON.stringify(value).slice(1, -1);
+    // A serializer that writes ASCII only, such as Python's json.dumps, spells é as \u00e9.
+    const asciiJson = json.replace(/[^\x00-\x7f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+    const escaped = [json, asciiJson, JSON.stringify(json).slice(1, -1)];
+    // The encoders throw on a lone surrogate. Such a value is still found as written. encodeURI
+    // keeps a `/` or a `:` as written, as a URL path does.
+    try {
+        escaped.push(encodeURIComponent(value), encodeURI(value));
+    }
+    catch {
+        // no percent-encoded form
+    }
+    const binary = [
         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)];
+    return [value, ...escaped, ...binary.filter((form) => form.length >= MIN_ENCODED_FORM)];
 }
 /** Every occurrence of every form, outside the markers, merged where they overlap or touch. */
 function secretSpans(text, forms) {

package/dist/feedback/draft.js

@@ -120,7 +120,8 @@ export async function buildAnalysisDraft(context, options) {
     const root = path.dirname(context.loaded.bundlePath);
     const evidenceIds = new Set(finding.observations.flatMap((item) => item.evidenceIds));
     const evidence = analysis.evidence.filter((item) => evidenceIds.has(item.id));
-    const claim = correction?.status === "amended" ? correction.replacementClaim : finding.title;
+    const amended = correction?.status === "amended";
+    const claim = amended ? correction.replacementClaim : (finding.headline ?? finding.title);
     const firstLine = claim.trim().split(/\r?\n/)[0] || `Reviewed finding ${finding.id}`;
     const summary = Array.from(firstLine).length > 160
         ? Array.from(firstLine).slice(0, 159).join("") + "…"
@@ -144,10 +145,19 @@ export async function buildAnalysisDraft(context, options) {
         summary,
         expected: "Review the cited behavior against the participant assignment and confirm the expected product behavior.",
         actual: [
+            // The plain account leads; an amendment makes it stale, so the draft says so in its place.
+            ...(finding.headline === undefined
+                ? []
+                : amended
+                    ? [
+                        "This finding was corrected in human review. The reviewer's claim above replaces its original headline and account.",
+                        "",
+                    ]
+                    : finding.experience === undefined
+                        ? []
+                        : [finding.experience, ""]),
             "Independent study analysis; does not replace participant feedback or recorded completion outcomes.",
-            correction?.status === "amended"
-                ? `Amended claim: ${claim}. Original analysis: ${finding.summary}`
-                : finding.summary,
+            amended ? `Amended claim: ${claim}. Original analysis: ${finding.summary}` : finding.summary,
             `Impact: ${finding.impact}. ${finding.affectedStreamIds.length} affected / ${finding.exposedStreamIds.length} observed exposed participants. ${finding.exposureReason}`,
             `Recovery: ${finding.recovery}. Confidence: ${finding.confidence}.`,
             ...finding.observations.map((item) => `${item.basis}: ${item.claim}${item.limitation ? ` Limitation: ${item.limitation}` : ""}`),

package/dist/observer/run-routes.js

@@ -8,6 +8,7 @@ import { isLocalOnlyRunFile, isLocalOnlyRunFileIdentity } from "../run/local-onl
 import { listRuns } from "../run/stored-runs.js";
 import { readAnalysisAccounting } from "../run/costs.js";
 import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
+import { isRunOutcome } from "../run/bundle-shape.js";
 import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord, } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
@@ -138,7 +139,7 @@ async function readObserverData(runRoot, runtimeStreamUrls = []) {
         if (!bundleBytes)
             throw new Error("run.json unavailable");
         const bundle = JSON.parse(bundleBytes.toString("utf8"));
-        return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record)), runtimeStreamUrls);
+        return withRuntimeStreamUrls(withLocalRunStatus(record, buildObserverData(bundle, undefined, record), bundle.outcome), runtimeStreamUrls);
     }
     catch { }
     try {
@@ -166,12 +167,12 @@ async function readLocalRunStatus(runRoot) {
     }
 }
 /**
- * Liveness is a current read of a contained local status record, separate from run evidence.
+ * A recorded bundle outcome wins; otherwise runtime status reads the contained local heartbeat.
  * A stale heartbeat means unknown: neither an old timestamp nor a persisted PID proves that a
  * process died (the evidence may have been copied from another machine). A record its stopped
  * process wrote is interrupted. No PID is served/probed.
  */
-function withLocalRunStatus(record, input) {
+function withLocalRunStatus(record, input, outcome) {
     // A served observation must never be inherited from a persisted projection or export.
     const { runtime: _persistedRuntime, ...data } = input;
     if (record === undefined || record.runId !== data.run.runId || record.mode !== data.run.mode)
@@ -181,7 +182,10 @@ function withLocalRunStatus(record, input) {
     const updated = Date.parse(record.updatedAt);
     const timestampsValid = Number.isFinite(started) && Number.isFinite(updated) && started <= updated && updated <= now;
     let state = "unknown";
-    if (timestampsValid) {
+    if (isRunOutcome(outcome)) {
+        state = outcome.state;
+    }
+    else if (timestampsValid) {
         if (record.state === "finished") {
             state = "finished";
         }