humanish 0.112.0 → 0.113.0

package/CHANGELOG.md

@@ -8,6 +8,25 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.113.0: Participant impressions, mission and persona warnings, local desktop capacity, key status, update notice (2026-10-07)
+
+humanish 0.113.0 asks computer-use participants what they thought at the end of a session, warns
+when a study scripts its participants, and says how many local desktops fit. An OpenAI or Codex
+participant ends with up to six first-person impressions: what looked unclear, unfinished or
+untrustworthy, what they liked, what they expected and did not find, and where the screen differs
+from how they do the same task in their own work or life. The trace keeps them as `impressions`,
+the Observer shows them under "What they said at the end", and analyses at prompt
+`study-evidence-8` can cite them. `study check` and `run` warn when a mission reads like a list of
+UI steps or a participant's persona has no background, and the starter personas `init` writes now
+lead with a background, which changes their participant prompt. `runtime status` and
+`doctor --study` report how many participant desktops the local runtime holds, and a live local
+study that needs more than a Mac's humanish VM holds is refused before any desktop starts.
+`humanish keys` lists each provider key with its source and never its value, and humanish says at
+most once a day, at a terminal, when a newer version is out. Live shared-world output and older
+terminal and scripted runs use plain participant captions.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.113.0)
+
 ## 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

package/README.md

@@ -138,6 +138,8 @@ npx humanish observe --run latest --open
 ```
 
 Existing `E2B_API_KEY` and `OPENAI_API_KEY` environment variables also work.
+`npx humanish keys` shows which keys are set and where each comes from, and
+`npx humanish keys set` with no vendor asks for each missing key in turn.
 `doctor --study` checks the study's local setup without launching a
 desktop or making a model request. It reports key presence, not remote key
 validity, model access, or quota. `study check` checks manifest metadata by default.
@@ -364,6 +366,7 @@ has the providers' retention terms.
 | Codex or Claude Code | The same screenshots and prompts, through your signed-in agent and its provider                                                                                                                                                                                                                                                                        | `local-agent` participants, local browser studies, the Codex analyst                                                             |
 | E2B                  | A desktop or shell running your app and everything on its screen; the repository a `clone` subject names; your working tree for a `local-tree` subject, minus gitignored files, `.env*` and other secret-shaped files; the credentials you declare for the subject app; for a terminal study with `execution.runtimeAuth: openai-env`, your OpenAI key | Every hosted study                                                                                                               |
 | PostHog              | Telemetry events, described [below](#check-what-telemetry-sends)                                                                                                                                                                                                                                                                                       | By default                                                                                                                       |
+| npm registry         | A request for the latest humanish version, with no identifying data, described [below](#check-what-telemetry-sends)                                                                                                                                                                                                                                    | At most once a day, at a terminal                                                                                                |
 
 ## Find the main commands
 
@@ -476,6 +479,14 @@ subjects, personas, prompts, paths, run ids and evidence are never sent.
 disable` or `DO_NOT_TRACK=1` turns it off. [TELEMETRY.md](TELEMETRY.md) lists
 every field.
 
+At most once a day, a command run at a terminal also asks the npm registry for
+the latest humanish version, and a later command prints one line on stderr when
+yours is older. That request is a plain `GET` of humanish's dist-tags with no
+machine id, version, command or path. It is skipped in CI, without a terminal,
+for `--json`, and with `DO_NOT_TRACK=1`, `HUMANISH_TELEMETRY_DISABLED=1` or
+`HUMANISH_NO_UPDATE_CHECK=1`. [TELEMETRY.md](TELEMETRY.md#the-update-check)
+describes it.
+
 ## Contribute
 
 Contributors: read

package/TELEMETRY.md

@@ -112,3 +112,24 @@ humanish-specific configuration. The opt-out is stored under your user config
 
 Telemetry never blocks, slows, or fails a command: it is fire-and-forget, bounded
 by a two-second timeout, and every error inside it is swallowed.
+
+## The update check
+
+A command run at a terminal also checks, at most once a day, whether a newer
+humanish is published. This is a separate request and sends no event. A
+background process asks the npm registry for
+`https://registry.npmjs.org/-/package/humanish/dist-tags` with a plain `GET`
+whose only header is `Accept`. It carries no machine id, installed version,
+command or path; the registry sees the request's source address, as it does for
+any `npm install`. The answer is cached next to the telemetry state, in
+`~/.config/humanish/update-check.json`, and a later command prints one line on
+stderr when your version is older. The check never delays or fails a command.
+
+It is skipped without a terminal, in CI, for `--json` output, for a study
+participant, and when any of these is set:
+
+```bash
+DO_NOT_TRACK=1
+HUMANISH_TELEMETRY_DISABLED=1
+HUMANISH_NO_UPDATE_CHECK=1
+```

package/dist/actors/codex/restricted-participant-policy.d.ts

@@ -1,5 +1,5 @@
 import { type CuaTurn } from "../computer-use/loop.js";
-import type { ActorExecutionProfile, ParticipantClosingReport } from "../contract.js";
+import { type ActorExecutionProfile, type ParticipantClosingReport } from "../contract.js";
 /** The declared profile. A participant replaces cliVersion with its detected CLI release, or with
  * this host's newest qualified release before its first launch. */
 export declare const PARTICIPANT_PROFILE: Readonly<ActorExecutionProfile>;
@@ -39,6 +39,26 @@ export declare const PARTICIPANT_FINAL_SCHEMA: {
                 maxLength: number;
             };
         };
+        impressions: {
+            type: string;
+            maxItems: number;
+            items: {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    kind: {
+                        type: string;
+                        enum: ("liked" | "missing" | "unclear" | "unfinished" | "unlike_my_work" | "untrustworthy")[];
+                    };
+                    text: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                    };
+                };
+            };
+        };
     };
 };
 /** humanish tool arguments, validated before the shared executor sees a batch. */

package/dist/actors/codex/restricted-participant-policy.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { BROWSER_CONTROL_LIMITS, browserControlActionSchema, browserOnlyControlActionSchema, validateBrowserControlAction, } from "../../browser-control/protocol.js";
 import { validClosingReport } from "../computer-use/loop.js";
+import { PARTICIPANT_IMPRESSION_KINDS, } from "../contract.js";
 /** The declared profile. A participant replaces cliVersion with its detected CLI release, or with
  * this host's newest qualified release before its first launch. */
 export const PARTICIPANT_PROFILE = Object.freeze({
@@ -40,7 +41,7 @@ export const PARTICIPANT_TOOL_SCHEMA = participantToolSchema();
 export const PARTICIPANT_FINAL_SCHEMA = {
     type: "object",
     additionalProperties: false,
-    required: ["outcome", "summary", "frictionReports"],
+    required: ["outcome", "summary", "frictionReports", "impressions"],
     properties: {
         outcome: { type: "string", enum: ["reached", "not_reached", "blocked"] },
         summary: { type: "string", minLength: 1, maxLength: 4000 },
@@ -49,6 +50,19 @@ export const PARTICIPANT_FINAL_SCHEMA = {
             maxItems: 8,
             items: { type: "string", minLength: 1, maxLength: 2000 },
         },
+        impressions: {
+            type: "array",
+            maxItems: 6,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["kind", "text"],
+                properties: {
+                    kind: { type: "string", enum: [...PARTICIPANT_IMPRESSION_KINDS] },
+                    text: { type: "string", minLength: 1, maxLength: 500 },
+                },
+            },
+        },
     },
 };
 /**
@@ -105,6 +119,10 @@ export function parseParticipantFinal(value) {
         done: true,
         outcome,
         message: [report.summary, ...report.frictionReports].join("\n"),
-        closingReport: { summary: report.summary, frictionReports: [...report.frictionReports] },
+        closingReport: {
+            summary: report.summary,
+            frictionReports: [...report.frictionReports],
+            ...(report.impressions === undefined ? {} : { impressions: [...report.impressions] }),
+        },
     };
 }

package/dist/actors/codex/restricted-participant.d.ts

@@ -1,4 +1,4 @@
-import type { CuaProvider } from "../computer-use/loop.js";
+import { type CuaProvider } from "../computer-use/loop.js";
 import { type RestrictedCodexSessionOptions } from "./restricted-session.js";
 import type { RestrictedCodexAnalysisErrorCode } from "./restricted-policy.js";
 import type { ReasoningEffort } from "../reasoning-effort.js";

package/dist/actors/codex/restricted-participant.js

@@ -1,5 +1,6 @@
 import {} from "../contract.js";
 import { defaultCodexCliVersion, untestedOperatorReleaseWarning } from "./codex-admission.js";
+import { IMPRESSIONS_ASK, } from "../computer-use/loop.js";
 import { ComputerUseProviderError, isComputerUseProviderError, } from "../computer-use/provider-error.js";
 import { validateBrowserControlPng, validateHeardSpeech } from "../../browser-control/protocol.js";
 import { createRestrictedCodexSession, } from "./restricted-session.js";
@@ -40,7 +41,7 @@ function deferred() {
 }
 // prose-check: model prompt (Codex reads this tool description, not a person)
 const toolDescription = (speechEnabled) => `Act on the participant's browser through humanish. Submit one to four UI actions${speechEnabled ? ", including speak when you need to reply aloud," : ""} and a short public comment; never private reasoning. humanish returns a JSON STRING with execution acknowledgments${speechEnabled ? ", speech heard from the actual participant speaker sink," : ""} and a fresh screenshot. In Code Mode use: const r = JSON.parse(await tools.humanish_ui({narration: "...", actions: [...]})); text({acknowledgments: r.acknowledgments${speechEnabled ? ", heardSpeech: r.heardSpeech" : ""}, contextHint: r.contextHint, closing: r.closing}); image(r.imageUrl). Call serially and inspect each returned screenshot${speechEnabled ? " and heardSpeech array" : ""} before deciding what to do next. A wait action lasts at most ${L.waitMs} ms; a longer wait is shortened to ${L.waitMs} ms, so wait longer with another call.${speechEnabled ? " Use speak only after the visible UI shows that you joined the call and your microphone is unmuted; it sends audio into that call." : ""} Acknowledged input does not prove an application outcome. If closing is true, stop calling tools and give your final account.`;
-const participantInstructions = (prompt, speechEnabled) => `${prompt}\n\nYou are the study participant throughout this conversation, including its closing account. Use only the supplied screenshots and humanish_ui tool to interact. The tool returns a JSON string: parse it, inspect acknowledgments${speechEnabled ? " and heardSpeech captured from the actual participant speaker sink" : ""}, and display imageUrl with Code Mode image(). Do not print the image data URL as text. Keep your persona and earlier observations throughout the session.${speechEnabled ? " A speak action plays into the participant microphone; use it only after the visible UI shows that you joined the call and the microphone is unmuted." : ""} Speak publicly about your experience, never reveal private reasoning. Completed inputs do not prove application outcomes; verify on the next screenshot. When the task ends, return only the required final JSON with outcome, summary and frictionReports. Report observed confusion and recovered mistakes as well as blockers. Do not invent observations.`;
+const participantInstructions = (prompt, speechEnabled) => `${prompt}\n\nYou are the study participant throughout this conversation, including its closing account. Use only the supplied screenshots and humanish_ui tool to interact. The tool returns a JSON string: parse it, inspect acknowledgments${speechEnabled ? " and heardSpeech captured from the actual participant speaker sink" : ""}, and display imageUrl with Code Mode image(). Do not print the image data URL as text. Keep your persona and earlier observations throughout the session.${speechEnabled ? " A speak action plays into the participant microphone; use it only after the visible UI shows that you joined the call and the microphone is unmuted." : ""} Speak publicly about your experience, never reveal private reasoning. Completed inputs do not prove application outcomes; verify on the next screenshot. When the task ends, return only the required final JSON with outcome, summary, frictionReports and impressions. Report observed confusion and recovered mistakes as well as blockers. ${IMPRESSIONS_ASK} Do not invent observations.`;
 /** Turns and failures from the native run, handed in order to the next provider request. */
 class ParticipantEvents {
     queued = [];

package/dist/actors/computer-use/loop/debrief.d.ts

@@ -1,4 +1,4 @@
-import type { ActorTrace, ParticipantClosingReport } from "../../contract.js";
+import { type ActorTrace, type ParticipantClosingReport, type ParticipantImpression } from "../../contract.js";
 import type { DebriefTrigger } from "./ending.js";
 import type { LoopSession } from "./session.js";
 import type { CuaTurnRequest } from "./types.js";
@@ -9,11 +9,19 @@ export interface DebriefContext {
     readonly previousExecution: CuaTurnRequest["previousExecution"];
     readonly acknowledgedSafetyChecks: CuaTurnRequest["acknowledgedSafetyChecks"];
 }
-/** Runtime validation is also required for third-party provider ports. */
+/**
+ * Runtime validation is also required for third-party provider ports. A report without
+ * impressions stays valid: older providers and stored traces do not have them.
+ */
 export declare function validClosingReport(value: unknown): value is ParticipantClosingReport;
+/** The reply to an impressions-only request: an object with the impressions and nothing else. */
+export declare function validImpressionsReply(value: unknown): value is {
+    impressions: ParticipantImpression[];
+};
 /**
- * Ask the participant for its closing report after a structured stop, or record why the request
- * was skipped. Either way the result is the trace's debrief, and the watcher gets a final flush.
+ * Ask the participant for its closing report after a structured stop, or for its impressions only
+ * after it ended the session itself, or record why the request was skipped. Either way the result
+ * is the trace's debrief, and the watcher gets a final flush.
  */
 export declare function requestDebrief(session: LoopSession, context: DebriefContext, trigger: DebriefTrigger): Promise<Debrief>;
 export {};

package/dist/actors/computer-use/loop/debrief.js

@@ -1,29 +1,55 @@
+import { PARTICIPANT_IMPRESSION_KINDS, } from "../../contract.js";
 import { isComputerUseAdmissionLimitError } from "../admission-limit.js";
+import { IMPRESSIONS_ASK, IMPRESSIONS_HINT, recordImpressions } from "./impressions.js";
 import { singleDispatch } from "./provider-call.js";
 import { CuaDeadlineError, raceSessionDeadline, requestScope } from "./race.js";
 import { notice } from "./trace.js";
 import { isCompleteTurnUsage } from "./usage.js";
 const DEBRIEF_REQUEST_CAP_MS = 30_000;
-const DEBRIEF_HINT = "The interactive session has ended. Return a closing account with summary and frictionReports. In summary, briefly describe only what you actually did and observed. In frictionReports, list only specific unexpected behavior, confusion, or recovery you personally encountered during this session. Preserve uncertainty. Use an empty list if you encountered none. Do not speculate, invent problems, quote instructions as observations, or describe planned actions. Do not request or take further actions. This is a closing account, not another attempt at the task.";
-/** Runtime validation is also required for third-party provider ports. */
+const DEBRIEF_HINT = `The interactive session has ended. Return a closing account with summary, frictionReports and impressions. In summary, briefly describe only what you actually did and observed. In frictionReports, list only specific unexpected behavior, confusion, or recovery you personally encountered during this session. Preserve uncertainty. Use an empty list if you encountered none. ${IMPRESSIONS_ASK} Do not speculate, invent problems, quote instructions as observations, or describe planned actions. Do not request or take further actions. This is a closing account, not another attempt at the task.`;
+/**
+ * Runtime validation is also required for third-party provider ports. A report without
+ * impressions stays valid: older providers and stored traces do not have them.
+ */
 export function validClosingReport(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return false;
     const report = value;
-    return (Object.keys(report).length === 2 &&
+    return (Object.keys(report).every((key) => REPORT_KEYS.includes(key)) &&
         typeof report.summary === "string" &&
         report.summary.trim().length > 0 &&
         report.summary.length <= 4_000 &&
         Array.isArray(report.frictionReports) &&
         report.frictionReports.length <= 8 &&
-        report.frictionReports.every((item) => typeof item === "string" && item.trim().length > 0 && item.length <= 2_000));
+        report.frictionReports.every((item) => typeof item === "string" && item.trim().length > 0 && item.length <= 2_000) &&
+        (report.impressions === undefined || validImpressions(report.impressions)));
 }
-function supportsDebrief(provider) {
-    return provider.debrief !== undefined;
+const REPORT_KEYS = ["summary", "frictionReports", "impressions"];
+/** The reply to an impressions-only request: an object with the impressions and nothing else. */
+export function validImpressionsReply(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const reply = value;
+    return Object.keys(reply).length === 1 && validImpressions(reply.impressions);
+}
+function validImpressions(value) {
+    return (Array.isArray(value) &&
+        value.length <= 6 &&
+        value.every((item) => {
+            if (item === null || typeof item !== "object" || Array.isArray(item))
+                return false;
+            const { kind, text, ...rest } = item;
+            return (Object.keys(rest).length === 0 &&
+                PARTICIPANT_IMPRESSION_KINDS.some((known) => known === kind) &&
+                typeof text === "string" &&
+                text.trim().length > 0 &&
+                text.length <= 500);
+        }));
 }
 /**
- * Ask the participant for its closing report after a structured stop, or record why the request
- * was skipped. Either way the result is the trace's debrief, and the watcher gets a final flush.
+ * Ask the participant for its closing report after a structured stop, or for its impressions only
+ * after it ended the session itself, or record why the request was skipped. Either way the result
+ * is the trace's debrief, and the watcher gets a final flush.
  */
 export async function requestDebrief(session, context, trigger) {
     const record = (status, detail, usageReported) => {
@@ -33,13 +59,13 @@ export async function requestDebrief(session, context, trigger) {
             reason: session.redactNarration(detail),
             ...(usageReported === undefined ? {} : { usageReported }),
         };
-        session.trace.record("notice", () => notice(status === "completed" ? "ok" : "warn", `participant debrief ${status}`, session.redactNarration(detail)));
+        session.trace.record("notice", () => notice(status === "completed" ? "ok" : "warn", `participant ${trigger.kind === "participant_end" ? "impressions request" : "debrief"} ${status}`, session.redactNarration(detail)));
         return debrief;
     };
     const plan = planDebrief(session, trigger);
     const debrief = "skip" in plan
         ? record("skipped", plan.skip)
-        : await debriefExchange(session, plan.provider, context, trigger, plan.boundMs, record);
+        : await debriefExchange(session, plan.ask, context, trigger, plan.boundMs, record);
     session.flush();
     return debrief;
 }
@@ -48,7 +74,8 @@ function planDebrief(session, trigger) {
     const { maxUsd, overRunBudget, estimateTurnCostUsd } = session.settings;
     if (session.trace.counts.turns === 0)
         return { skip: "the study stopped before any participant turn" };
-    if (!supportsDebrief(provider))
+    const ask = trigger.kind === "participant_end" ? provider.requestImpressions : provider.debrief;
+    if (ask === undefined)
         return { skip: "this provider does not support read-only closing reports" };
     if (usage.cleanupUnconfirmed)
         return { skip: "participant request cleanup is unconfirmed" };
@@ -80,10 +107,10 @@ function planDebrief(session, trigger) {
             skip: signal?.aborted ? "the study was cancelled" : "the session deadline was reached",
         };
     }
-    return { provider, boundMs };
+    return { ask, boundMs };
 }
-async function debriefExchange(session, provider, context, trigger, boundMs, record) {
-    const { signal } = session;
+async function debriefExchange(session, ask, context, trigger, boundMs, record) {
+    const { signal, provider } = session;
     const scope = requestScope(signal);
     const timer = setTimeout(() => scope.end(), boundMs);
     timer.unref?.();
@@ -101,12 +128,12 @@ async function debriefExchange(session, provider, context, trigger, boundMs, rec
             ...(context.acknowledgedSafetyChecks === undefined
                 ? {}
                 : { acknowledgedSafetyChecks: context.acknowledgedSafetyChecks }),
-            contextHint: DEBRIEF_HINT,
+            contextHint: trigger.kind === "participant_end" ? IMPRESSIONS_HINT : DEBRIEF_HINT,
         };
         const turn = provider.requestPolicy === "fail_closed"
-            ? await singleDispatch(session, "debrief", (dispatchSignal) => provider.debrief(request, dispatchSignal), boundMs)
-            : await raceSessionDeadline(provider.debrief(request, scope.signal), boundMs, signal);
-        return acceptDebriefTurn(session, turn, record);
+            ? await singleDispatch(session, "debrief", (dispatchSignal) => ask.call(provider, request, dispatchSignal), boundMs)
+            : await raceSessionDeadline(ask.call(provider, request, scope.signal), boundMs, signal);
+        return acceptDebriefTurn(session, turn, trigger, record);
     }
     catch (error) {
         // A failed optional report cannot rewrite the already observed structured completion.
@@ -116,7 +143,7 @@ async function debriefExchange(session, provider, context, trigger, boundMs, rec
         const detail = signal?.aborted
             ? "cancelled"
             : scope.signal.aborted || error instanceof CuaDeadlineError
-                ? "closing report deadline reached"
+                ? `${trigger.kind === "participant_end" ? "impressions request" : "closing report"} deadline reached`
                 : error instanceof Error
                     ? error.message
                     : String(error);
@@ -129,7 +156,7 @@ async function debriefExchange(session, provider, context, trigger, boundMs, rec
         scope.end();
     }
 }
-function acceptDebriefTurn(session, turn, record) {
+function acceptDebriefTurn(session, turn, trigger, record) {
     const { maxUsd, overRunBudget, estimateTurnCostUsd } = session.settings;
     session.usage.record(turn, "debrief");
     session.lastResponseId = turn.responseId ?? session.lastResponseId;
@@ -144,6 +171,15 @@ function acceptDebriefTurn(session, turn, record) {
     if (turn.actions.length > 0 || turn.pendingSafetyChecks.length > 0) {
         return record("failed", "the closing response requested actions or safety checks; none were executed and its report was not accepted", usageReported);
     }
+    if (trigger.kind === "participant_end") {
+        if (!validImpressions(turn.impressions)) {
+            return record("failed", turn.interruption === "output_limit"
+                ? "the reply was cut off by the output limit"
+                : "the reply did not contain valid impressions", usageReported);
+        }
+        session.impressions = recordImpressions(session, turn.impressions);
+        return record("completed", "one read-only impressions request; no additional desktop actions; the participant's own ending is unchanged", usageReported);
+    }
     if (!validClosingReport(turn.closingReport)) {
         return record("failed", "the closing response did not contain a valid structured participant report", usageReported);
     }
@@ -159,6 +195,7 @@ function acceptDebriefTurn(session, turn, record) {
         text: [report.summary, ...report.frictionReports].join("\n\n"),
     }));
     session.trace.bump("messages");
+    session.impressions = recordImpressions(session, turn.closingReport.impressions);
     const debrief = record("completed", "one read-only report; no additional desktop actions; original stop and task outcomes preserved", usageReported);
     return { ...debrief, report, messageId };
 }

package/dist/actors/computer-use/loop/ending.d.ts

@@ -3,9 +3,12 @@ import type { StopConditionMatch } from "../../stop-conditions.js";
 import type { LoopSession } from "./session.js";
 import { type Evidence } from "./trace.js";
 import type { CuaObservation, CuaProvider, CuaTurn } from "./types.js";
-/** A harness-observed completion after which the participant is asked for a debrief. */
+/**
+ * An ending after which the participant is asked for a debrief: a harness-observed completion, or
+ * the participant's own ending when only its impressions are missing.
+ */
 export interface DebriefTrigger {
-    readonly kind: "stop_when" | "dwell";
+    readonly kind: "stop_when" | "dwell" | "participant_end";
     /** The final observation, already captured; the debrief request sends it without observing. */
     readonly observation: CuaObservation;
 }

package/dist/actors/computer-use/loop/impressions.d.ts

@@ -0,0 +1,14 @@
+import type { ActorTrace, ParticipantImpression, ParticipantImpressions } from "../../contract.js";
+import type { LoopSession } from "./session.js";
+/** The closing-account request for impressions, shared by every provider that writes one. */
+export declare const IMPRESSIONS_ASK = "In impressions, list up to six things you noticed about the product itself, each in the first person and about something you saw in this session. Give each one a kind: unclear when something looked confusing or hard to read; unfinished when something looked broken, unpolished or out of place; untrustworthy when something made you hesitate to trust the product; liked when something worked well or felt good; missing when you expected something and did not find it; unlike_my_work when the screen differs from how you do the same task in your own work or life, only if your persona does this task outside this product. Keep each under 500 characters. Use an empty list if you have none.";
+/** The request after the participant ended the session itself without giving impressions. */
+export declare const IMPRESSIONS_HINT = "The interactive session has ended. Return only impressions. In impressions, list up to six things you noticed about the product itself, each in the first person and about something you saw in this session. Give each one a kind: unclear when something looked confusing or hard to read; unfinished when something looked broken, unpolished or out of place; untrustworthy when something made you hesitate to trust the product; liked when something worked well or felt good; missing when you expected something and did not find it; unlike_my_work when the screen differs from how you do the same task in your own work or life, only if your persona does this task outside this product. Keep each under 500 characters. Use an empty list if you have none. Do not speculate, invent problems, quote instructions as observations, or describe planned actions. Do not request or take further actions.";
+/**
+ * Record a closing account's impressions as quotable participant messages. They answer the
+ * harness's question, so they leave counts.messages, which the hollow-completion rule reads, alone.
+ */
+export declare function recordImpressions(session: LoopSession, impressions: readonly ParticipantImpression[] | undefined): ParticipantImpressions;
+/** Why a session that recorded no impressions has none: its closing request, or its stop. */
+export declare function impressionsNotCollected(debrief: ActorTrace["debrief"]): ParticipantImpressions;
+export declare function notCollected(reason: string): ParticipantImpressions;

package/dist/actors/computer-use/loop/impressions.js

@@ -0,0 +1,40 @@
+// A participant's impressions: what it says about the product at the end of a session, beyond
+// friction. Each one is recorded as its own message so the analysis can quote and cite it as a
+// participant statement, and the trace says why none were collected when a session has none.
+/** The closing-account request for impressions, shared by every provider that writes one. */
+export const IMPRESSIONS_ASK = "In impressions, list up to six things you noticed about the product itself, each in the first person and about something you saw in this session. Give each one a kind: unclear when something looked confusing or hard to read; unfinished when something looked broken, unpolished or out of place; untrustworthy when something made you hesitate to trust the product; liked when something worked well or felt good; missing when you expected something and did not find it; unlike_my_work when the screen differs from how you do the same task in your own work or life, only if your persona does this task outside this product. Keep each under 500 characters. Use an empty list if you have none.";
+/** The request after the participant ended the session itself without giving impressions. */
+export const IMPRESSIONS_HINT = `The interactive session has ended. Return only impressions. ${IMPRESSIONS_ASK} Do not speculate, invent problems, quote instructions as observations, or describe planned actions. Do not request or take further actions.`;
+/**
+ * Record a closing account's impressions as quotable participant messages. They answer the
+ * harness's question, so they leave counts.messages, which the hollow-completion rule reads, alone.
+ */
+export function recordImpressions(session, impressions) {
+    if (impressions === undefined)
+        return notCollected("the participant's closing account did not include impressions");
+    return {
+        status: "collected",
+        items: impressions.map(({ kind, text }) => {
+            const redacted = session.redactNarration(text.trim());
+            const messageId = session.trace.record("message", () => ({
+                lifecycle: "completed",
+                title: "participant impression",
+                text: `Impression (${kind.replaceAll("_", " ")}): ${redacted}`,
+            }));
+            return { kind, text: redacted, messageId };
+        }),
+    };
+}
+/** Why a session that recorded no impressions has none: its closing request, or its stop. */
+export function impressionsNotCollected(debrief) {
+    if (debrief === undefined)
+        return notCollected("the session stopped before a closing account");
+    if (debrief.status === "completed")
+        return notCollected("the participant's closing account did not include impressions");
+    const request = debrief.trigger === "participant_end" ? "impressions request" : "closing report";
+    const outcome = debrief.status === "skipped" ? "was skipped" : "failed";
+    return notCollected(`the ${request} ${outcome}: ${debrief.reason}`);
+}
+export function notCollected(reason) {
+    return { status: "not_collected", reason };
+}

package/dist/actors/computer-use/loop/session.d.ts

@@ -1,4 +1,4 @@
-import type { ActorTraceItem, ParticipantDeclaredOutcome } from "../../contract.js";
+import type { ActorTraceItem, ParticipantDeclaredOutcome, ParticipantImpressions } from "../../contract.js";
 import type { AffordanceObservation } from "../../affordance.js";
 import { TaskTracker } from "../../../study/tasks.js";
 import type { DebriefTrigger, Stop } from "./ending.js";
@@ -61,6 +61,8 @@ export declare class LoopSession {
     declaredOutcome: ParticipantDeclaredOutcome | undefined;
     /** Set by a structured stop; the debrief follows it even if the session then failed. */
     debriefTrigger: DebriefTrigger | undefined;
+    /** Set by the participant's own final account or by its closing report. */
+    impressions: ParticipantImpressions | undefined;
     private stopCause;
     private readonly scrubText;
     constructor(options: LoopRunOptions);

package/dist/actors/computer-use/loop/session.js

@@ -61,6 +61,8 @@ export class LoopSession {
     declaredOutcome;
     /** Set by a structured stop; the debrief follows it even if the session then failed. */
     debriefTrigger;
+    /** Set by the participant's own final account or by its closing report. */
+    impressions;
     stopCause;
     scrubText;
     constructor(options) {

package/dist/actors/computer-use/loop/trace.js

@@ -1,5 +1,6 @@
 import { summarizeAffordanceUse } from "../../affordance.js";
 import { ACTOR_TRACE_SCHEMA, } from "../../contract.js";
+import { impressionsNotCollected } from "./impressions.js";
 import { plural } from "../../../run/text.js";
 export function notice(status, title, text) {
     return { lifecycle: "completed", status, title, text };
@@ -129,6 +130,7 @@ export function loopResult(session, stop, debrief) {
             : {}),
         ...(session.declaredOutcome === undefined ? {} : { declaredOutcome: session.declaredOutcome }),
         ...(debrief === undefined ? {} : { debrief }),
+        impressions: session.impressions ?? impressionsNotCollected(debrief),
         ...(usage.interactionUsageIncomplete(session.capDeclared)
             ? { interactionUsageIncomplete: true }
             : {}),

package/dist/actors/computer-use/loop/types.d.ts

@@ -1,5 +1,5 @@
 import type { HeardSpeech } from "../speech.js";
-import type { ActorCapabilities, ActorConversation, ActorExecutionProfile, ActorPersonaRef, ActorSessionResult, ActorTokenUsage, ActorTrace, ActorTraceItem, ParticipantClosingReport, ParticipantDeclaredOutcome, ProviderRequestReceipt } from "../../contract.js";
+import type { ActorCapabilities, ActorConversation, ActorExecutionProfile, ActorPersonaRef, ActorSessionResult, ActorTokenUsage, ActorTrace, ActorTraceItem, ParticipantClosingReport, ParticipantDeclaredOutcome, ParticipantImpression, ProviderRequestReceipt } from "../../contract.js";
 import type { RedactionHooks } from "../../../evidence/redaction.js";
 import type { DwellWindow, StopWhen } from "../../stop-conditions.js";
 import type { StudyTask } from "../../../study/tasks.js";
@@ -200,6 +200,8 @@ export interface CuaTurn {
     outcome?: ParticipantDeclaredOutcome;
     /** Present only for an accepted structured closing account. */
     closingReport?: ParticipantClosingReport;
+    /** Present only for an accepted impressions-only closing reply. */
+    impressions?: ParticipantImpression[];
 }
 /** The model side of the loop. Self-describes its identity and capabilities. */
 export interface CuaProvider {
@@ -245,6 +247,11 @@ export interface CuaProvider {
     nextTurn(req: CuaTurnRequest, signal: AbortSignal, spend?: CuaSpendGate): Promise<CuaTurn>;
     /** Optional read-only closing report. Implementations must disable tools and make no retries. */
     debrief?: ((req: CuaTurnRequest, signal: AbortSignal) => Promise<CuaTurn>) | undefined;
+    /**
+     * Optional read-only request for impressions only, after the participant ended the session
+     * itself without them. Its turn carries `impressions`. Same rules as `debrief`.
+     */
+    requestImpressions?: ((req: CuaTurnRequest, signal: AbortSignal) => Promise<CuaTurn>) | undefined;
     /** Release the participant's model resources. Idempotent; reject if cleanup is unconfirmed. */
     close?(): Promise<void>;
 }

package/dist/actors/computer-use/loop.d.ts

@@ -2,7 +2,8 @@ import type { CuaLoopOptions, CuaLoopResult, LoopRunOptions } from "./loop/types
 export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, ShortenedWait, } from "./loop/types.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.js";
-export { validClosingReport } from "./loop/debrief.js";
+export { validClosingReport, validImpressionsReply } from "./loop/debrief.js";
+export { IMPRESSIONS_ASK } from "./loop/impressions.js";
 /**
  * Drive the loop to one explicit completion and return its CuaLoopResult: status, completion
  * reason, public reason and ActorTrace. Model-authored text passes through redactNarration before

package/dist/actors/computer-use/loop.js

@@ -1,9 +1,10 @@
 import { ComputerUseProviderError } from "./provider-error.js";
 import { runActionBatch } from "./loop/actions.js";
 import { advanceBackstop, startBackstop } from "./loop/backstop.js";
-import { requestDebrief } from "./loop/debrief.js";
+import { requestDebrief, validClosingReport } from "./loop/debrief.js";
 import * as stops from "./loop/ending.js";
 import { declaredOutcomeOf } from "./loop/ending.js";
+import { notCollected, recordImpressions } from "./loop/impressions.js";
 import { DesktopObserver } from "./loop/observation.js";
 import { retryAfterOutputLimit } from "./loop/output-limit.js";
 import { requestTurn } from "./loop/provider-call.js";
@@ -13,7 +14,8 @@ import { accountBillingConflicts } from "./loop/usage.js";
 import { loopResult, notice } from "./loop/trace.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.js";
-export { validClosingReport } from "./loop/debrief.js";
+export { validClosingReport, validImpressionsReply } from "./loop/debrief.js";
+export { IMPRESSIONS_ASK } from "./loop/impressions.js";
 /**
  * Drive the loop to one explicit completion and return its CuaLoopResult: status, completion
  * reason, public reason and ActorTrace. Model-authored text passes through redactNarration before
@@ -118,8 +120,18 @@ async function runTurns(session, conversation) {
             // The declared outcome is kept even if redacting the participant's summary fails.
             session.declaredOutcome = declaredOutcomeOf(turn);
             const ended = stops.participantEnded(turn, session.declaredOutcome, (text) => session.redactNarration(text));
+            const report = validClosingReport(turn.closingReport) ? turn.closingReport : undefined;
+            // A provider that can ask for impressions alone does so after the session, like a debrief.
+            if (report?.impressions !== undefined || session.provider.requestImpressions === undefined) {
+                session.impressions =
+                    report === undefined
+                        ? notCollected("the participant ended the session without a structured closing account")
+                        : recordImpressions(session, report.impressions);
+            }
             await observer.observeFinalTasks(turnNumber);
-            return ended;
+            return session.impressions === undefined
+                ? { ...ended, debriefTrigger: { kind: "participant_end", observation } }
+                : ended;
         }
         const batch = await runActionBatch(session, turn.actions, turn.shortenedWaits);
         conversation.previousExecution = batch.execution;