humanish 0.111.4 → 0.112.0

package/CHANGELOG.md

@@ -8,6 +8,24 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.112.0: Plain finding headlines, design findings, plain captions, DO_NOT_TRACK for terminal participants (2026-10-07)
+
+humanish 0.112.0 writes findings and captions for someone who did not watch the session, and
+terminal participants send `DO_NOT_TRACK=1` by default. Each analysis finding leads with a plain
+headline and an account of what the person tried, what got in their way and how it seemed to feel;
+its title, summary and observations stay underneath as the evidence. Analyses also report design
+findings: problems a product designer would notice in the captures, each with a severity and at
+least one cited capture. `review --json` carries them as `analysis.designFindings`, and the
+analysis prompt is `study-evidence-7`. Participant captions name the person, such as "Lobby host,
+phone", and every route's run summary says how many participants took part and how many reached
+the goal. Terminal participant and product setup commands run with `DO_NOT_TRACK=1`; set
+`execution.terminal.doNotTrack: false` to study a product's telemetry. `humanish runs` and the
+Observer now read a run with no outcome and a running simulation as interrupted, as the TUI,
+`stats` and `verify` already did. The `--env-file` and `cleanup` aliases are removed in the first
+minor release on or after 2026-11-03.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.112.0)
+
 ## 0.111.4: Encoded known values scrubbed, scripted traces scrubbed, a live command after a dry run (2026-10-06)
 
 humanish 0.111.4 scrubs a run's known values from more of its evidence and fixes three messages.

package/dist/actors/computer-use/openai-conversation.d.ts

@@ -0,0 +1,91 @@
+import type { CuaTurn, CuaTurnRequest } from "./loop.js";
+import type { ReasoningEffort } from "../reasoning-effort.js";
+import type { ActorConversation } from "../contract.js";
+import { type OpenAiReasoningSummary } from "./openai-wire.js";
+/** How a conversation starts. The model settings stay fixed for the whole session. */
+export interface OpenAiConversationSettings {
+    readonly model: string;
+    readonly reasoningEffort: ReasoningEffort;
+    readonly maxOutputTokens?: number;
+    readonly safetyIdentifier?: string;
+    /** The summaries to ask for until the account or model rejects them; undefined asks for none. */
+    readonly reasoningSummary: OpenAiReasoningSummary | undefined;
+    /** Carry the conversation on the client from the first request (explicit_context). */
+    readonly zeroDataRetention: boolean;
+    /** The clock the trace's record reads. */
+    readonly now: () => number;
+}
+/**
+ * One request of the conversation. Its new items are built once, so every attempt at it, and the
+ * reply it accepts, see the same ones.
+ */
+export interface ConversationRequest {
+    /** The body as the conversation stands now, so an attempt after a rejection shows its effect. */
+    body(): Record<string, unknown>;
+    /**
+     * The request was answered: records a participant request with what it carried, moves the
+     * conversation on to the reply and returns the reply's turn.
+     */
+    accept(reply: unknown): CuaTurn;
+}
+/** Which answer told the provider that the organization keeps no server-side conversation. */
+export type ZdrRejection = NonNullable<ActorConversation["rejection"]>;
+export declare class OpenAiConversation {
+    private readonly settings;
+    private lastResponseId;
+    /** computer_call ids the next request owes an output for. */
+    private pendingCallIds;
+    /** Accepted replies so far; the next request is number `replies + 1`. */
+    private replies;
+    /** The whole conversation, which explicit-context requests carry within its token budget. */
+    private readonly carried;
+    private mode;
+    /** Undefined once the account or model rejected reasoning summaries. */
+    private reasoningSummary;
+    private readonly evidence;
+    constructor(settings: OpenAiConversationSettings);
+    /**
+     * The next request, carrying `req`'s screen: the opening request, or the outputs the latest
+     * reply's computer calls are owed. A closing report asks for a strict JSON report and no tools.
+     */
+    request(req: CuaTurnRequest, closing?: boolean): ConversationRequest;
+    /**
+     * The organization rejected server-side state: carry the conversation on the client from the
+     * request being sent, and record which answer made the switch. False when the conversation is
+     * already carried, so the rejection stands.
+     */
+    switchToExplicitContext(rejection: ZdrRejection): boolean;
+    /**
+     * The account or model rejected reasoning summaries: stop asking for the rest of the session,
+     * from the request being sent. False when none are asked for, so the rejection stands.
+     */
+    dropReasoningSummaries(): boolean;
+    /**
+     * Whether the server holds the whole session, so a closing report threaded on it reads every
+     * turn. An explicit-context conversation summarizes its oldest turns past its budget, configured
+     * or switched to at runtime.
+     */
+    get serverHoldsSession(): boolean;
+    /** The trace's account of how the conversation was carried (ActorConversation). */
+    record(): ActorConversation;
+    /**
+     * The items a request adds to the conversation: the opening message with the first screen, or
+     * an output for each pending computer_call with the latest screenshot and any hint.
+     */
+    private newItems;
+    private context;
+    /**
+     * A participant request: the opening request, or a continuation carrying `sent`. A threaded
+     * continuation names the previous response; an explicit-context one carries the conversation
+     * ahead of `sent`.
+     */
+    private turnBody;
+    /** The read-only closing report: no tools, a small output limit, a strict schema. */
+    private closingBody;
+    /**
+     * Move the conversation on to a reply to a request that added `sent`. A participant reply cut
+     * off by the output limit is set aside, so the next request is the same one again
+     * (outputLimitRetry); its actions never run, so no call output is owed for them.
+     */
+    private accept;
+}

package/dist/actors/computer-use/openai-conversation.js

@@ -0,0 +1,209 @@
+import { CarriedConversation, estimateTokens } from "./openai-context.js";
+import { buildCallOutput, buildContinuationRequest, buildInitialRequest, hintItems, openingMessage, parseOpenAiResponse, } from "./openai-wire.js";
+/** The closing report's output limit: its own cap, or the declared limit when that is lower. */
+const CLOSING_OUTPUT_LIMIT = 1024;
+export class OpenAiConversation {
+    settings;
+    lastResponseId;
+    /** computer_call ids the next request owes an output for. */
+    pendingCallIds = [];
+    /** Accepted replies so far; the next request is number `replies + 1`. */
+    replies = 0;
+    /** The whole conversation, which explicit-context requests carry within its token budget. */
+    carried = new CarriedConversation();
+    mode;
+    /** Undefined once the account or model rejected reasoning summaries. */
+    reasoningSummary;
+    evidence;
+    constructor(settings) {
+        this.settings = settings;
+        this.mode = settings.zeroDataRetention ? "explicit_context" : "threaded";
+        this.reasoningSummary = settings.reasoningSummary;
+        this.evidence = new ConversationRecord(settings.zeroDataRetention, settings.now);
+    }
+    /**
+     * The next request, carrying `req`'s screen: the opening request, or the outputs the latest
+     * reply's computer calls are owed. A closing report asks for a strict JSON report and no tools.
+     */
+    request(req, closing = false) {
+        const sent = this.newItems(req);
+        return {
+            body: () => (closing ? this.closingBody(req, sent) : this.turnBody(req, sent)),
+            accept: (reply) => this.accept(reply, closing, sent),
+        };
+    }
+    /**
+     * The organization rejected server-side state: carry the conversation on the client from the
+     * request being sent, and record which answer made the switch. False when the conversation is
+     * already carried, so the rejection stands.
+     */
+    switchToExplicitContext(rejection) {
+        if (this.mode === "explicit_context")
+            return false;
+        this.evidence.switched(rejection);
+        this.mode = "explicit_context";
+        return true;
+    }
+    /**
+     * The account or model rejected reasoning summaries: stop asking for the rest of the session,
+     * from the request being sent. False when none are asked for, so the rejection stands.
+     */
+    dropReasoningSummaries() {
+        if (this.reasoningSummary === undefined)
+            return false;
+        this.reasoningSummary = undefined;
+        return true;
+    }
+    /**
+     * Whether the server holds the whole session, so a closing report threaded on it reads every
+     * turn. An explicit-context conversation summarizes its oldest turns past its budget, configured
+     * or switched to at runtime.
+     */
+    get serverHoldsSession() {
+        return this.mode === "threaded" && this.lastResponseId !== undefined;
+    }
+    /** The trace's account of how the conversation was carried (ActorConversation). */
+    record() {
+        return this.evidence.snapshot(this.mode);
+    }
+    /**
+     * The items a request adds to the conversation: the opening message with the first screen, or
+     * an output for each pending computer_call with the latest screenshot and any hint.
+     */
+    newItems(req) {
+        if (this.replies === 0)
+            return [openingMessage(req.instructions, req.observation.screenshot)];
+        return [
+            ...this.pendingCallIds.map((id) => buildCallOutput(id, req.observation.screenshot, req.acknowledgedSafetyChecks)),
+            ...hintItems(req.contextHint),
+        ];
+    }
+    context(instructions) {
+        const { settings } = this;
+        return {
+            stateless: this.mode === "explicit_context",
+            model: settings.model,
+            instructions,
+            reasoningEffort: settings.reasoningEffort,
+            ...(settings.maxOutputTokens === undefined
+                ? {}
+                : { maxOutputTokens: settings.maxOutputTokens }),
+            ...(this.reasoningSummary === undefined ? {} : { reasoningSummary: this.reasoningSummary }),
+            ...(settings.safetyIdentifier === undefined
+                ? {}
+                : { safetyIdentifier: settings.safetyIdentifier }),
+        };
+    }
+    /**
+     * A participant request: the opening request, or a continuation carrying `sent`. A threaded
+     * continuation names the previous response; an explicit-context one carries the conversation
+     * ahead of `sent`.
+     */
+    turnBody(req, sent) {
+        const ctx = this.context(req.instructions);
+        if (this.replies === 0)
+            return buildInitialRequest(ctx, req.observation.screenshot);
+        return buildContinuationRequest({
+            ctx,
+            previousResponseId: this.lastResponseId,
+            callOutputs: [...sent],
+            ...(this.mode === "explicit_context" ? { explicitContextItems: this.carried.carried() } : {}),
+        });
+    }
+    /** The read-only closing report: no tools, a small output limit, a strict schema. */
+    closingBody(req, sent) {
+        return {
+            ...this.turnBody(req, sent),
+            tool_choice: "none",
+            max_output_tokens: Math.min(this.settings.maxOutputTokens ?? CLOSING_OUTPUT_LIMIT, CLOSING_OUTPUT_LIMIT),
+            text: {
+                format: {
+                    type: "json_schema",
+                    name: "participant_closing_report",
+                    strict: true,
+                    schema: {
+                        type: "object",
+                        additionalProperties: false,
+                        required: ["summary", "frictionReports"],
+                        properties: {
+                            summary: { type: "string" },
+                            frictionReports: { type: "array", items: { type: "string" } },
+                        },
+                    },
+                },
+            },
+        };
+    }
+    /**
+     * Move the conversation on to a reply to a request that added `sent`. A participant reply cut
+     * off by the output limit is set aside, so the next request is the same one again
+     * (outputLimitRetry); its actions never run, so no call output is owed for them.
+     */
+    accept(reply, closing, sent) {
+        // Recorded before the reply is accepted: accepting can cut the carried history, and the record
+        // counts what this request carried.
+        if (!closing)
+            this.evidence.requested(this.mode, this.carried, sent);
+        const parsed = parseOpenAiResponse(reply);
+        if (!closing && parsed.turn.interruption === "output_limit")
+            return parsed.turn;
+        if (parsed.turn.responseId !== undefined)
+            this.lastResponseId = parsed.turn.responseId;
+        this.pendingCallIds = parsed.callIds;
+        this.replies += 1;
+        this.carried.accept(this.replies, sent, parsed.outputItems);
+        return parsed.turn;
+    }
+}
+/** The trace's account of how a session carried its conversation (ActorConversation). */
+class ConversationRecord {
+    now;
+    explicitReason;
+    rejection;
+    switchedAt;
+    switchedAtRequest;
+    summarizedTurns = 0;
+    requests = [];
+    constructor(configured, now) {
+        this.now = now;
+        if (configured)
+            this.explicitReason = "configured";
+    }
+    /** The organization rejected server-side state, so the request being sent is explicit_context. */
+    switched(rejection) {
+        this.explicitReason = "zdr_rejection";
+        this.rejection = rejection;
+        this.switchedAt = new Date(this.now()).toISOString();
+        // Counted like requests[], which includes replies set aside at their output limit.
+        this.switchedAtRequest = this.requests.length + 1;
+    }
+    /** A participant request went out with `sent` after `conversation`. */
+    requested(mode, conversation, sent) {
+        if (mode !== "explicit_context") {
+            this.requests.push({ mode: "threaded" });
+            return;
+        }
+        const carried = conversation.size();
+        // Only summaries a request carried count; the conversation also trims after the last reply.
+        this.summarizedTurns = carried.notedTurns;
+        this.requests.push({
+            mode: "explicit_context",
+            carriedExchanges: carried.exchanges,
+            carriedScreenshots: carried.screenshots,
+            estimatedInputTokens: carried.estimatedTokens + estimateTokens(sent),
+        });
+    }
+    snapshot(mode) {
+        return {
+            mode,
+            ...(this.explicitReason === undefined ? {} : { explicitReason: this.explicitReason }),
+            ...(this.rejection === undefined ? {} : { rejection: this.rejection }),
+            ...(this.switchedAt === undefined ? {} : { switchedAt: this.switchedAt }),
+            ...(this.switchedAtRequest === undefined
+                ? {}
+                : { switchedAtRequest: this.switchedAtRequest }),
+            summarizedTurns: this.summarizedTurns,
+            requests: this.requests.map((request) => ({ ...request })),
+        };
+    }
+}

package/dist/actors/computer-use/openai-provider.js

@@ -1,16 +1,16 @@
 import { validClosingReport } from "./loop.js";
 import { ComputerUseAdmissionLimitError, isComputerUseAdmissionLimitError, } from "./admission-limit.js";
 import { ComputerUsePromptRefusedError } from "./provider-error.js";
-import { CarriedConversation } from "./openai-context.js";
-import { acceptReply, ConversationRecord, debriefRequestBody, turnInputItems, turnRequestBody, } from "./openai-requests.js";
-import { asRecord, optionalString, parseOpenAiResponse, } from "./openai-wire.js";
+import { OpenAiConversation, } from "./openai-conversation.js";
+import { asRecord, optionalString } from "./openai-wire.js";
 import { redactText } from "../../evidence/redaction.js";
 import { isMaxOutputTokens } from "../output-token-limit.js";
 import { prepareContainedOutputFile, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../../run/contained-output.js";
 import { OPENAI_RESPONSES_URL } from "../openai-endpoint.js";
 // A public-safe re-derivation of the OpenAI Responses API computer-use provider,
 // behind the CuaProvider port from src/actors/computer-use/loop.ts. The pure wire mapping
-// (openAiActionToCua, parseOpenAiResponse and the request builders) is in openai-wire.ts.
+// (openAiActionToCua, parseOpenAiResponse and the request builders) is in openai-wire.ts, and
+// what each request carries, with the trace's record of it, is in openai-conversation.ts.
 // This module is the live shim: createOpenAiResponsesProvider does a raw POST to the
 // Responses endpoint (no SDK dependency) through an injectable FetchLike seam, so the retry,
 // ZDR fallback, and state threading are testable with a fake.
@@ -412,24 +412,17 @@ export function createOpenAiResponsesProvider(options) {
     // An unset or empty capture variable leaves capture off.
     const capture = createWireCapture(optionalString((options.env ?? process.env)[WIRE_CAPTURE_ENV]?.trim()));
     let interactionUsageIncomplete = false;
-    const settings = {
+    const conversation = new OpenAiConversation({
         model,
         reasoningEffort,
         ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
         ...(options.safetyIdentifier === undefined
             ? {}
             : { safetyIdentifier: options.safetyIdentifier }),
-    };
-    const state = {
-        lastResponseId: undefined,
-        pendingCallIds: [],
-        replies: 0,
-        conversation: new CarriedConversation(),
-        mode: options.zeroDataRetention ? "explicit_context" : "previous_response_id",
-        // Latches to undefined (stop asking) for the rest of the session when the
-        // account/model rejects the summary request; see OpenAiResponsesProviderOptions.
         reasoningSummary: options.reasoningSummary === "off" ? undefined : (options.reasoningSummary ?? "auto"),
-    };
+        zeroDataRetention: options.zeroDataRetention === true,
+        now: options.now ?? Date.now,
+    });
     const transport = {
         endpoint: options.endpoint ?? OPENAI_RESPONSES_URL,
         apiKey: options.apiKey,
@@ -441,25 +434,21 @@ export function createOpenAiResponsesProvider(options) {
         },
     };
     const post = (body, signal, retries = maxRetries, interaction = true, spend) => postResponse(transport, body, signal, retries, interaction, spend);
-    const record = new ConversationRecord(options.zeroDataRetention === true, options.now ?? Date.now);
     // POST with the recoverable-policy latches: a ZDR rejection switches to explicit-context mode; a
     // reasoning-summary rejection latches summaries off. Each latch can flip only once, so the loop
     // is bounded; anything else rethrows. The body is rebuilt per attempt so a flipped latch shows.
-    const postTurn = async (req, sent, signal, spend) => {
+    const postTurn = async (request, signal, spend) => {
         if (options.singleDispatch === true)
-            return post(turnRequestBody(settings, state, req, sent), signal, 0);
+            return post(request.body(), signal, 0);
         for (;;) {
             try {
-                return await post(turnRequestBody(settings, state, req, sent), signal, maxRetries, true, spend);
+                return await post(request.body(), signal, maxRetries, true, spend);
             }
             catch (error) {
-                if (error instanceof SummaryRejectionError && state.reasoningSummary !== undefined) {
-                    state.reasoningSummary = undefined;
+                if (error instanceof SummaryRejectionError && conversation.dropReasoningSummaries()) {
                     continue;
                 }
-                if (error instanceof ZdrError && state.mode !== "explicit_context") {
-                    record.switched(error.rejection);
-                    state.mode = "explicit_context";
+                if (error instanceof ZdrError && conversation.switchToExplicitContext(error.rejection)) {
                     continue;
                 }
                 throw error;
@@ -468,29 +457,26 @@ export function createOpenAiResponsesProvider(options) {
     };
     const requestTurn = async (req, signal, closing = false, spend) => {
         await capture.prepareNext();
-        const sent = turnInputItems(state, req);
+        const request = conversation.request(req, closing);
         // A closing report makes exactly one request: no HTTP or policy-latch retries.
         const raw = closing
-            ? await post(debriefRequestBody(settings, state, req, sent), signal, 0, false)
-            : await postTurn(req, sent, signal, spend);
-        if (!closing)
-            record.requested(state, sent);
-        const parsed = parseOpenAiResponse(raw);
-        acceptReply(state, parsed, closing, sent);
+            ? await post(request.body(), signal, 0, false)
+            : await postTurn(request, signal, spend);
+        const turn = request.accept(raw);
         if (closing) {
             // Refusals, incomplete output, malformed JSON, and invalid shapes remain no-report results.
             // Never promote raw JSON or a fallback paragraph into a structured finding.
             try {
-                const report = JSON.parse(parsed.turn.message ?? "");
+                const report = JSON.parse(turn.message ?? "");
                 if (asRecord(raw).status === "completed" && validClosingReport(report)) {
-                    return { ...parsed.turn, closingReport: report };
+                    return { ...turn, closingReport: report };
                 }
             }
             catch {
                 /* A failed optional closing account keeps its usage and no report. */
             }
         }
-        return parsed.turn;
+        return turn;
     };
     return {
         id: "openai-responses-cu",
@@ -512,15 +498,13 @@ export function createOpenAiResponsesProvider(options) {
         },
         nextTurn: (req, signal, spend) => requestTurn(req, signal, false, spend),
         get conversation() {
-            return record.snapshot(state);
+            return conversation.record();
         },
-        // An explicit-context conversation summarizes its oldest turns past its budget, so it may not
-        // hold the whole session a retrospective report needs. This getter follows both configured
-        // ZDR and a runtime policy latch.
+        // A retrospective report reads the session the server holds; see serverHoldsSession.
         get debrief() {
-            return state.mode === "explicit_context" || state.lastResponseId === undefined
-                ? undefined
-                : (req, signal) => requestTurn(req, signal, true);
+            return conversation.serverHoldsSession
+                ? (req, signal) => requestTurn(req, signal, true)
+                : undefined;
         },
     };
 }

package/dist/actors/contract.d.ts

@@ -191,6 +191,8 @@ export interface ParticipantClosingReport {
 export interface ActorRuntimeProvenance {
     schema: "humanish.actor-runtime.v1";
     package: string;
+    /** Terminal command telemetry opt-out; absent in older bundles. */
+    doNotTrack?: boolean;
     requestedVersion: string;
     observedVersion?: string;
     versionStatus: "unobserved" | "verified" | "failed";

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,