humanish 0.39.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";
@@ -22,7 +22,7 @@ export interface RunOptions {
     timeoutMs?: number;
 }
 export type RunStreamKind = "ui" | "browser" | "terminal" | "tui" | "codex-ui" | "artifact" | "summary";
-export type RunSimulationStatus = "queued" | "preparing" | "running" | "passed" | "complete" | "blocked" | "timed_out" | "failed" | "contract_proof_only";
+export type RunSimulationStatus = "queued" | "preparing" | "running" | "passed" | "abandoned" | "incomplete" | "complete" | "blocked" | "timed_out" | "failed" | "contract_proof_only";
 export interface RunStreamCompletion {
     actorLogPath?: string;
     actorLogTail?: string;
@@ -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 {
@@ -2869,7 +2916,29 @@ export async function doctor(cwdInput) {
             name: "runtime ignore",
             ok: await safeCheck(async () => (await readImplicitProjectFile(projectRoot, ".gitignore"))?.includes(".humanish/") ?? false),
             message: ".gitignore safely contains .humanish/"
-        }
+        },
+        // The optional peer dep every live browser and terminal lane needs (#346). `npx -y humanish`
+        // does not pull optional peers, so an adopter's FIRST live run used to fail on it — safely and
+        // at $0, but as a burned first impression on the flagship path. Answering it here means the
+        // readiness command actually answers readiness.
+        await (async () => {
+            const present = await safeCheck(async () => {
+                try {
+                    await import("@e2b/desktop");
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            return {
+                name: "e2b desktop sdk",
+                ok: present,
+                message: present
+                    ? "optional peer @e2b/desktop is installed; live desktop lanes can launch"
+                    : "optional peer @e2b/desktop is NOT installed — dry runs work, but any live desktop lane will fail closed. Install it with `npm i -D @e2b/desktop`."
+            };
+        })()
     ];
     return {
         schema: DOCTOR_SCHEMA,
@@ -5175,6 +5244,10 @@ function isRunSimulationStatus(value) {
         || value === "preparing"
         || value === "running"
         || value === "passed"
+        // Participant outcomes (docs/principles/three-roles.md). This runtime allowlist is the actual
+        // gate — the TS union alone does not validate a bundle read back from disk.
+        || value === "abandoned"
+        || value === "incomplete"
         || value === "complete"
         || value === "blocked"
         || value === "timed_out"