humanish 0.107.0 → 0.109.0

package/dist/routes/computer-use/single-bundle.d.ts

@@ -16,7 +16,7 @@ export declare function buildSingleParticipantBundle(args: {
     /** The run's verdict, from the judge. */
     verdict: Verdict;
     realEmail?: boolean;
-    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and study. */
     run: BundleRun;
     actorId: string;
     appUrl: string;
@@ -26,8 +26,8 @@ export declare function buildSingleParticipantBundle(args: {
     surface?: string;
     caseGroup?: string;
     dryRun: boolean;
-    labId: string;
-    labTitle?: string;
+    studyId: string;
+    studyTitle?: string;
     mission: string;
     assignment?: RunStream["assignment"];
     persona: ActorPersonaRef;
@@ -44,20 +44,20 @@ export declare function buildSingleParticipantBundle(args: {
     isMobile?: boolean;
     screenshots: string[];
     /** Relative run-dir path of the digest-only comms-thread evidence artifact (humanish.comms-thread.v1),
-     *  when a comms lab captured mail; registered as a "log" stream artifact. */
+     *  when a comms study captured mail; registered as a "log" stream artifact. */
     commsArtifactPath?: string;
     /**
      * Capture-time screenshot policy ("blurred" when policies.redactScreenshots, else "raw").
      * When a session ran, its trace's `redaction.screenshots` is the evidence-of-record and
-     * wins; this fallback keeps labels honest for frames written before a mid-session failure
-     * (no trace exists to testify then). Defaults to "raw" — the engine default.
+     * wins; this fallback labels the frames written before a mid-session failure
+     * (no trace exists to testify then). Defaults to "raw", the engine default.
      */
     captureRedaction?: "raw" | "blurred";
     session?: CuaLoopResult;
     sessionError?: string;
     /**
-     * The route's own credibility read of a goal_satisfied session (#476). The actor's status is
-     * evidence of what it CLAIMED; whether the harness counts the claim is decided by the route
+     * The route's own credibility read of a goal_satisfied session. The actor's status is
+     * evidence of what it claimed; whether the harness counts the claim is decided by the route
      * (zero engagement, a final message that describes a blocker). The review has to say the same
      * thing the participant's exit code says, or the durable bundle reports a participant reaching the
      * goal on a run the harness refused to count.
@@ -72,9 +72,9 @@ export declare function buildSingleParticipantBundle(args: {
      * + digests only, never values or command text), including the subject's state story. */
     subjectProvenance?: CuaSubjectProvenanceArg;
     /**
-     * Entry kind for the non-clone subject.declared event (invariant 5 — declare what the subject
-     * WAS). "local-app": an already-running LOCAL dev server driven in-process, un-pinnable —
-     * declared honestly as caller-provisioned/unpinned with no E2B. Absent: a plain app-url entry.
+     * Entry kind for the non-clone subject.declared event, which declares what the subject
+     * was. "local-app": an already-running local dev server driven in-process, un-pinnable, and
+     * declared as caller-provisioned/unpinned with no E2B. Absent: a plain app-url entry.
      */
     entryKind?: "local-app";
     /** The custom E2B desktop template (image) this participant launched on, when configured (provenance). */

package/dist/routes/computer-use/single-bundle.js

@@ -1,4 +1,4 @@
-import { participantAssignment } from "../../lab/participant-assignment.js";
+import { participantAssignment } from "../../study/participant-assignment.js";
 import { redactText } from "../../evidence/redaction.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import {} from "../../run/streams.js";
@@ -7,6 +7,7 @@ import { describeSubjectState, participantFeedbackCandidates, phaseEventIdSuffix
 import { participantStatus as participantStatusFor } from "../../run/judge.js";
 import { buildRunCostSummary } from "../../run/cost-summary.js";
 import { participantEvent, participantIds, participantRecord, participantStream, } from "../../run/participant-records.js";
+import { plural } from "../../run/text.js";
 /** The one participant's record and stream ids: sim-001 and stream-001. */
 const SINGLE = participantIds(0);
 /** The participant's runner: a hosted E2B desktop, a local VM desktop, or the in-process route. */
@@ -24,7 +25,7 @@ function browserPlace(args) {
             return "in a hosted desktop browser";
     }
 }
-/** Run-level cost ESTIMATE (advisory; omitted when nothing was priced and no sandbox ran). */
+/** Run-level cost estimate (advisory; omitted when nothing was priced and no sandbox ran). */
 function runCost(args) {
     return buildRunCostSummary({
         participants: args.session
@@ -52,15 +53,15 @@ function participantView(args, publicAppUrl) {
         ? "Live computer-use session is running; stream auth URL is available only through the attached Observer server."
         : (args.session?.reason ??
             args.sessionError ??
-            "Contract bundle only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.");
+            "Dry run: the evidence shape was written without launching a desktop or spending provider tokens.");
     const lastScreenshot = args.screenshots[args.screenshots.length - 1];
     const desktopGeometry = args.desktopRoute === false
         ? undefined
         : (args.desktopGeometry ?? {
             screen: { requested: { width: args.resolution[0], height: args.resolution[1] } },
         });
-    // Honest labels (invariant 6: claims match mechanism): every screenshot label names the
-    // run's ACTUAL mode. The session trace is the evidence-of-record; the capture policy covers
+    // Claims match mechanism: every screenshot label names the
+    // run's actual mode. The session trace is the evidence-of-record; the capture policy covers
     // frames written before a mid-session failure produced a trace.
     const traceScreenshotMode = args.session?.trace.redaction.screenshots;
     const screenshotMode = traceScreenshotMode === "raw" || traceScreenshotMode === "blurred"
@@ -80,7 +81,7 @@ function singleSimulation(args, view) {
     const { publicAppUrl, status, reason } = view;
     return participantRecord(SINGLE, 1, {
         personaId: args.persona.id,
-        scenarioId: `cua-${args.labId}`,
+        scenarioId: `cua-${args.studyId}`,
         status,
         streamKind: "browser",
         mode: "browser-sim",
@@ -91,8 +92,8 @@ function singleSimulation(args, view) {
             : args.inProgress === true
                 ? `Computer-use actor (${args.actorId}) is driving the subject app ${browserPlace(args)}.`
                 : args.sessionError !== undefined
-                    ? `Computer-use lab failed before a terminal session verdict: ${args.sessionError}`
-                    : `Contract participant for the computer-use actor (${args.actorId}) against ${publicAppUrl}.`,
+                    ? `The computer-use run failed before a terminal session verdict: ${args.sessionError}`
+                    : `Computer-use actor (${args.actorId}) against ${publicAppUrl}; no session ran.`,
         startedAt: args.run.createdAt,
         updatedAt: args.run.createdAt,
     });
@@ -107,13 +108,13 @@ function singleStream(args, view) {
         ...(args.surface === undefined ? {} : { surface: args.surface }),
         ...(args.caseGroup === undefined ? {} : { caseGroup: args.caseGroup }),
         kind: "browser",
-        label: `CUA browser — ${args.labId}`,
+        label: `${args.participantId ?? "lane-01"} · browser`,
         status,
         transport: "snapshot",
         updatedAt: args.run.createdAt,
         embed: lastScreenshot
-            ? { kind: "screenshot", url: lastScreenshot, title: `CUA desktop (${screenshotMode})` }
-            : { kind: "placeholder", title: "CUA desktop" },
+            ? { kind: "screenshot", url: lastScreenshot, title: `Desktop (${screenshotMode})` }
+            : { kind: "placeholder", title: "Desktop" },
         ...(desktopGeometry?.viewport === undefined
             ? {}
             : {
@@ -133,7 +134,7 @@ function singleStream(args, view) {
             ...(args.session ? { actorStatus: args.session.status } : {}),
             ...(lastScreenshot ? { screenshotUrl: lastScreenshot } : {}),
         },
-        // The seam this lab exists to fill: the provider-neutral actor evidence projection.
+        // The seam this route exists to fill: the provider-neutral actor evidence projection.
         ...(args.session ? { actor: args.session.trace } : {}),
         artifacts: [
             { label: "run bundle", path: "run.json", kind: "bundle" },
@@ -164,7 +165,7 @@ function singleEvents(args, view) {
             at: args.run.createdAt,
             level: "info",
             type: "cua-lab.run.created",
-            message: `Created computer-use lab run for ${args.labId} (actor ${args.actorId}).`,
+            message: `Created a computer-use run for ${args.studyId} (actor ${args.actorId}).`,
         },
         args.subjectProvenance
             ? participantEvent(SINGLE, {
@@ -172,7 +173,7 @@ function singleEvents(args, view) {
                 at: args.run.createdAt,
                 level: "info",
                 type: "cua-lab.subject.provenance",
-                // HONEST WORDING: claim "cloned/packed and served" only when it actually happened.
+                // Claim "cloned/packed and served" only when it actually happened.
                 message: `${subjectProvenanceMessage(args.subjectProvenance, publicAppUrl, args.dryRun, args.session !== undefined)} (subject env names: ${args.subjectProvenance.envNames.length > 0 ? args.subjectProvenance.envNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(args.subjectProvenance.state, args.dryRun)}.`,
             })
             : participantEvent(SINGLE, {
@@ -180,13 +181,13 @@ function singleEvents(args, view) {
                 at: args.run.createdAt,
                 level: "info",
                 type: "cua-lab.subject.declared",
-                // Invariant 5: declare what the subject WAS, including the ABSENCE of a pin. A
-                // local-app / in-process subject is an already-running LOCAL dev server the caller
-                // provisioned; it cannot be commit-pinned, so its provenance is honestly UNPINNED and
+                // Declare what the subject was, including the absence of a pin. A
+                // local-app / in-process subject is an already-running local dev server the caller
+                // provisioned; it cannot be commit-pinned, so its provenance is unpinned and
                 // no E2B desktop was created. A plain app-url entry runs inside the desktop sandbox, or,
                 // on the local VM, reaches the host's loopback from the VM's browser.
                 message: args.entryKind === "local-app"
-                    ? `Subject app declared at ${publicAppUrl} (already-running LOCAL dev server driven in-process; NO clone, NO E2B desktop). Provenance: caller-provisioned and UNPINNED — a running dev server cannot be commit-pinned.`
+                    ? `Subject app declared at ${publicAppUrl}: a running local dev server driven in this process, with no clone and no E2B desktop. Provenance: provided by the caller and unpinned, because a running dev server has no commit to pin.`
                     : runnerSubstrate(args) === "local-desktop"
                         ? `Subject app declared at ${publicAppUrl} (the host's loopback, opened from a browser on a local VM).`
                         : `Subject app declared at ${publicAppUrl} (loopback inside the desktop sandbox).`,
@@ -220,12 +221,12 @@ function singleEvents(args, view) {
                         at: args.run.createdAt,
                         level: "info",
                         type: "cua-lab.contract.ready",
-                        message: "Dry-run contract bundle ready; switch scenario.mode to live for a real desktop session.",
+                        message: "Dry-run bundle ready; switch scenario.mode to live for a real desktop session.",
                     }),
     ];
     const record = (event) => events.push(participantEvent(SINGLE, event));
     // Persisted phase trail (real boot timing, not just a coarse provenance sentence): one
-    // RunEvent per COMPLETED phase boundary (started events never persist here; they carry no
+    // RunEvent per completed phase boundary (started events never persist here; they carry no
     // durationMs). ok:false phases warn rather than error, since the failing phase's own thrown
     // error already becomes the terminal cua-lab.session.error event above.
     let phaseEventSeq = 3;
@@ -251,17 +252,15 @@ function singleEvents(args, view) {
 }
 function singleReview(args, view, stream) {
     const { reason } = view;
-    // A funnel with a denominator of one is still the funnel — and its absence stays honest: no
+    // A funnel with a denominator of one is still the funnel, and its absence stays recorded: no
     // declared protocol (or a dry run) means no `tasks` field, never an empty one.
     const singleRunTasks = args.inProgress !== true && args.session?.trace.taskFunnel !== undefined
         ? aggregateTaskFunnels([args.session.trace.taskFunnel])
         : undefined;
-    // What happened to the participant, as the route judged it — the same rule the fan-out roll-up
-    // applies (participantStatusForOutcome). Before #476 this read the actor's own status, so a
-    // run the route refused as "not a credible pass" was written up as verdict pass, 1/1 reached
-    // the goal, and every projection of the bundle (Observer tally, `runs`, the status index)
-    // repeated it. Found on a real drawDB run whose participant wrote "Blocked after partial
-    // completion".
+    // What happened to the participant, as the route judged it: the same rule the fan-out roll-up
+    // applies (participantStatus in src/run/judge.ts). Reading the actor's own status instead would write up
+    // a run the route refused as "not a credible pass" as verdict pass, 1/1 reached the goal, and
+    // every projection of the bundle (Observer tally, `runs`, the status index) would repeat it.
     const participantStatus = args.session === undefined
         ? undefined
         : participantStatusFor(args.session.status, args.credibility);
@@ -286,7 +285,7 @@ function singleReview(args, view, stream) {
             ? []
             : args.inProgress === true
                 ? ["Live desktop session is still running."]
-                : ["Live desktop session not yet run (dry-run contract only)."],
+                : ["Live desktop session not yet run (dry run only)."],
     }, [stream]);
     return review;
 }
@@ -314,21 +313,21 @@ export function buildSingleParticipantBundle(args) {
         persona: {
             id: args.persona.id,
             name: `Computer-use operator (${args.persona.id})`,
-            source: `lab:${args.labId}`,
+            source: `study:${args.studyId}`,
             sourceDigest: args.persona.promptDigest,
         },
         scenario: {
-            id: `cua-${args.labId}`,
-            title: args.labTitle ?? `Computer-use lab: ${args.labId}`,
+            id: `cua-${args.studyId}`,
+            title: args.studyTitle ?? `Computer-use run: ${args.studyId}`,
             goal: redactText(args.mission),
-            source: `lab:${args.labId}`,
+            source: `study:${args.studyId}`,
             sourceDigest: args.persona.promptDigest,
         },
         lifecycle: [
             {
                 at: args.run.createdAt,
                 event: "cua-lab.run.created",
-                message: `Created computer-use lab run with one participant in a desktop browser (actor ${args.actorId}).`,
+                message: `Created a computer-use run with one participant in a desktop browser (actor ${args.actorId}).`,
             },
         ],
         simulations: [simulation],
@@ -337,23 +336,23 @@ export function buildSingleParticipantBundle(args) {
         redaction: {
             status: "passed",
             notes: traceScreenshotMode === "raw"
-                ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are FULL-FIDELITY (raw), retained for local use — NOT redacted for publishing; set policies.redactScreenshots: true to blur a share-as-is bundle."
+                ? "Typed text is recorded as its length only, and reasoning and messages pass through text redaction. Screenshots are unblurred and kept for local use; they are not redacted for publishing. Set policies.redactScreenshots: true to blur screenshots in a bundle you plan to share."
                 : traceScreenshotMode === "blurred"
                     ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are blurred at capture (policies.redactScreenshots: true) for a share-as-is bundle."
                     : args.screenshots.length > 0
-                        ? `Session ended before a trace was recorded; ${args.screenshots.length} already-written frame(s) follow the capture policy (${screenshotMode}). Typed text is recorded as length only and reasoning/messages pass through text redaction.`
+                        ? `Session ended before a trace was recorded; ${plural(args.screenshots.length, "already-written frame")} ${args.screenshots.length === 1 ? "follows" : "follow"} the capture policy (${screenshotMode}). Typed text is recorded as length only and reasoning/messages pass through text redaction.`
                         : "No screenshots captured. Typed text is recorded as length only and reasoning/messages pass through text redaction whenever a session runs.",
         },
         artifacts: bundleArtifacts(),
         review,
-        // What the participant reported, when it reported anything (#392). Dry-run and in-progress
-        // bundles carry none — there is no participant yet to quote.
+        // What the participant reported, when it reported anything. Dry-run and in-progress
+        // bundles carry none: there is no participant yet to quote.
         feedbackCandidates: args.dryRun || args.inProgress === true
             ? []
             : participantFeedbackCandidates({
                 runId: args.run.runId,
-                scenarioId: `cua-${args.labId}`,
-                adapterId: args.labId,
+                scenarioId: `cua-${args.studyId}`,
+                adapterId: args.studyId,
                 goal: redactText(args.mission),
                 substrate: runnerSubstrate(args),
                 participants: [
@@ -378,8 +377,8 @@ export function buildSingleParticipantBundle(args) {
         ...(args.providerResources === undefined || args.providerResources.length === 0
             ? {}
             : { providerResources: args.providerResources }),
-        // Structured subject provenance (invariant 5): code pin + state story. Uniform and
-        // honest on app-url bundles too — the caller minted the URL, its state is the caller's.
+        // Structured subject provenance: code pin + state story. Uniform, and
+        // stated on app-url bundles too: the caller minted the URL, its state is the caller's.
         // CuaSubjectProvenanceArg's two variants (clone, local-tree) are already RunSubjectProvenance-
         // shaped, so no reconstruction is needed beyond the app-url fallback.
         subject: args.subjectProvenance ?? { source: "app-url", state: { provenance: "undeclared" } },

package/dist/routes/computer-use/subject-projection.d.ts

@@ -1,5 +1,5 @@
-import type { ComputerUsePlan } from "../../lab/plan-types.js";
-import type { LabSubjectState } from "../../lab/types.js";
+import type { ComputerUsePlan } from "../../study/plan-types.js";
+import type { StudySubjectState } from "../../study/types.js";
 import { type RunSubjectProvenance, type RunSubjectStateStepRecord } from "../../run/bundle.js";
 import { type LocalTreeArchive } from "../../subject/local-tree-archive.js";
 import { type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ParticipantRunOutcome } from "./types.js";
@@ -18,13 +18,13 @@ export declare function projectParticipantSubjects(args: {
 }): CuaSubjectProjection[];
 /**
  * Resolve the bundle's state marker from the declaration and what actually ran.
- * Precedence: external declared → "unpinned" (seed records, if any, stay attached — a
+ * Precedence: external declared → "unpinned" (seed records, if any, stay attached; a
  * migrated external DB is still unpinned overall); else seed declared → "seeded" only when
  * every declared step executed ok on a live run, otherwise "declared-not-run" (dry-run
  * contract bundles and failed live provisioning); no declaration → "undeclared".
  */
 export declare function resolveSubjectState(args: {
-    declared: LabSubjectState | undefined;
+    declared: StudySubjectState | undefined;
     dryRun: boolean;
     executed: RunSubjectStateStepRecord[];
 }): RunSubjectProvenance["state"];

package/dist/routes/computer-use/subject-projection.js

@@ -36,7 +36,7 @@ export function projectParticipantSubjects(args) {
 }
 /**
  * Resolve the bundle's state marker from the declaration and what actually ran.
- * Precedence: external declared → "unpinned" (seed records, if any, stay attached — a
+ * Precedence: external declared → "unpinned" (seed records, if any, stay attached; a
  * migrated external DB is still unpinned overall); else seed declared → "seeded" only when
  * every declared step executed ok on a live run, otherwise "declared-not-run" (dry-run
  * contract bundles and failed live provisioning); no declaration → "undeclared".
@@ -48,8 +48,8 @@ export function resolveSubjectState(args) {
     }
     const declaredSeed = declared.seed ?? [];
     const external = declared.external ?? [];
-    // Dry-run: nothing executes (no sandbox) — record the DECLARED recipe: name, phase, and
-    // command digest only, with NO execution fields.
+    // Dry-run: nothing executes (no sandbox), so record the declared recipe: name, phase, and
+    // command digest only, with no execution fields.
     const seed = args.dryRun
         ? declaredSeed.map((step) => ({
             name: step.name,
@@ -74,8 +74,8 @@ export function resolveSubjectState(args) {
         ...(external.length > 0 ? { externalEnvNames: external } : {}),
     };
 }
-/** Build the per-participant subject projection (invariant 5). Local-tree participants all share
- *  ONE host-packed archive, so every participant's projection carries the identical archiveSha256/
+/** Build the per-participant subject projection. Local-tree participants all share
+ *  one host-packed archive, so every participant's projection carries the identical archiveSha256/
  *  commit/dirty (no divergence is possible, unlike the clone route's per-participant
  *  in-sandbox commit). */
 function participantSubjectProjection(args) {
@@ -144,7 +144,7 @@ export function aggregateCuaSubject(args) {
     const unanimous = !dryRun && commits.length === participantCount && new Set(commits).size === 1;
     const warnings = !dryRun && participantCount > 1 && new Set(commits).size > 1
         ? [
-            "Fan-out participants resolved DIVERGENT subject commits, so the top-level subject.commit is omitted; see each participant's provenance in result.lanes for its pinned commit.",
+            "Participants resolved different subject commits, so the top-level subject.commit is omitted; each participant's provenance in result.lanes has its pinned commit.",
         ]
         : [];
     return {