humanish 0.40.0 → 0.41.0

package/dist/run.d.ts

@@ -1,5 +1,5 @@
 import { type CodexAppServerTrace } from "./codex-app-server.js";
-import { type ActorTrace } from "./actor-contract.js";
+import { type ActorStatus, type ActorTrace } from "./actor-contract.js";
 import { type CapturedGitState } from "./core/git-state.js";
 import type { E2BDesktopModule } from "./e2b-desktop-launch.js";
 import { type PreparedRunArtifactPaths } from "./run-paths.js";
@@ -807,12 +807,65 @@ export interface RunRerunLineage {
         completionReason?: string;
     }>;
 }
+/**
+ * What happened to the PARTICIPANTS in a study, with the denominator attached.
+ *
+ * A stakeholder watching through the glass forms conclusions from vivid moments — that is the
+ * classic failure of the viewing room, and it is why researchers synthesize rather than letting the
+ * room decide. So anything shown to a stakeholder carries its count, or it becomes a machine for
+ * manufacturing certainty from n=1 (docs/principles/three-roles.md).
+ *
+ * These are OUTCOMES, not scores. `abandoned` is the most valuable thing a usability study
+ * produces, and `harnessFailed` is the only member that says the instrument, rather than the
+ * product, is what went wrong.
+ */
+export interface ParticipantOutcomes {
+    /** Participants whose sessions reached a terminal state — the denominator for every count below. */
+    total: number;
+    /** Reached the goal. */
+    reachedGoal: number;
+    /** Stopped trying. A finding about the product. */
+    abandoned: number;
+    /** Ran out of session or budget before reaching the goal. */
+    ranOut: number;
+    /** Needed an approval the run could not give. */
+    blocked: number;
+    /** The harness failed them: a dead sandbox, a provider error, a broken artifact. */
+    harnessFailed: number;
+    /**
+     * Participants who reported friction or a defect on the way, whatever their outcome.
+     *
+     * This is NOT a failure count and it overlaps the others on purpose — someone can reach the goal
+     * and still tell you the road there was broken. A live two-persona run made the case: both
+     * participants signed in, so "2/2 reached the goal" was true, and the keyboard-first one also
+     * reported that the signature step could not be completed without a mouse. Reporting only the
+     * outcome would have buried the single most useful thing that run produced.
+     */
+    reportedFriction: number;
+}
 export interface ReviewSummary {
     schema: typeof REVIEW_SCHEMA;
     verdict: "contract_proof_only" | "pass" | "fail" | "blocked" | "timed_out";
     summary: string;
     gaps: string[];
+    /**
+     * The study result, separate from the verdict above.
+     *
+     * `verdict` answers a gate-shaped question and has to collapse a run to one word. This answers
+     * the research question — what happened to the people in the study — and does not collapse: a run
+     * where two of three participants finished is not usefully "fail", and a run where the harness
+     * broke is a different thing from one where a persona gave up. Absent on a dry-run contract
+     * bundle, which has no participants.
+     */
+    participants?: ParticipantOutcomes;
 }
+/** Tally participant outcomes from actor statuses. Statuses this does not recognise are counted in
+ *  `total` but nowhere else, so the parts can never exceed the whole. */
+export declare function tallyParticipantOutcomes(statuses: readonly ActorStatus[], 
+/** Per-participant: did this one report friction or a defect? Same order as `statuses`. */
+reportedFriction?: readonly boolean[]): ParticipantOutcomes;
+/** One line a stakeholder can read, with the denominator attached to every number. */
+export declare function formatParticipantOutcomes(outcomes: ParticipantOutcomes): string;
 export declare function buildRunSource(args: {
     cwd: string;
     capturedAt?: Date | string;

package/dist/run.js

@@ -49,6 +49,53 @@ const SAFE_GIT_NOTES = new Set([
     "public-safe synthetic fixture",
     "public-safe synthetic OSS meta-lab fixture"
 ]);
+/** Tally participant outcomes from actor statuses. Statuses this does not recognise are counted in
+ *  `total` but nowhere else, so the parts can never exceed the whole. */
+export function tallyParticipantOutcomes(statuses, 
+/** Per-participant: did this one report friction or a defect? Same order as `statuses`. */
+reportedFriction = []) {
+    const tally = {
+        total: statuses.length,
+        reachedGoal: 0,
+        abandoned: 0,
+        ranOut: 0,
+        blocked: 0,
+        harnessFailed: 0,
+        reportedFriction: reportedFriction.filter(Boolean).length
+    };
+    for (const status of statuses) {
+        if (status === "passed")
+            tally.reachedGoal += 1;
+        else if (status === "abandoned")
+            tally.abandoned += 1;
+        else if (status === "incomplete" || status === "timed_out")
+            tally.ranOut += 1;
+        else if (status === "blocked")
+            tally.blocked += 1;
+        else if (status === "failed")
+            tally.harnessFailed += 1;
+    }
+    return tally;
+}
+/** One line a stakeholder can read, with the denominator attached to every number. */
+export function formatParticipantOutcomes(outcomes) {
+    if (outcomes.total === 0)
+        return "no participants reached a terminal state";
+    const parts = [`${outcomes.reachedGoal}/${outcomes.total} reached the goal`];
+    if (outcomes.abandoned > 0)
+        parts.push(`${outcomes.abandoned} gave up`);
+    if (outcomes.ranOut > 0)
+        parts.push(`${outcomes.ranOut} ran out of session`);
+    if (outcomes.blocked > 0)
+        parts.push(`${outcomes.blocked} blocked on an approval`);
+    if (outcomes.harnessFailed > 0)
+        parts.push(`${outcomes.harnessFailed} lost to a harness failure`);
+    // Last, and separate, because it cuts across the outcomes rather than partitioning them: someone
+    // can reach the goal and still have found the road there broken.
+    if (outcomes.reportedFriction > 0)
+        parts.push(`${outcomes.reportedFriction} reported friction`);
+    return parts.join(", ");
+}
 export async function buildRunSource(args) {
     const gitOptions = args.capturedAt === undefined ? {} : { capturedAt: args.capturedAt };
     return {