humanish 0.111.3 → 0.112.0

package/dist/actors/scripted-browser/journey.d.ts

@@ -7,3 +7,5 @@ export declare function parseBrowserPersonaJourneyFromScenario(args: {
     failure?: string;
     journey?: BrowserPersonaJourney;
 };
+/** `value` lower-cased, with each run of other characters a `-`, cut to 80; else `fallback`. */
+export declare function publicSafeToken(value: string | undefined, fallback: string): string;

package/dist/actors/scripted-browser/journey.js

@@ -172,7 +172,8 @@ function stringValue(value) {
 function booleanValue(value) {
     return typeof value === "boolean" ? value : undefined;
 }
-function publicSafeToken(value, fallback) {
+/** `value` lower-cased, with each run of other characters a `-`, cut to 80; else `fallback`. */
+export function publicSafeToken(value, fallback) {
     const candidate = (value ?? fallback)
         .toLowerCase()
         .replace(/[^a-z0-9_.-]+/g, "-")

package/dist/actors/scripted-browser/steps.d.ts

@@ -18,6 +18,8 @@ export declare function buildBlockedBrowserPersonaSteps(args: {
     timestamp: string;
     urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
 }): BrowserPersonaStepCapture[];
+/** A step as the trace records it: its label, reason, URL and assertion reasons scrubbed. */
+export declare function scrubRecordedStep(step: BrowserPersonaStepCapture, scrub: (text: string) => string): BrowserPersonaStepCapture;
 export declare function screenshotPathForBrowserStep(surface: BrowserSurface, step: BrowserPersonaStepManifest | undefined): string;
 export declare function tracePathForBrowserSurface(surface: BrowserSurface): string;
 /**

package/dist/actors/scripted-browser/steps.js

@@ -191,6 +191,23 @@ export function buildBlockedBrowserPersonaSteps(args) {
         url: sanitizeBrowserEvidenceUrl(args.currentUrl, args.urlPolicy),
     }));
 }
+/** A step as the trace records it: its label, reason, URL and assertion reasons scrubbed. */
+export function scrubRecordedStep(step, scrub) {
+    return {
+        ...step,
+        ...(step.assertions === undefined
+            ? {}
+            : {
+                assertions: step.assertions.map((assertion) => ({
+                    ...assertion,
+                    reason: scrub(assertion.reason),
+                })),
+            }),
+        label: scrub(step.label),
+        reason: scrub(step.reason),
+        url: scrub(step.url),
+    };
+}
 export function screenshotPathForBrowserStep(surface, step) {
     assertSafeOutputPathSegment(surface.id, "Browser surface id");
     if (step) {

package/dist/analysis/diagnostics.js

@@ -1,9 +1,8 @@
 import { lstat, readdir, rmdir, unlink } from "node:fs/promises";
 import path from "node:path";
-import { decodeEscapes } from "../evidence/encoded-text.js";
 import { redactText } from "../evidence/redaction.js";
 import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, bindExistingManagedHumanishOutputDirectory, prepareManagedHumanishOutputDirectory, writeContainedOutputFile, } from "../run/contained-output.js";
-import { scrubTransientCommsText, transientCommsEncodedScrub, } from "../run/transient-comms-secrets.js";
+import { transientCommsKnownValueScrub } from "../run/transient-comms-secrets.js";
 import { ANALYSIS_ID_PATTERN } from "./types.js";
 // A rejected analyst response is kept for diagnosis under .humanish/analysis-diagnostics/<run>/,
 // outside every run directory. Export, verify and the Observer read run directories only, so the
@@ -14,19 +13,15 @@ const ANALYSIS_DIAGNOSTIC_SCHEMA = "humanish.analysis-rejected-output.v1";
 /** How many rejected outputs are kept across all runs; older ones are removed on each write. */
 export const MAX_ANALYSIS_DIAGNOSTICS = 20;
 const REDACTED = "[REDACTED_SECRET]";
-const markers = (text) => text.split(REDACTED).length - 1;
 /**
- * Scrub every string, key and scalar in the output. The encoded scrub finds a known value written
- * percent-encoded, escaped or base64-encoded and returns decoded text; a string where it finds
- * nothing keeps its original spelling, so an escape in a rejected quote stays visible, and still
- * gets the literal scrub. A number or boolean equal to a known value becomes the marker.
+ * Scrub every string, key and scalar in the output. The known-value scrub finds a value written
+ * percent-encoded, escaped or base64-encoded; a string where it finds nothing keeps its original
+ * spelling, so an escape in a rejected quote stays visible. A number or boolean equal to a known
+ * value becomes the marker.
  */
 function scrubber() {
-    const encoded = transientCommsEncodedScrub();
-    const text = (value) => {
-        const found = encoded(value);
-        return redactText(markers(found) > markers(decodeEscapes(value)) ? found : scrubTransientCommsText(value));
-    };
+    const known = transientCommsKnownValueScrub();
+    const text = (value) => redactText(known(value));
     const scrub = (value) => {
         if (typeof value === "string")
             return text(value);

package/dist/analysis/execute.d.ts

@@ -1,7 +1,7 @@
 import { type AnalysisArtifact, type AnalysisConfig, type AnalysisInput } from "./types.js";
 import { type AnalysisFetch, type AnalysisProvider } from "./provider.js";
 import type { RejectedAnalysisOutput } from "./diagnostics.js";
-export declare const ANALYSIS_PROMPT_VERSION = "study-evidence-6";
+export declare const ANALYSIS_PROMPT_VERSION = "study-evidence-7";
 export declare const isSupportedAnalysisModel: (model: string) => boolean;
 /** The OpenAI output limit when a study omits maxOutputTokens, and the most it may ask for. */
 export declare const DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS = 16384;

package/dist/analysis/execute.js

@@ -3,14 +3,14 @@ import { highDetailImageTokens } from "./image-tokens.js";
 import { createHash, randomUUID } from "node:crypto";
 import { estimateActorCost, MODEL_RATES } from "../run/pricing.js";
 import { containsSensitive } from "../evidence/redaction.js";
-import { scrubTransientCommsText } from "../run/transient-comms-secrets.js";
+import { transientCommsKnownValueScrub } from "../run/transient-comms-secrets.js";
 import { ANALYSIS_ID_PATTERN, ANALYSIS_SCHEMA, } from "./types.js";
 import { INPUT_IMAGE_DATA_URL, createAnalysisProvider, } from "./provider.js";
 import { checkAnalysisResult, hashAnalysisValue, analysisResponseSchema, analysisResultJsonSchema, validateAnalysisInputMetadata, } from "./validation.js";
 import { EVIDENCE_LIMITS } from "./evidence.js";
 import { truncatedFrameWarning, unknownNotificationsWarning, } from "../actors/codex/restricted-notifications.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
-export const ANALYSIS_PROMPT_VERSION = "study-evidence-6";
+export const ANALYSIS_PROMPT_VERSION = "study-evidence-7";
 const SUPPORTED_ANALYSIS_MODELS = Object.freeze([
     "gpt-6-astra",
     "gpt-5.5",
@@ -55,7 +55,11 @@ Harness records describe the machinery running the study. Provisioning, runtime
 
 For each finding, consolidate repeated observations into one bounded problem or recovery. Each observation states one claim, labels its basis (visual, action, participant_statement, inference), cites supporting evidence, and declares its limitation. High confidence does not turn an inference into an observation. Show which distinct participants were affected and which were demonstrably exposed to the relevant interaction. Affected IDs must be a subset of exposed IDs, and both sets must be within included participants. Explain exposure; never automatically use the full panel as a denominator. Each affected participant must have supporting observation evidence.
 
-Keep every field as qualified as its evidence. This includes headlines, summaries, outcomes, impact, exposure, recovery, confidence and the premises of proposed next checks. A cautious observation cannot support an unqualified headline. When a useful concern is established only as participant feedback, say it was reported wherever the concern is summarized. A dispatched action establishes an attempt; its success needs resulting evidence. Use recovered only when the improvement is supported for the participants being grouped. If recovery differs across participants, describe those differences and use unknown for the combined recovery instead of erasing an unresolved case. Keep distinct problems separate, especially an unresolved result and a different problem that was corrected. Reversible exploration and unmeasured pauses are not automatically product defects.
+Keep every evidence field as qualified as its evidence. This includes titles, summaries, outcomes, impact, exposure, recovery, confidence and the premises of proposed next checks. A cautious observation cannot support an unqualified title. When a useful concern is established only as participant feedback, say it was reported wherever the concern is summarized. A dispatched action establishes an attempt; its success needs resulting evidence. Use recovered only when the improvement is supported for the participants being grouped. If recovery differs across participants, describe those differences and use unknown for the combined recovery instead of erasing an unresolved case. Keep distinct problems separate, especially an unresolved result and a different problem that was corrected. Reversible exploration and unmeasured pauses are not automatically product defects.
+
+Write for the person who will act on the report: a designer, product manager or developer who did not watch the session and does not know this tool's vocabulary. Give every finding a headline and an experience. The headline is one plain sentence about what happened to the people involved, as a colleague would say it out loud. The experience is one to three plain sentences: what the person was trying to do, what got in their way, and how it seemed to feel, using the participant's own words where a quote exists. Do not use participant stream IDs, evidence IDs, or this report's evidence vocabulary (exposure, exposed, stream, capture, corroborated, established, basis, provenance) in the headline or experience. Plain is not unqualified: a concern known only from what participants said reads as something they said ("Two players said they lost track of which control had focus"), and a cause the evidence does not show is not stated as fact. The title, summary and observations keep their current precision underneath.
+
+Separately, review the supplied captures as an experienced product designer would and report designFindings: problems a designer would notice in what the screens show, whether or not any participant mentioned them. Look at the size of text and controls (too small to read or to hit comfortably at this window size), layout and density (spread too wide or packed too tight for the task), visual hierarchy, legibility and contrast, wording and labels, consistency between screens, feedback after actions, and anything that makes the product look unfinished or untrustworthy. Judge the screens as the participants' personas would meet them: who they are and what they came to do. Each design finding names the screen in plain words, says what a designer notices, why it matters to a person using the product, and one concrete suggestion. Each must cite at least one supplied capture that shows the problem, and seenByStreamIds lists only participants whose cited captures show it. Rate severity by the effect on a person using the product: major when it misleads or blocks, moderate when it slows or confuses, minor when it is polish. Report only what the captures show; no capture, no design finding. Use D1, D2, and so on as IDs. An empty designFindings array is correct when the captures show no design problem worth a designer's time. Write design findings in the same plain register as headlines.
 
 Order findings by observed task impact, replication among exposed participants, and recovery. Preserve severity and confidence as separate fields. Do not compute a numeric frustration score or universal priority score. Use F1, F2, and so on as local finding IDs. Explain ordering with concrete evidence. Provide a short, testable next check for each finding. Say when recovery was not observed rather than claiming it was impossible. Keep titles and summaries concise and specific. The overall summary must be grounded in participant reviews and observations, including successful outcomes and evidence limits.`;
 function instructions(config) {
@@ -213,9 +217,10 @@ export function preferLargerAnalysisOutput(input, config) {
     const expanded = { ...config, maxOutputTokens: MAX_ANALYSIS_OUTPUT_TOKENS };
     return estimateAnalysisAdmission(input, expanded).allowed ? expanded : config;
 }
-/** Scrub only generated prose. Source evidence, provenance and integrity hashes remain exact. */
+/** Scrub only generated prose. Source evidence, provenance and integrity hashes remain exact. A
+ * known value is found as written and in its encoded forms. */
 function scrubGeneratedNarrative(result) {
-    const scrub = scrubTransientCommsText;
+    const scrub = transientCommsKnownValueScrub();
     const observation = (value) => ({
         ...value,
         claim: scrub(value.claim),
@@ -239,6 +244,13 @@ function scrubGeneratedNarrative(result) {
             ...value.exposedStreamIds,
             ...value.observations.flatMap((item) => [item.basis, ...item.evidenceIds]),
         ]),
+        ...(result.designFindings ?? []).flatMap((value) => [
+            value.id,
+            value.severity,
+            value.confidence,
+            ...value.seenByStreamIds,
+            ...value.evidenceIds,
+        ]),
         ...(result.concernReviews ?? []).flatMap((value) => [
             value.basis,
             value.disposition,
@@ -263,12 +275,26 @@ function scrubGeneratedNarrative(result) {
         findings: result.findings.map((value) => ({
             ...value,
             title: scrub(value.title),
+            ...(value.headline === undefined ? {} : { headline: scrub(value.headline) }),
+            ...(value.experience === undefined ? {} : { experience: scrub(value.experience) }),
             summary: scrub(value.summary),
             exposureReason: scrub(value.exposureReason),
             nextStep: scrub(value.nextStep),
             priorityReason: scrub(value.priorityReason),
             observations: value.observations.map(observation),
         })),
+        ...(result.designFindings === undefined
+            ? {}
+            : {
+                designFindings: result.designFindings.map((value) => ({
+                    ...value,
+                    headline: scrub(value.headline),
+                    screen: scrub(value.screen),
+                    notice: scrub(value.notice),
+                    whyItMatters: scrub(value.whyItMatters),
+                    suggestion: scrub(value.suggestion),
+                })),
+            }),
         ...(result.concernReviews === undefined
             ? {}
             : {
@@ -281,6 +307,10 @@ function scrubGeneratedNarrative(result) {
 }
 const VALIDATION_FAILURES = Object.freeze({
     ANALYSIS_RESULT_SCHEMA_INVALID: "analysis_validation_failed_schema_invalid",
+    ANALYSIS_DESIGN_FINDING_ID_DUPLICATE: "analysis_validation_failed_design_finding_id_duplicate",
+    ANALYSIS_DESIGN_REFERENCE_INVALID: "analysis_validation_failed_design_reference_invalid",
+    ANALYSIS_DESIGN_WITHOUT_CAPTURE: "analysis_validation_failed_design_without_capture",
+    ANALYSIS_DESIGN_MEMBERSHIP_INVALID: "analysis_validation_failed_design_membership_invalid",
     ANALYSIS_INPUT_DUPLICATES: "analysis_validation_failed_input_duplicates",
     ANALYSIS_PARTICIPANT_COVERAGE_INVALID: "analysis_validation_failed_participant_coverage_invalid",
     ANALYSIS_PARTICIPANT_REFERENCE_INVALID: "analysis_validation_failed_participant_reference_invalid",

package/dist/analysis/service.js

@@ -5,6 +5,7 @@ import { lstat, mkdir, realpath, rmdir } from "node:fs/promises";
 import path from "node:path";
 import { renderObserver } from "../observer/render.js";
 import { containsSensitive } from "../evidence/redaction.js";
+import { transientCommsKnownValueScrub } from "../run/transient-comms-secrets.js";
 import { verifyRunPrepared } from "../verify/verify.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
 import { physicalCwdOf, runIdOf, resolvePhysicalCwd, validatePreparedRunRootIdentity, } from "../run/paths.js";
@@ -397,7 +398,12 @@ export async function correctAnalysis(cwd, run, options) {
         const finding = analysis?.result?.findings.find((item) => item.id === options.findingId);
         if (loaded.state !== "ready" || !analysis || !finding)
             throw new Error("ANALYSIS_CORRECTION_SOURCE_UNAVAILABLE");
-        if (containsSensitive(options.reason) || containsSensitive(options.replacementClaim ?? ""))
+        // A reviewer's claim replaces the finding's headline in every view, so it gets the same known
+        // value check as generated text: as written and encoded. Only a caller inside the run's secret
+        // scope holds those values; a separate `analyze correct` has only the pattern check.
+        const known = transientCommsKnownValueScrub();
+        const unsafe = (text) => containsSensitive(text) || known(text) !== text;
+        if (unsafe(options.reason) || unsafe(options.replacementClaim ?? ""))
             throw new Error("ANALYSIS_CORRECTION_TEXT_UNSAFE");
         const correction = {
             schema: ANALYSIS_CORRECTION_SCHEMA,

package/dist/analysis/types.d.ts

@@ -104,6 +104,11 @@ export interface AnalysisObservation {
 interface AnalysisFinding {
     id: string;
     title: string;
+    /** One plain sentence for a reader who did not watch the session. Absent in older reports. */
+    headline?: string;
+    /** One to three plain sentences: what the person tried, what got in the way, how it seemed to
+     * feel. Absent in older reports. */
+    experience?: string;
     summary: string;
     impact: "blocked_task" | "friction" | "recovery" | "uncertain";
     affectedStreamIds: string[];
@@ -115,6 +120,22 @@ interface AnalysisFinding {
     nextStep: string;
     priorityReason: string;
 }
+/** A problem a product designer would see in the cited captures, whether or not a participant
+ * mentioned it. It cites at least one capture. */
+interface AnalysisDesignFinding {
+    id: string;
+    headline: string;
+    /** The screen, in plain words. */
+    screen: string;
+    notice: string;
+    whyItMatters: string;
+    suggestion: string;
+    severity: "minor" | "moderate" | "major";
+    confidence: "low" | "medium" | "high";
+    /** Participants whose cited evidence shows the problem. */
+    seenByStreamIds: string[];
+    evidenceIds: string[];
+}
 /** Evidence-grounded disposition of a material concern, not model reasoning. */
 interface AnalysisConcernReview extends AnalysisObservation {
     disposition: "finding" | "context" | "unsupported";
@@ -128,6 +149,8 @@ export interface AnalysisResult {
     concernReviews?: AnalysisConcernReview[];
     /** Highest priority first; counts are derived from distinct stream sets. */
     findings: AnalysisFinding[];
+    /** Absent in older reports. New analyses supply it, empty when the captures show no problem. */
+    designFindings?: AnalysisDesignFinding[];
     limitations: string[];
 }
 interface OpenAIAnalysisConfig {

package/dist/analysis/validation.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { type AnalysisArtifact, type AnalysisCorrection, type AnalysisInput, type AnalysisResult } from "./types.js";
-/** Historical artifacts may omit concernReviews; every new provider response must supply it. */
+/** Historical artifacts may omit concernReviews, headlines, experiences and designFindings; every
+ * new provider response must supply them. */
 export declare const analysisResponseSchema: z.ZodObject<{
     summary: z.ZodString;
     participants: z.ZodArray<z.ZodObject<{
@@ -22,9 +23,30 @@ export declare const analysisResponseSchema: z.ZodObject<{
         }, z.core.$strict>>;
         limitations: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
+    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        basis: z.ZodEnum<{
+            action: "action";
+            inference: "inference";
+            participant_statement: "participant_statement";
+            visual: "visual";
+        }>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+        limitation: z.ZodString;
+        disposition: z.ZodEnum<{
+            context: "context";
+            finding: "finding";
+            unsupported: "unsupported";
+        }>;
+        findingId: z.ZodNullable<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strict>>>>;
+    limitations: z.ZodArray<z.ZodString>;
     findings: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
+        headline: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+        experience: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
         summary: z.ZodString;
         impact: z.ZodEnum<{
             blocked_task: "blocked_task";
@@ -59,25 +81,26 @@ export declare const analysisResponseSchema: z.ZodObject<{
         nextStep: z.ZodString;
         priorityReason: z.ZodString;
     }, z.core.$strict>>;
-    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
-        claim: z.ZodString;
-        basis: z.ZodEnum<{
-            action: "action";
-            inference: "inference";
-            participant_statement: "participant_statement";
-            visual: "visual";
+    designFindings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        headline: z.ZodString;
+        screen: z.ZodString;
+        notice: z.ZodString;
+        whyItMatters: z.ZodString;
+        suggestion: z.ZodString;
+        severity: z.ZodEnum<{
+            major: "major";
+            minor: "minor";
+            moderate: "moderate";
         }>;
-        evidenceIds: z.ZodArray<z.ZodString>;
-        limitation: z.ZodString;
-        disposition: z.ZodEnum<{
-            context: "context";
-            finding: "finding";
-            unsupported: "unsupported";
+        confidence: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            medium: "medium";
         }>;
-        findingId: z.ZodNullable<z.ZodString>;
-        reason: z.ZodString;
-    }, z.core.$strict>>>>;
-    limitations: z.ZodArray<z.ZodString>;
+        seenByStreamIds: z.ZodArray<z.ZodString>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const analysisResultJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
     summary: z.ZodString;
@@ -100,9 +123,30 @@ export declare const analysisResultJsonSchema: z.core.ZodStandardJSONSchemaPaylo
         }, z.core.$strict>>;
         limitations: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
+    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        basis: z.ZodEnum<{
+            action: "action";
+            inference: "inference";
+            participant_statement: "participant_statement";
+            visual: "visual";
+        }>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+        limitation: z.ZodString;
+        disposition: z.ZodEnum<{
+            context: "context";
+            finding: "finding";
+            unsupported: "unsupported";
+        }>;
+        findingId: z.ZodNullable<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strict>>>>;
+    limitations: z.ZodArray<z.ZodString>;
     findings: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
+        headline: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+        experience: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
         summary: z.ZodString;
         impact: z.ZodEnum<{
             blocked_task: "blocked_task";
@@ -137,25 +181,26 @@ export declare const analysisResultJsonSchema: z.core.ZodStandardJSONSchemaPaylo
         nextStep: z.ZodString;
         priorityReason: z.ZodString;
     }, z.core.$strict>>;
-    concernReviews: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodObject<{
-        claim: z.ZodString;
-        basis: z.ZodEnum<{
-            action: "action";
-            inference: "inference";
-            participant_statement: "participant_statement";
-            visual: "visual";
+    designFindings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        headline: z.ZodString;
+        screen: z.ZodString;
+        notice: z.ZodString;
+        whyItMatters: z.ZodString;
+        suggestion: z.ZodString;
+        severity: z.ZodEnum<{
+            major: "major";
+            minor: "minor";
+            moderate: "moderate";
         }>;
-        evidenceIds: z.ZodArray<z.ZodString>;
-        limitation: z.ZodString;
-        disposition: z.ZodEnum<{
-            context: "context";
-            finding: "finding";
-            unsupported: "unsupported";
+        confidence: z.ZodEnum<{
+            high: "high";
+            low: "low";
+            medium: "medium";
         }>;
-        findingId: z.ZodNullable<z.ZodString>;
-        reason: z.ZodString;
-    }, z.core.$strict>>>>;
-    limitations: z.ZodArray<z.ZodString>;
+        seenByStreamIds: z.ZodArray<z.ZodString>;
+        evidenceIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>>;
 /** Stable hashing is independent of object insertion order and excludes no fields implicitly. */
 export declare function hashAnalysisValue(value: unknown): string;

package/dist/analysis/validation.js

@@ -27,6 +27,20 @@ const observationSchema = z
     limitation: text(2000),
 })
     .strict();
+const designFindingSchema = z
+    .object({
+    id,
+    headline: label,
+    screen: label,
+    notice: text(1500).min(1),
+    whyItMatters: text(1000).min(1),
+    suggestion: text(1000).min(1),
+    severity: z.enum(["minor", "moderate", "major"]),
+    confidence: z.enum(["low", "medium", "high"]),
+    seenByStreamIds: sourceIds.min(1),
+    evidenceIds: refs,
+})
+    .strict();
 const analysisResultSchema = z
     .object({
     summary: text(4000).min(1),
@@ -51,6 +65,8 @@ const analysisResultSchema = z
         .object({
         id,
         title: label,
+        headline: label.optional(),
+        experience: text(1200).min(1).optional(),
         summary: text(4000).min(1),
         impact: z.enum(["blocked_task", "friction", "recovery", "uncertain"]),
         affectedStreamIds: sourceIds.min(1),
@@ -64,6 +80,7 @@ const analysisResultSchema = z
     })
         .strict())
         .max(100),
+    designFindings: z.array(designFindingSchema).max(40).optional(),
     concernReviews: z
         .array(observationSchema
         .extend({
@@ -77,13 +94,25 @@ const analysisResultSchema = z
     limitations,
 })
     .strict();
-/** Historical artifacts may omit concernReviews; every new provider response must supply it. */
-export const analysisResponseSchema = analysisResultSchema.required({
-    concernReviews: true,
-});
+/** Historical artifacts may omit concernReviews, headlines, experiences and designFindings; every
+ * new provider response must supply them. */
+export const analysisResponseSchema = analysisResultSchema
+    .extend({
+    findings: z
+        .array(analysisResultSchema.shape.findings.element.required({ headline: true, experience: true }))
+        .max(100),
+    designFindings: z.array(designFindingSchema).max(40),
+})
+    .required({ concernReviews: true });
 export const analysisResultJsonSchema = z.toJSONSchema(analysisResponseSchema);
-const normalizedResult = ({ concernReviews, ...result }) => ({
+const normalizedResult = ({ concernReviews, designFindings, findings, ...result }) => ({
     ...result,
+    findings: findings.map(({ headline, experience, ...finding }) => ({
+        ...finding,
+        ...(headline === undefined ? {} : { headline }),
+        ...(experience === undefined ? {} : { experience }),
+    })),
+    ...(designFindings === undefined ? {} : { designFindings }),
     ...(concernReviews === undefined ? {} : { concernReviews }),
 });
 const analysisCoverageSchema = z
@@ -349,6 +378,21 @@ export function checkAnalysisResult(input, value) {
         if (finding.affectedStreamIds.some((stream) => !citedStreams.has(stream)))
             errors.add("ANALYSIS_AFFECTED_WITHOUT_EVIDENCE");
     }
+    const designFindings = result.designFindings ?? [];
+    if (!distinct(designFindings.map((finding) => finding.id)))
+        errors.add("ANALYSIS_DESIGN_FINDING_ID_DUPLICATE");
+    for (const finding of designFindings) {
+        const refs = finding.evidenceIds.map((ref) => evidence.get(ref));
+        if (!distinct(finding.evidenceIds) || refs.some((ref) => !ref || !included.has(ref.streamId)))
+            errors.add("ANALYSIS_DESIGN_REFERENCE_INVALID");
+        if (!refs.some((ref) => ref?.capture !== null && ref?.capture !== undefined))
+            errors.add("ANALYSIS_DESIGN_WITHOUT_CAPTURE");
+        // Seen by means a cited capture of that participant shows the problem.
+        const captured = new Set(refs.flatMap((ref) => (ref?.capture ? [ref.streamId] : [])));
+        if (!distinct(finding.seenByStreamIds) ||
+            finding.seenByStreamIds.some((stream) => !included.has(stream) || !captured.has(stream)))
+            errors.add("ANALYSIS_DESIGN_MEMBERSHIP_INVALID");
+    }
     for (const review of result.concernReviews ?? []) {
         const citedStreams = checkObservation(review);
         const finding = result.findings.find((item) => item.id === review.findingId);
@@ -425,12 +469,15 @@ export function validateAnalysisArtifact(value) {
         (artifact.status === "complete" && !coverage.complete))
         throw new Error("ANALYSIS_STATUS_INVALID");
     if (artifact.result !== null) {
-        // Concern accounting became required with revision 5. Keep the boundary stable
-        // when the prompt version advances; a later prompt must not regain legacy omissions.
-        const revision = /^study-evidence-(\d+)$/.exec(artifact.promptVersion)?.[1];
-        if (revision !== undefined &&
-            Number(revision) >= 5 &&
-            artifact.result.concernReviews === undefined)
+        // Concern accounting became required with revision 5, and headlines, experiences and design
+        // findings with revision 7. Keep each boundary stable when the prompt version advances; a later
+        // prompt must not regain legacy omissions.
+        const revision = Number(/^study-evidence-(\d+)$/.exec(artifact.promptVersion)?.[1] ?? 0);
+        const result = artifact.result;
+        if ((revision >= 5 && result.concernReviews === undefined) ||
+            (revision >= 7 &&
+                (result.designFindings === undefined ||
+                    result.findings.some((finding) => finding.headline === undefined || finding.experience === undefined))))
             throw new Error("ANALYSIS_RESULT_SCHEMA_INVALID");
         validateAnalysisResult({ ...artifact, images: [] }, artifact.result);
     }

package/dist/cli/commands/runs.js

@@ -6,6 +6,7 @@ import { DEFAULT_EXPORT_MAX_BYTES, exportRun, formatExportHuman } from "../../fe
 import { listRuns, readReview } from "../../run/stored-runs.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
+import { runDisplay } from "../../run/display.js";
 import { addRunOptions, handleRun } from "./run-command.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { plural } from "../../run/text.js";
@@ -33,7 +34,7 @@ export function registerVerifyCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
-const CLEANUP_RENAMED = "`cleanup` is now `reclaim --check`; `cleanup` is removed in 0.112.0.";
+const CLEANUP_RENAMED = "`cleanup` is now `reclaim --check`; `cleanup` is removed in the first minor release on or after 2026-11-03.";
 /**
  * The deprecated `cleanup`, hidden from help: one warning, then exactly `reclaim --check`, with
  * its output and exit code. The old command read only what computer-use runs recorded and passed
@@ -244,13 +245,6 @@ const REVIEW_VERDICTS = {
     blocked: "blocked",
     timed_out: "timed out",
 };
-/** The state runDisplay gives a finished run whose own ok agrees with its verdict. */
-const VERDICT_STATES = {
-    pass: "passed",
-    fail: "failed",
-    blocked: "blocked",
-    timed_out: "timed_out",
-};
 /**
  * Review's headline: the run's display label, as `humanish runs`, review.md and the Observer show
  * it. A verdict that names another state follows in parentheses, so an interrupted run whose last
@@ -262,8 +256,8 @@ function reviewHeadline(verdict, display) {
         return REVIEW_VERDICTS[verdict];
     if (display.state === "no_verdict" || display.state === "dry_run")
         return `${display.label}; ${NOTHING_TESTED}`;
-    const judged = VERDICT_STATES[verdict];
-    return judged === undefined || judged === display.state
+    const judged = runDisplay({ liveness: "finished", verdict }).state;
+    return verdict === "contract_proof_only" || judged === display.state
         ? display.label
         : `${display.label} (verdict ${REVIEW_VERDICTS[verdict]})`;
 }