humanish 0.110.0 → 0.110.1

package/dist/cli/findings.js

@@ -0,0 +1,316 @@
+// A run's analysis findings for `review`, `analyze show` and the end of a live `run`: the
+// `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 { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { loadAnalysis } from "../analysis/load.js";
+import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
+import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
+import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
+import { plural } from "../run/text.js";
+import { shellQuote } from "../substrates/shell.js";
+import { analysisOutcomeText, wantsJson } from "./io.js";
+export const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
+/** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
+function cwdFlag(cwd) {
+    if (path.resolve(cwd) === process.cwd())
+        return "";
+    return ` --cwd ${/^[\w@%+=:,./-]+$/.test(cwd) ? cwd : shellQuote(cwd)}`;
+}
+function analyzeCommand(source, provider) {
+    const run = `humanish analyze --run ${source.runId}${source.cwdFlag}`;
+    return provider === "codex"
+        ? `${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);
+        }
+    const byId = new Map(analysis.evidence.map((entry) => [entry.id, entry]));
+    return [...bases].flatMap(([id, used]) => {
+        const entry = byId.get(id);
+        if (!entry)
+            return [];
+        return [
+            {
+                id,
+                streamId: entry.streamId,
+                kind: entry.kind,
+                bases: [...used],
+                frame: entry.frame,
+                elapsedMs: entry.elapsedMs,
+                at: entry.at,
+                capture: entry.capture ? path.join(runRoot, entry.capture.path) : null,
+            },
+        ];
+    });
+}
+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,
+        title: finding.title,
+        summary: finding.summary,
+        impact: finding.impact,
+        confidence: finding.confidence,
+        recovery: finding.recovery,
+        affected: finding.affectedStreamIds.map((streamId) => ({
+            streamId,
+            label: labels.get(streamId) ?? streamId,
+        })),
+        exposedCount: finding.exposedStreamIds.length,
+        evidence: evidenceOf(finding, loaded.analysis, runRoot),
+        nextStep: finding.nextStep,
+        correction: correction
+            ? {
+                status: correction.status,
+                reason: correction.reason,
+                replacementClaim: correction.replacementClaim,
+            }
+            : null,
+    };
+}
+/** A view with no findings: what happened and the command that gets them. */
+function withoutFindings(source, state, reason, message, next) {
+    return {
+        schema: ANALYSIS_FINDINGS_SCHEMA,
+        runId: source.runId,
+        state,
+        reason,
+        message,
+        next,
+        analysisId: null,
+        status: null,
+        provider: null,
+        model: null,
+        completedAt: null,
+        estimatedCostUsd: null,
+        runPath: source.runRoot || null,
+        path: null,
+        summary: null,
+        findings: [],
+        limitations: [],
+        warnings: source.loaded.warnings,
+    };
+}
+/** 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);
+    const loaded = projectShareCheckedAnalysis(source.loaded);
+    const analysis = loaded.analysis;
+    if (analysis?.result && (loaded.state === "ready" || loaded.state === "stale")) {
+        const result = analysis.result;
+        const stale = loaded.state === "stale";
+        return {
+            schema: ANALYSIS_FINDINGS_SCHEMA,
+            runId: source.runId,
+            state: loaded.state,
+            reason: stale ? (loaded.warnings[0] ?? null) : null,
+            message: stale
+                ? `The run's evidence changed after analysis ${analysis.id}, so its findings may not match the run.`
+                : `Analysis ${analysis.id} is ${analysis.status}, with ${plural(result.findings.length, "finding")}.`,
+            next: stale ? analyzeCommand(source, analysis.provider) : null,
+            analysisId: analysis.id,
+            status: analysis.status,
+            provider: analysis.provider,
+            model: analysis.config.model,
+            completedAt: analysis.completedAt,
+            estimatedCostUsd: analysis.usage.estimatedCostUsd,
+            runPath: source.runRoot,
+            path: path.join(source.runRoot, "analysis", analysis.id, "analysis.json"),
+            summary: result.summary,
+            findings: result.findings.map((finding) => findingView(finding, { ...loaded, analysis }, source.runRoot)),
+            limitations: result.limitations,
+            warnings: loaded.warnings,
+        };
+    }
+    if (loaded.warnings.includes("ANALYSIS_SENSITIVE_TEXT_QUARANTINED"))
+        return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. humanish analyze show --run ${source.runId}${source.cwdFlag} --json prints the raw record.`, null);
+    const job = loaded.automatic;
+    if (job?.state === "queued" || job?.state === "running")
+        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", `humanish review --run ${source.runId}${source.cwdFlag}`);
+    if (analysis && analysis.result === null)
+        return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
+    if (job?.state === "failed" || job?.state === "cancelled") {
+        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") {
+        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"
+            ? null
+            : `${analyzeCommand(source, undefined)}${refused ? " --dry-run" : ""}`);
+    }
+    if (job !== undefined || loaded.state === "invalid")
+        return withoutFindings(source, "unavailable", job?.reason ?? loaded.warnings[0] ?? null, "This run's analysis records could not be read or checked, so no findings are shown.", `humanish analyze list --run ${source.runId}${source.cwdFlag}`);
+    return withoutFindings(source, "none", null, "No analysis has run for this run.", analyzeCommand(source, 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.
+ */
+export async function readRunAnalysis(cwd, run, analysisId) {
+    const physical = await resolvePhysicalCwd(cwd);
+    const prepared = await resolveRunPath(physical, run).catch(() => null);
+    if (!prepared)
+        return null;
+    const bundle = await loadRunBundlePrepared(physical, prepared).catch(() => null);
+    return {
+        runId: runIdOf(prepared),
+        mode: bundle?.bundle.mode,
+        runRoot: prepared.relativeRunRoot,
+        loaded: await loadAnalysis(prepared, analysisId),
+        cwdFlag: cwdFlag(cwd),
+    };
+}
+/** The view of a run that could not be found. */
+export function missingRunFindings(cwd, run) {
+    const loaded = {
+        state: "invalid",
+        analysis: null,
+        corrections: [],
+        warnings: ["ANALYSIS_RUN_NOT_FOUND"],
+    };
+    const flag = cwdFlag(cwd);
+    return withoutFindings({ runId: run, mode: undefined, runRoot: "", loaded, cwdFlag: flag }, "unavailable", "ANALYSIS_RUN_NOT_FOUND", `Run ${run} was not found or its storage is unsafe.`, `humanish runs${flag}`);
+}
+/** The findings of a run's selected analysis, or why it has none. */
+export async function readRunFindings(cwd, run, analysisId) {
+    const source = await readRunAnalysis(cwd, run, analysisId);
+    return source ? analysisFindings(source) : missingRunFindings(cwd, run);
+}
+const IMPACT_TEXT = {
+    blocked_task: "blocked task",
+    friction: "friction",
+    recovery: "recovery",
+    uncertain: "uncertain",
+};
+const RECOVERY_TEXT = {
+    recovered: "recovered",
+    not_observed: "no recovery observed",
+    unknown: "recovery unknown",
+};
+/** `+1:05` from milliseconds since the first retained capture. */
+function elapsedText(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const ss = String(seconds % 60).padStart(2, "0");
+    return hours > 0
+        ? `+${hours}:${String(minutes % 60).padStart(2, "0")}:${ss}`
+        : `+${minutes}:${ss}`;
+}
+/** One participant's cited moments: each frame once, at its earliest cited time. */
+function momentsText(evidence) {
+    const frames = new Map();
+    let unframed = 0;
+    for (const entry of evidence) {
+        if (entry.frame === null) {
+            unframed++;
+            continue;
+        }
+        const earlier = frames.get(entry.frame);
+        if (earlier === undefined ||
+            (entry.elapsedMs !== null && (earlier ?? Infinity) > entry.elapsedMs))
+            frames.set(entry.frame, entry.elapsedMs);
+    }
+    const parts = [...frames]
+        .sort(([a], [b]) => a - b)
+        .map(([frame, ms]) => `frame ${frame}${ms === null ? "" : ` at ${elapsedText(ms)}`}`);
+    if (unframed > 0)
+        parts.push(`${plural(unframed, "item")} with no frame`);
+    return parts.join(", ");
+}
+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 correction = finding.correction;
+    return [
+        `${finding.id} ${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")}`,
+        ...streams.map((streamId) => {
+            const moments = momentsText(finding.evidence.filter((entry) => entry.streamId === streamId));
+            const label = `${labels.get(streamId) ?? streamId}${labels.has(streamId) ? "" : " (cited, not affected)"}`;
+            return `   - ${label}${moments ? `: ${moments}` : ""}`;
+        }),
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+        `   next step: ${finding.nextStep}`,
+        ...(correction === null
+            ? []
+            : [
+                `   human review: ${correction.status}, ${correction.reason}${correction.replacementClaim ? ` Amended claim: ${correction.replacementClaim}` : ""}`,
+            ]),
+    ];
+}
+/** 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")
+        return [`findings: none. ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
+    const model = [view.provider, view.model].filter(Boolean).join(" ");
+    const cost = view.estimatedCostUsd === null ? "" : `, estimated $${view.estimatedCostUsd.toFixed(2)}`;
+    return [
+        `findings: ${view.findings.length} from analysis ${view.analysisId} (${view.status}, ${model}${cost})`,
+        ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
+        ...(view.summary ? [view.summary] : []),
+        ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
+        ...(view.limitations.length === 0
+            ? []
+            : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
+        ...view.warnings.map((warning) => `warning: ${warning}`),
+        "",
+        `analysis: ${view.path}`,
+    ];
+}
+/** At most `limit` findings, one line each, and the command that prints all of them. */
+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);
+    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}`),
+        ...(view.findings.length > limit
+            ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
+            : []),
+        `all findings: ${fullCommand}`,
+    ];
+}
+/**
+ * The end of a live run's human output, after its `analysis:` line: the findings of the analysis
+ * the run just completed. Prints nothing for --json, or when the run's analysis did not complete,
+ * since that line already says why.
+ */
+export async function writeRunFindings(command, io, cwd, result) {
+    const outcome = result.automaticAnalysis;
+    const analysisId = outcome?.result?.analysisId;
+    if (wantsJson(command) ||
+        result.runId === undefined ||
+        analysisId === undefined ||
+        (outcome?.state !== "complete" && outcome?.state !== "partial"))
+        return;
+    try {
+        const view = await readRunFindings(cwd, result.runId, analysisId);
+        const full = `humanish review --run ${view.runId}${cwdFlag(cwd)}`;
+        io.writeOut(`${formatFindingsSummary(view, full).join("\n")}\n`);
+    }
+    catch {
+        // The run's own result is already printed; review reads the same record later.
+    }
+}

package/dist/cli/first-run-path.d.ts

@@ -15,11 +15,12 @@ export interface FirstRunEnvironment {
      */
     hasDesktopSdk: boolean;
     /**
-     * Whether humanish itself is installed in this project rather than running from an npx cache.
-     * It changes what advice is true: a one-shot `npx humanish` resolves its optional peer relative
-     * to itself, so "install the peer here" cannot work; humanish has to be installed alongside it.
+     * The command that installs `@e2b/desktop` where this humanish resolves it, ahead of
+     * `npx humanish`: beside humanish in its project, or humanish and the peer together in this one
+     * when humanish runs from an npx cache, a global install or another directory. Undefined where
+     * `npm i` would prune a node_modules that no package.json declares.
      */
-    installedInProject: boolean;
+    desktopPeerCommand: string | undefined;
     /** A provider API key for the model. */
     hasProviderKey: boolean;
     /** The coding agents already signed in locally: Codex, Claude Code, or both. */

package/dist/cli/first-run-path.js

@@ -79,13 +79,16 @@ export function firstRunSteps(env) {
             : `${preferredAgent(env)?.label} (already signed in, so no API key is needed)`;
         // Everything the step needs, in one line. Splitting it across two commands means the second
         // one fails, which is the same dead end this guidance exists to remove.
+        if (!env.hasDesktopSdk && env.desktopPeerCommand === undefined) {
+            steps.push({
+                command: `${HUMANISH} doctor`,
+                why: "the hosted starter needs the desktop SDK, and installing it from here would remove what this directory's node_modules holds; doctor names the command to run from your project's directory",
+            });
+            return steps;
+        }
         const command = env.hasDesktopSdk
             ? `${HUMANISH} run try-live`
-            : env.installedInProject
-                ? `npm i -D @e2b/desktop && ${HUMANISH} run try-live`
-                : // Running from an npx cache: installing only the peer here would not be found, because
-                    // Node resolves it relative to humanish. Both, or neither.
-                    `npm i -D humanish @e2b/desktop && ${HUMANISH} run try-live`;
+            : `${env.desktopPeerCommand} && ${HUMANISH} run try-live`;
         steps.push({
             command,
             why: `a live study: one participant drives a real app in a hosted desktop, using ${brain}` +
@@ -99,7 +102,7 @@ export function firstRunSteps(env) {
     }
     steps.push({
         command: `${HUMANISH} keys set openai`,
-        why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actors[0].type: local-agent" +
+        why: "openai-computer-use needs an API key; to use a Codex or Claude Code login instead, sign in and change the study to actor.type: local-agent" +
             localUnavailable,
     });
     return steps;
@@ -134,8 +137,12 @@ export function agentsSection() {
         "humanish run local-browser # your loopback app; no E2B or model API key",
         "humanish run try-live      # demo app study: E2B plus the selected participant's authentication",
         "humanish verify --run latest --json   # is the evidence share-safe",
+        "humanish review --run <id>  # the run's outcome and its analysis findings",
         "```",
         "",
+        "- After a live run, run `humanish review --run <id>` (or `--json`) and report its findings to the",
+        "  person you are working for: each one's title, impact, confidence, recovery and cited captures.",
+        "  When it shows no findings, report its message and the command it names.",
         "- Studies are declared in `humanish/studies/*.yaml`. Edit `try-live.yaml`'s `subject` to point",
         "  at this project's own app once you have seen a run work.",
         "- Configure the local study without editing YAML: `humanish init --yes --local-browser",
@@ -144,7 +151,7 @@ export function agentsSection() {
         "  bundles into an issue; `humanish feedback issue` writes a redacted, share-safe draft.",
         "- `humanish tui` is for people and refuses to run in an agent session. Use the `--json`",
         "  commands above instead, and tell the person you are working for that `humanish tui` exists.",
-        "- A live run spends money. `execution.caps.maxUsd` in each study caps estimated model spend: the run",
+        "- A live run spends money. `caps.maxUsd` in each study caps estimated model spend: the run",
         "  stops before its next request once the estimate passes it, so the last request can go over, and",
         "  hosted desktop time is billed on top. Do not raise it without asking the person you are working for.",
         "",

package/dist/cli/io.js

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, Option } from "commander";
-import { loadEnvFile } from "../keys/env-file.js";
+import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
 import { deriveRunFacts } from "./telemetry.js";
 import { warnAndQueue, withQueuedWarnings } from "./deprecations.js";
@@ -90,6 +90,7 @@ export async function applyEnvFileOption(args) {
         }
         for (const name of result.loaded)
             env[name] = stagedEnv[name];
+        recordDotenvNames(env, result.loaded);
         args.onLoaded?.({ path: args.envFile, names: result.loaded });
     }
     if (args.discoverKeys !== false) {

package/dist/cli/product-sentence.d.ts

@@ -1,6 +1,6 @@
 /**
- * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
- * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
- * equal.
+ * The product in one sentence. package.json's description, `humanish --help` and bare `humanish`
+ * use it, and line 3 of `README.md` and the humanish skill's description open with it;
+ * tests/cli/product-sentence.test.ts holds them equal.
  */
 export declare const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/product-sentence.js

@@ -1,6 +1,6 @@
 /**
- * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
- * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
- * equal.
+ * The product in one sentence. package.json's description, `humanish --help` and bare `humanish`
+ * use it, and line 3 of `README.md` and the humanish skill's description open with it;
+ * tests/cli/product-sentence.test.ts holds them equal.
  */
 export const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/keys/env-file.d.ts

@@ -11,5 +11,9 @@ export interface EnvFileLoadResult {
         message: string;
     };
 }
+/** Records in `env` the names a `--dotenv` file set there. */
+export declare function recordDotenvNames(env: NodeJS.ProcessEnv, names: readonly string[]): void;
+/** The names `--dotenv` set in `env`, as recordDotenvNames recorded them. */
+export declare function dotenvSetNames(env: Readonly<Record<string, string | undefined>>): Set<string>;
 export declare function loadEnvFile(cwd: string, envFile: string, env?: NodeJS.ProcessEnv): Promise<EnvFileLoadResult>;
 export {};

package/dist/keys/env-file.js

@@ -2,6 +2,23 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 const ENV_FILE_RESULT_SCHEMA = "humanish.env-file-result.v1";
 const envNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Names a `--dotenv` file set, kept as a comma list in the environment the values went into, so a
+ * process humanish starts with that environment (a run the TUI launches) knows them too. A
+ * host-side participant (the Claude Code local agent) never gets these names, even ones it would
+ * otherwise keep, such as a proxy.
+ */
+const DOTENV_NAMES = "HUMANISH_DOTENV_NAMES";
+/** Records in `env` the names a `--dotenv` file set there. */
+export function recordDotenvNames(env, names) {
+    if (names.length === 0)
+        return;
+    env[DOTENV_NAMES] = [...new Set([...dotenvSetNames(env), ...names])].join(",");
+}
+/** The names `--dotenv` set in `env`, as recordDotenvNames recorded them. */
+export function dotenvSetNames(env) {
+    return new Set((env[DOTENV_NAMES] ?? "").split(",").filter((name) => name.length > 0));
+}
 export async function loadEnvFile(cwd, envFile, env = process.env) {
     const resolvedCwd = path.resolve(cwd);
     const envPath = path.resolve(resolvedCwd, envFile);

package/dist/observer/data.d.ts

@@ -1,5 +1,6 @@
 import { type ActorEnding } from "../actors/stop-cause.js";
 import type { RunBundle, RunCostSummary, RunEvent, RunSimulation } from "../run/bundle.js";
+import { type RunDisplay } from "../run/display.js";
 import type { RunStream, RunStreamKind } from "../run/streams.js";
 export declare const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
 interface ObserverArtifactLink {
@@ -20,7 +21,14 @@ export interface ObserverData {
     run: {
         runId: string;
         mode: RunBundle["mode"];
+        /** The participants' verdict. `display` says whether the run passed. */
         status: RunBundle["review"]["verdict"];
+        /**
+         * How the run reads (runDisplay in src/run/display.ts): `passed` only when the verdict is pass
+         * and run.json's outcome does not say the run failed. Absent in observer-data.json written
+         * before it existed.
+         */
+        display?: RunDisplay;
         title: string;
         createdAt: string;
         simCount: number;
@@ -109,7 +117,12 @@ interface ObserverLaneGroup {
     surface?: string;
     caseGroup?: string;
 }
-export declare function buildObserverData(bundle: RunBundle, generatedAt?: string): ObserverData;
+/**
+ * The Observer's projection of a bundle. `statusRecord` is the run's status.json, read for a
+ * bundle with no outcome in run.json: a run in progress, interrupted, or recorded before run.json
+ * carried its outcome.
+ */
+export declare function buildObserverData(bundle: RunBundle, generatedAt?: string, statusRecord?: unknown): ObserverData;
 /** Refresh presentation from recorded actor evidence, including older exported snapshots. */
 export declare function withObserverEndings(data: ObserverData): ObserverData;
 export {};

package/dist/observer/data.js

@@ -2,6 +2,7 @@ import { actorEnding } from "../actors/stop-cause.js";
 import { isCommsReceivingEvidence, receivingAnalysisContext } from "../comms/receiving-evidence.js";
 import { formatParticipantOutcomes, formatRunTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
 import { cuaGoalSource, CUA_COMPLETION_NOTE } from "../actors/goal-source.js";
+import { bundleDisplayFacts, runDisplay } from "../run/display.js";
 export const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
 /** Discard a forged or stale runtime grant before projecting persisted evidence. */
 export function recordedStreamEmbed(embed) {
@@ -19,7 +20,12 @@ const allKinds = [
     "artifact",
     "summary",
 ];
-export function buildObserverData(bundle, generatedAt = new Date().toISOString()) {
+/**
+ * The Observer's projection of a bundle. `statusRecord` is the run's status.json, read for a
+ * bundle with no outcome in run.json: a run in progress, interrupted, or recorded before run.json
+ * carried its outcome.
+ */
+export function buildObserverData(bundle, generatedAt = new Date().toISOString(), statusRecord) {
     const byKind = Object.fromEntries(allKinds.map((kind) => [kind, 0]));
     const events = [...(bundle.events ?? [])];
     // Analysis cites this source-backed aggregate as context, not a participant
@@ -32,14 +38,17 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
     const streams = (bundle.streams ?? []).map((stream) => {
         const sim = bundle.simulations.find((candidate) => candidate.id === stream.simId) ??
             fallbackSimulation(bundle, stream);
-        // A natural session can finish its protocol while the participant explicitly reports a
-        // blocker. Match the review's typed-outcome rule without rewriting the raw trace or
-        // guessing from prose. Never turn an active or failed harness into a participant outcome.
-        const status = (stream.status === "passed" || stream.status === "complete") &&
-            stream.actor?.completionReason === "goal_satisfied" &&
-            stream.actor.declaredOutcome === "blocked"
-            ? "blocked"
-            : stream.status;
+        // The judge's status for the participant wins where the run recorded one, so a participant
+        // the verdict counted as blocked or as never engaging shows that way here. A bundle written
+        // before the judge's status was recorded keeps the typed-outcome reading: a natural session
+        // that finished while declaring a blocker. Never turn an active or failed harness into a
+        // participant outcome.
+        const status = stream.judgedStatus ??
+            ((stream.status === "passed" || stream.status === "complete") &&
+                stream.actor?.completionReason === "goal_satisfied" &&
+                stream.actor.declaredOutcome === "blocked"
+                ? "blocked"
+                : stream.status);
         byKind[stream.kind] += 1;
         return {
             ...stream,
@@ -77,6 +86,7 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
             runId: bundle.runId,
             mode: bundle.mode,
             status: bundle.review.verdict,
+            display: runDisplay(bundleDisplayFacts(bundle, statusRecord)),
             title: `${bundle.scenario.title} - ${bundle.persona.name}`,
             createdAt: bundle.createdAt,
             simCount: bundle.simCount ?? bundle.simulations.length,

package/dist/observer/library.d.ts

@@ -1,3 +1,4 @@
+import type { RunDisplay } from "../run/display.js";
 export interface LibraryHistory {
     latestRunId: string | null;
     runs: Array<{
@@ -5,7 +6,10 @@ export interface LibraryHistory {
         createdAt: string | null;
         mode: string | null;
         href: string;
+        /** The participants' verdict. `display` says whether the run passed. */
         status: string;
+        /** How the run reads (runDisplay in src/run/display.ts); absent when its data could not be read. */
+        display?: RunDisplay;
         /** Current contained status-record observation, separate from the evidence verdict. */
         runtimeState?: "running" | "finished" | "interrupted" | "unknown";
         streamCount: number;

package/dist/observer/library.js

@@ -1,9 +1,10 @@
-const STATUS_TONES = {
-    passed: "#3fb970",
-    running: "#4f8ff7",
-    failed: "#e5534b",
-    blocked: "#d29922",
-    timed_out: "#d29922",
+// The pip color for each RunDisplay tone; a run with no display gets the neutral gray.
+const DISPLAY_TONES = {
+    pass: "#3fb970",
+    live: "#4f8ff7",
+    fail: "#e5534b",
+    warn: "#d29922",
+    neutral: "#57606f",
 };
 export function renderLibraryHtml(history, opts) {
     const emptyState = opts.safe
@@ -83,7 +84,7 @@ main { padding: 1rem 1.1rem 3rem; max-width: 44rem; margin: 0 auto; }
 }
 // prose-check: script (the library page's JavaScript)
 function libraryClientJs() {
-    const tones = JSON.stringify(STATUS_TONES);
+    const tones = JSON.stringify(DISPLAY_TONES);
     return `
 (function () {
   var TONES = ${tones};
@@ -103,9 +104,11 @@ function libraryClientJs() {
       link.href = run.href;
       var top = document.createElement("div");
       top.className = "run-top";
+      var display = run.display || null;
+      var live = display !== null && display.state === "running";
       var pip = document.createElement("span");
-      pip.className = run.status === "running" ? "pip running" : "pip";
-      pip.style.background = TONES[run.status] || "#57606f";
+      pip.className = live ? "pip running" : "pip";
+      pip.style.background = (display && TONES[display.tone]) || TONES.neutral;
       var id = document.createElement("span");
       id.className = "run-id";
       id.textContent = run.runId;
@@ -116,15 +119,15 @@ function libraryClientJs() {
         latest.className = "badge latest";
         latest.textContent = "latest";
         top.appendChild(latest);
-      } else if (run.status === "running") {
-        var live = document.createElement("span");
-        live.className = "badge";
-        live.textContent = "live";
-        top.appendChild(live);
+      } else if (live) {
+        var badge = document.createElement("span");
+        badge.className = "badge";
+        badge.textContent = "live";
+        top.appendChild(badge);
       }
       var meta = document.createElement("div");
       meta.className = "run-meta";
-      var metaBits = [run.mode || "unknown", run.streamCount + " participants", run.createdAt || ""];
+      var metaBits = [display ? display.label : "", run.mode || "unknown", run.streamCount + " participants", run.createdAt || ""];
       // Labeled cost token: ALWAYS "~$X est." (never a bare "$X"), so the library never implies an
       // authoritative charge. Null = omitted (advisory, fail-open on display).
       if (run.costLabel) {