humanish 0.106.1 → 0.108.0

package/dist/lab/warnings.js

@@ -12,13 +12,14 @@ const scriptedRoute = (routes) => !promptRoute(routes) && routes.scripted;
 const otherRoute = (routes) => !promptRoute(routes) && !routes.scripted;
 /** Rows for each actor, reported as `actors[<index>].<field>`, in this order per actor. */
 const ACTOR_ROWS = [
-    // Shared-world ONLY fields on the roster: per-role `entry` is inert anywhere else (invariant 6).
+    // Shared-world-only fields on the roster: a participant's `entry` is inert anywhere else
+    // (claims match mechanism).
     {
         field: "lanes[].entry",
-        reason: "the per-role loopback entry is a shared-world capability; needs subject.topology: shared-world",
+        reason: "the per-participant loopback entry is a shared-world capability; needs subject.topology: shared-world",
         applies: (actor, routes) => Boolean(rosterOf(actor)?.some((entry) => entry.entry !== undefined)) && !routes.shared,
     },
-    // The host-seat marker acts ONLY on the external-public shared-world route; inert elsewhere.
+    // The host marker acts only on the external-public shared-world route; inert elsewhere.
     {
         field: "lanes[].host",
         reason: "the designated host-participant marker; needs the external-public shared-world route: app-url × topology shared-world × allowPublicTargets",
@@ -34,7 +35,7 @@ const ACTOR_ROWS = [
     },
     {
         field: "lanes",
-        reason: "fan-out is a computer-use route capability; terminal fan-out is a later slice",
+        reason: "only the computer-use route runs more than one participant",
         applies: (actor, routes) => routes.terminal && Boolean(rosterOf(actor)),
     },
     {
@@ -57,7 +58,7 @@ const ACTOR_ROWS = [
         reason: "the scripted-browser route fans out via actors[0].count, not an actors[0].lanes roster",
         applies: (actor, routes) => scriptedRoute(routes) && Boolean(rosterOf(actor)),
     },
-    // On every other route the prompt fields, persona and the lane roster are inert.
+    // On every other route the prompt fields, persona and the `lanes[]` roster are inert.
     { field: "mission", applies: (actor, routes) => otherRoute(routes) && Boolean(actor.mission) },
     {
         field: "laneFocus",
@@ -68,7 +69,7 @@ const ACTOR_ROWS = [
     { field: "lanes", applies: (actor, routes) => otherRoute(routes) && Boolean(rosterOf(actor)) },
 ];
 const TERMINAL_ONLY = "needs subject.source: terminal-product + a registered terminal actor";
-const RESERVED = "reserved for a later slice; not yet consumed";
+const RESERVED = "reserved; no route reads it yet";
 /** Rows for the rest of the config, reported after the actor rows, in this order. */
 const CONFIG_ROWS = [
     // The computer-use routes consume (clone) subject.{serve,env,state,clone.depth}, and so does the
@@ -89,8 +90,9 @@ const CONFIG_ROWS = [
         field: "subject.state",
         applies: (config, routes) => Boolean(config.subject.state) && !routes.cua && !routes.scripted,
     },
-    // topology + checkpoint act ONLY on the shared-world route (#164); a set-but-unconsumed value
-    // (incl. an explicit per-lane-worlds, which the cua route already is by mechanism) warns inert.
+    // topology + checkpoint act only on the shared-world route; a set-but-unconsumed value
+    // (incl. an explicit per-lane-worlds, which the computer-use route already is by mechanism) warns
+    // inert.
     {
         field: "subject.topology",
         reason: "drives behavior only on the shared-world route; needs subject.topology: shared-world + clone × e2b-desktop × a computer-use actor + a roster of ≥2 participants",
@@ -101,29 +103,29 @@ const CONFIG_ROWS = [
         reason: "the shared-world state-checkpoint probe; needs subject.topology: shared-world",
         applies: (config, routes) => config.subject.state?.checkpoint !== undefined && !routes.shared,
     },
-    // publicTarget (the external-public ownership attestation) acts ONLY on the external-public
+    // publicTarget (the external-public ownership attestation) acts only on the external-public
     // shared-world route; inert elsewhere. (It is already parse-rejected on non-app-url sources.)
     {
         field: "subject.publicTarget",
         reason: "the external-public ownership attestation; needs the external-public shared-world route: app-url × topology shared-world × allowPublicTargets",
         applies: (config, routes) => config.subject.publicTarget !== undefined && !routes.externalPublic,
     },
-    // exposure (the synthetic-subject attestation) acts ONLY on the shared-world route (the
+    // exposure (the synthetic-subject attestation) acts only on the shared-world route (the
     // getHost-exposed plane) and on scripted clones; inert elsewhere.
     {
         field: "subject.exposure",
-        reason: "the synthetic-subject attestation for a getHost-exposed plane; needs shared-world or clone × e2b-desktop × scripted-browser",
+        reason: "the statement that a subject served on a public sandbox URL holds only synthetic data; needs shared-world or clone × e2b-desktop × scripted-browser",
         applies: (config, routes) => config.subject.exposure !== undefined &&
             !routes.shared &&
             !(routes.scripted && config.subject.source === "clone"),
     },
-    // comms.email drives the in-sandbox email/SMS catch, which needs a subject sandbox HUMANISH
+    // comms.email drives the in-sandbox email/SMS catch, which needs a subject sandbox that humanish
     // provisions (clone or local-tree) so it holds a handle to host the catch. On an app-url /
     // operator-provided subject there is no such handle, so a declared comms block would silently
-    // collect nothing — a false green. Warn at parse time (fires on inspect + dry-run too).
+    // collect nothing, a false green. Warn at parse time (fires on inspect + dry-run too).
     {
         field: "comms.email",
-        reason: "the in-sandbox email/SMS catch needs a harness-provisioned subject to host it — subject.source: clone or local-tree; on an app-url or operator-provided subject humanish holds no sandbox handle. Declare `comms.email.external` to run the catch yourself: humanish then points the persona at your inbox, drains your catch, and writes the same evidence — see #328",
+        reason: "the email catch runs in a sandbox humanish provisions, which needs `subject.source: clone` or `local-tree`, and an app-url subject has none. To use email here, run the catch yourself with `humanish comms catch` and declare `comms.email.external`: humanish then points each persona at your inbox, reads your catch and records the same evidence",
         applies: (config) => config.comms?.email?.kind === "fake" &&
             config.comms.email.external === undefined &&
             config.subject.source !== "clone" &&
@@ -138,9 +140,9 @@ const CONFIG_ROWS = [
         applies: (config) => Boolean(config.comms?.email?.external) &&
             (config.subject.source === "clone" || config.subject.source === "local-tree"),
     },
-    // clone.keep IS consumed on the cua route (honored on FAILURE: the sandbox is left up to debug
-    // a failed install/boot; otherwise always killed). clone.fanout is REJECTED on the cua route
-    // (a hard parse error above), so it can never reach this warning list there.
+    // clone.keep is consumed on the computer-use route (honored on failure: the sandbox is left up to
+    // debug a failed install/boot; otherwise always killed). clone.fanout is rejected on the
+    // computer-use route (a hard parse error above), so it can never reach this warning list there.
     {
         field: "execution.timeoutMs",
         applies: (config, routes) => !routes.cua &&
@@ -152,23 +154,24 @@ const CONFIG_ROWS = [
         field: "execution.completionTimeoutMs",
         applies: (config) => config.execution?.completionTimeoutMs !== undefined,
     },
-    // execution.concurrency is CONSUMED on the cua route (it bounds in-flight fan-out lanes);
-    // inert (warned) everywhere else.
+    // execution.concurrency is consumed on the computer-use route (it bounds in-flight fan-out
+    // participants); inert (warned) everywhere else.
     {
         field: "execution.concurrency",
         applies: (config, routes) => config.execution?.concurrency !== undefined && !routes.cua,
     },
-    // execution.caps is CONSUMED on the cua route (maxUsd is the fail-closed spend abort); inert
-    // (warned) everywhere else so a misplaced budget field is never trusted to cap a route it cannot.
+    // execution.caps is consumed on the computer-use route (maxUsd is the fail-closed spend abort);
+    // inert (warned) everywhere else so a misplaced budget field is never trusted to cap a route it
+    // cannot.
     {
         field: "execution.caps",
-        reason: "the fail-closed spend abort is a computer-use route capability; needs a computer-use actor on e2b-desktop",
+        reason: "only the computer-use route enforces it, with a computer-use actor on e2b-desktop",
         applies: (config, routes) => Boolean(config.execution?.caps) && !routes.cua,
     },
     // terminal-product consumes subject.product, scenario.caps, execution.{terminal,runtimeAuth}:
     // dry-run records the contract; live execution enforces caps and command-scoped auth. On every
-    // OTHER route they are inert and must warn so a
-    // misplaced safety/budget field is never trusted to do something it cannot (invariant 6).
+    // other route they are inert and must warn so a
+    // misplaced safety/budget field is never trusted to do something it cannot.
     {
         field: "subject.product",
         reason: "needs subject.source: terminal-product or desktop-cli with the matching actor",
@@ -227,10 +230,10 @@ const CONFIG_ROWS = [
         field: "execution.desktop.sandboxTimeoutMs",
         applies: (config, routes) => !routes.cua && config.execution?.desktop?.sandboxTimeoutMs !== undefined,
     },
-    // execution.desktop.template (the custom E2B desktop image) is consumed ONLY where a desktop is
-    // actually created via Sandbox.create — the e2b-desktop computer-use routes (cua/shared-world/
-    // concurrent). It is INERT on every other route (incl. the in-process local-app cua route, which
-    // creates no desktop): warn so an unconsumed template is never silently ignored (invariant 6).
+    // execution.desktop.template (the custom E2B desktop image) is consumed only where a desktop is
+    // actually created via Sandbox.create: the e2b-desktop computer-use routes (cua/shared-world/
+    // concurrent). It is inert on every other route (incl. the in-process local-app computer-use
+    // route, which creates no desktop): warn so an unconsumed template is never silently ignored.
     {
         field: "execution.desktop.template",
         reason: "the custom E2B desktop image is consumed only on execution.target: e2b-desktop computer-use routes that create a desktop; needs a computer-use actor on e2b-desktop",
@@ -243,15 +246,15 @@ const CONFIG_ROWS = [
         reason: "no current route reads it",
         applies: (config) => config.execution?.desktop?.codexAppServer !== undefined,
     },
-    // scenario.ref is CONSUMED on the scripted-browser route (required there); forward-declared
+    // scenario.ref is consumed on the scripted-browser route (required there); forward-declared
     // everywhere else.
     {
         field: "scenario.ref",
         applies: (config, routes) => Boolean(config.scenario?.ref) && !routes.scripted,
     },
     { field: "scenario.inline", applies: (config) => Boolean(config.scenario?.inline) },
-    // review.{scoring,milestones,vocabulary} stay forward-declared (reserved for #319) on every route.
-    // review.scorer (#316) IS consumed (loaded + wired, or fail-closed at load) on every scorer-capable
+    // review.{scoring,milestones,vocabulary} stay forward-declared on every route.
+    // review.scorer is consumed (loaded + wired, or fail-closed at load) on every scorer-capable
     // route, so it does not warn there; on the scripted-browser route the actor carries no scorer seam,
     // so a declared scorer is flagged inert (the run also fails closed at load).
     {
@@ -296,9 +299,11 @@ function rowLabel(row, prefix = "") {
         ? `${prefix}${row.field}`
         : `${prefix}${row.field} (${row.reason})`;
 }
-// Report fields that are present but not yet consumed by the engine, so a user never trusts a
-// setting that silently does nothing. Keeps the schema forward-correct AND honest.
-export function forwardDeclaredWarnings(config) {
+/**
+ * The fields a config sets that its route does not read, each as `field` or `field (reason)`. A v2
+ * file gets them as one warning; a v3 study is refused for any of them.
+ */
+export function inertFieldLabels(config) {
     const routes = routesOf(config);
     const inert = [];
     for (const [index, actor] of config.actors.entries()) {
@@ -309,14 +314,38 @@ export function forwardDeclaredWarnings(config) {
     for (const row of CONFIG_ROWS)
         if (row.applies(config, routes))
             inert.push(rowLabel(row));
+    return inert;
+}
+/**
+ * The same fields as `inertFieldLabels`, as paths without their reasons, such as
+ * `actors[0].lanes[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
+ */
+export function inertFieldPaths(config) {
+    const routes = routesOf(config);
+    const paths = [];
+    for (const [index, actor] of config.actors.entries()) {
+        for (const row of ACTOR_ROWS)
+            if (row.applies(actor, routes))
+                paths.push(`actors[${index}].${row.field}`);
+    }
+    for (const row of CONFIG_ROWS)
+        if (row.applies(config, routes))
+            paths.push(row.field);
+    return paths;
+}
+// Report fields that are present but not yet consumed by the engine, so a user never trusts a
+// setting that silently does nothing.
+export function forwardDeclaredWarnings(config) {
+    const routes = routesOf(config);
+    const inert = inertFieldLabels(config);
     const warnings = inert.length === 0
         ? []
         : [
-            `Forward-declared fields are set but not yet consumed by the engine (planned for a later slice): ${inert.join(", ")}.`,
+            `These fields are set, but no route reads them yet, so they have no effect: ${inert.join(", ")}.`,
         ];
-    // A declared cap below the seat count is legal but loud: the roster promises N live actors and
-    // the cap delivers waves of M. Say so up front (inspect + dry-run + run) — a green run in waves
-    // is otherwise indistinguishable from the all-live run the author meant (#350).
+    // A declared cap below the participant count is legal but loud: the roster promises N live actors
+    // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
+    // waves is otherwise indistinguishable from the all-live run the author meant.
     {
         const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
         const cap = config.execution?.concurrency;
@@ -324,14 +353,14 @@ export function forwardDeclaredWarnings(config) {
             warnings.push(`execution.concurrency ${cap} caps a ${participantCount}-participant roster: participants run in waves of ${cap}, never all live at once. Remove execution.concurrency (the default runs all ${participantCount} participants simultaneously) or set it to ${participantCount}; declare a lower cap only to bound simultaneous paid desktops.`);
         }
     }
-    // Partial email coverage is legal but loud (#351): a lane without an addressed recipient never
-    // hears an inbox exists, so an email-gated flow on that seat dead-ends by construction.
+    // Partial email coverage is legal but loud: a participant without an addressed recipient never
+    // hears an inbox exists, so an email-gated flow on that participant dead-ends by construction.
     if (routes.cua && config.comms?.email?.recipients) {
         const participantIds = declaredParticipantIds(config);
         const covered = new Set(addressedRecipients(config.comms.email).map((recipient) => recipient.participantId));
         const uncovered = participantIds.filter((id) => !covered.has(id));
         if (covered.size > 0 && uncovered.length > 0 && participantIds.length > 1) {
-            warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants; the uncovered participant(s) get no inbox and are never told one exists: ${uncovered.join(", ")}. Add addressed recipients for them if their flows need email.`);
+            warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants. These get no inbox and are never told one exists: ${uncovered.join(", ")}. Add a recipient with an address for each one whose flow needs email.`);
         }
     }
     return warnings;

package/dist/library-aliases.d.ts

@@ -0,0 +1,56 @@
+import { CuaAdmissionLimitError as AdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+import type { CuaAction as Action, CuaExecutor as Executor, CuaLoopOptions as LoopOptions, CuaLoopResult as LoopResult, CuaObservation as Observation, CuaProvider as Provider, CuaSafetyCheck as SafetyCheck, CuaTurn as Turn, CuaTurnRequest as TurnRequest } from "./actors/computer-use/loop.js";
+import type { BrowserLabScoringContext as BrowserScoringContext } from "./lab/adapter-extension.js";
+import { parseLabConfig as parseStudy } from "./lab/config.js";
+import type { LabRoute as StudyRoute } from "./lab/routing.js";
+import type { LabEvent as StudyEvent } from "./lab/run-lab-events.js";
+import { type LabConfig as StudyConfig } from "./lab/types.js";
+import { runPackageLab as runStudy, type LabOutcome as StudyOutcome, type LabResult as StudyResult, type RunLabOptions as RunStudyOptions } from "./run-lab.js";
+/** @deprecated Use `runStudy`, the same function. 0.109 removes `runLab`. */
+export declare const runLab: typeof runStudy;
+/** @deprecated Use `parseStudy`, the same function. 0.109 removes `parseLabConfig`. */
+export declare const parseLabConfig: typeof parseStudy;
+/**
+ * The `humanish.lab.v2` schema id, which 0.109 stops parsing.
+ * @deprecated Write `STUDY_SCHEMA` (`humanish.study.v3`) files. 0.109 removes `LAB_CONFIG_SCHEMA`.
+ */
+export declare const LAB_CONFIG_SCHEMA = "humanish.lab.v2";
+/** @deprecated Use `StudyConfig`, the same type. 0.109 removes `LabConfig`. */
+export type LabConfig = StudyConfig;
+/** @deprecated Use `StudyEvent`, the same type. 0.109 removes `LabEvent`. */
+export type LabEvent = StudyEvent;
+/** @deprecated Use `StudyOutcome`, the same type. 0.109 removes `LabOutcome`. */
+export type LabOutcome = StudyOutcome;
+/** @deprecated Use `StudyResult`, the same type. 0.109 removes `LabResult`. */
+export type LabResult<R extends StudyRoute = StudyRoute> = StudyResult<R>;
+/** @deprecated Use `StudyRoute`, the same type. 0.109 removes `LabRoute`. */
+export type LabRoute = StudyRoute;
+/** @deprecated Use `RunStudyOptions`, the same type. 0.109 removes `RunLabOptions`. */
+export type RunLabOptions = RunStudyOptions;
+/** @deprecated Use `BrowserScoringContext`, the same type. 0.109 removes `BrowserLabScoringContext`. */
+export type BrowserLabScoringContext = BrowserScoringContext;
+/**
+ * @deprecated Use `ComputerUseAdmissionLimitError`, the same class, so `instanceof` matches either
+ * name. 0.109 removes `CuaAdmissionLimitError`.
+ */
+export declare const CuaAdmissionLimitError: typeof AdmissionLimitError;
+/** @deprecated Use `ComputerUseAdmissionLimitError`. 0.109 removes `CuaAdmissionLimitError`. */
+export type CuaAdmissionLimitError = AdmissionLimitError;
+/** @deprecated Use `ComputerUseAction`, the same type. 0.109 removes `CuaAction`. */
+export type CuaAction = Action;
+/** @deprecated Use `ComputerUseExecutor`, the same type. 0.109 removes `CuaExecutor`. */
+export type CuaExecutor = Executor;
+/** @deprecated Use `ComputerUseLoopOptions`, the same type. 0.109 removes `CuaLoopOptions`. */
+export type CuaLoopOptions = LoopOptions;
+/** @deprecated Use `ComputerUseLoopResult`, the same type. 0.109 removes `CuaLoopResult`. */
+export type CuaLoopResult = LoopResult;
+/** @deprecated Use `ComputerUseObservation`, the same type. 0.109 removes `CuaObservation`. */
+export type CuaObservation = Observation;
+/** @deprecated Use `ComputerUseProvider`, the same type. 0.109 removes `CuaProvider`. */
+export type CuaProvider = Provider;
+/** @deprecated Use `ComputerUseSafetyCheck`, the same type. 0.109 removes `CuaSafetyCheck`. */
+export type CuaSafetyCheck = SafetyCheck;
+/** @deprecated Use `ComputerUseTurn`, the same type. 0.109 removes `CuaTurn`. */
+export type CuaTurn = Turn;
+/** @deprecated Use `ComputerUseTurnRequest`, the same type. 0.109 removes `CuaTurnRequest`. */
+export type CuaTurnRequest = TurnRequest;

package/dist/library-aliases.js

@@ -0,0 +1,22 @@
+// The names 0.107's library exported for running a lab and driving a computer-use participant.
+// Each is the same function, constant, class or type as the name that replaces it, so an existing
+// import, call or `instanceof` check keeps working, and editors mark it deprecated.
+// Removed in 0.109.0: this module and its exports in src/index.ts.
+import { CuaAdmissionLimitError as AdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+import { parseLabConfig as parseStudy } from "./lab/config.js";
+import { LAB_CONFIG_SCHEMA as V2_SCHEMA } from "./lab/types.js";
+import { runPackageLab as runStudy, } from "./run-lab.js";
+/** @deprecated Use `runStudy`, the same function. 0.109 removes `runLab`. */
+export const runLab = runStudy;
+/** @deprecated Use `parseStudy`, the same function. 0.109 removes `parseLabConfig`. */
+export const parseLabConfig = parseStudy;
+/**
+ * The `humanish.lab.v2` schema id, which 0.109 stops parsing.
+ * @deprecated Write `STUDY_SCHEMA` (`humanish.study.v3`) files. 0.109 removes `LAB_CONFIG_SCHEMA`.
+ */
+export const LAB_CONFIG_SCHEMA = V2_SCHEMA;
+/**
+ * @deprecated Use `ComputerUseAdmissionLimitError`, the same class, so `instanceof` matches either
+ * name. 0.109 removes `CuaAdmissionLimitError`.
+ */
+export const CuaAdmissionLimitError = AdmissionLimitError;

package/dist/observer/artifact.d.ts

@@ -1,9 +1,9 @@
 import type { LoadedAnalysis } from "../analysis/types.js";
 import { type ObserverData } from "./data.js";
 /**
- * Resolve — and in a repo checkout, build — the Observer artifact BEFORE any run or
+ * Resolve (and in a repo checkout, build) the Observer artifact before any run or
  * lab work starts. A missing artifact must cost seconds at startup, never a completed
- * session (a live lane spends real money before the render step would have noticed).
+ * session (a live participant spends real money before the render step would have noticed).
  * Unconditional on purpose: the artifact is the only renderer now, so the fail-before-
  * spend property this preflight bought under the flag matters more, not less.
  */

package/dist/observer/artifact.js

@@ -5,15 +5,15 @@ import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { projectShareCheckedAnalysis, studyAnalysisSharingProblems } from "../analysis/sharing.js";
+import { projectShareCheckedAnalysis, analysisSharingProblems } from "../analysis/sharing.js";
 import { withObserverEndings } from "./data.js";
 const OBSERVER_DATA_PLACEHOLDER = "__HUMANISH_OBSERVER_DATA__";
 const OBSERVER_DATA_SLOT = `<script id="observer-data" type="application/json">${OBSERVER_DATA_PLACEHOLDER}</script>`;
 let cachedObserverArtifact = null;
 /**
- * Resolve — and in a repo checkout, build — the Observer artifact BEFORE any run or
+ * Resolve (and in a repo checkout, build) the Observer artifact before any run or
  * lab work starts. A missing artifact must cost seconds at startup, never a completed
- * session (a live lane spends real money before the render step would have noticed).
+ * session (a live participant spends real money before the render step would have noticed).
  * Unconditional on purpose: the artifact is the only renderer now, so the fail-before-
  * spend property this preflight bought under the flag matters more, not less.
  */
@@ -42,7 +42,7 @@ function loadObserverArtifact() {
             // together) must not race one `vite build` output: a reader can catch the
             // artifact half-written. A mkdir lock serializes builders across processes;
             // whoever loses the race re-checks staleness and usually just reads.
-            // The lock lives OUTSIDE dist/ (vite empties dist mid-build) and inside an
+            // The lock lives outside dist/ (vite empties dist mid-build) and inside an
             // ignored path so a crashed builder cannot dirty the tree.
             const lockDir = path.join(workspaceDir, "node_modules", ".observer-build-lock");
             mkdirSync(path.dirname(lockDir), { recursive: true });
@@ -50,7 +50,7 @@ function loadObserverArtifact() {
             for (;;) {
                 try {
                     mkdirSync(lockDir);
-                    break; // lock acquired — this process builds
+                    break; // lock acquired: this process builds
                 }
                 catch {
                     if (Date.now() > deadline)
@@ -71,7 +71,7 @@ function loadObserverArtifact() {
                     try {
                         // NODE_ENV is forced: Vite respects a preset NODE_ENV (test, development),
                         // and a dev-flavored artifact embeds jsxDEV plus the builder's absolute
-                        // filesystem paths — which the run's public-safety scan then rightly rejects.
+                        // filesystem paths, which the run's public-safety scan then rightly rejects.
                         execSync("pnpm --filter humanish-observer build", {
                             cwd: repoRoot,
                             stdio: ["ignore", "pipe", "inherit"],
@@ -79,7 +79,7 @@ function loadObserverArtifact() {
                         });
                     }
                     catch {
-                        throw new Error("observer workspace build failed — run `pnpm --filter humanish-observer build` for the full output.");
+                        throw new Error("observer workspace build failed; run `pnpm --filter humanish-observer build` to see the full output.");
                     }
                 }
             }
@@ -169,7 +169,7 @@ function renderObserverAppHtml(data, snapshot, analysis, assets) {
         .replace(OBSERVER_DATA_SLOT, () => `<script id="observer-data" type="application/json">${escapeJsonScript(data)}</script>`)
         .replace(/<script id="study-analysis" type="application\/json">[\s\S]*?<\/script>/, () => `<script id="study-analysis" type="application/json">${escapeJsonScript(analysis)}</script>`)
         .replace("</body>", () => `${renderExportAssets(assets)}</body>`)
-        .replace(/<title>[^<]*<\/title>/, () => `<title>humanish Observer — ${escapeHtml(data.run.runId)}</title>`);
+        .replace(/<title>[^<]*<\/title>/, () => `<title>humanish Observer · ${escapeHtml(data.run.runId)}</title>`);
 }
 /** Render current packaged UI around a validated/projected Observer snapshot. */
 export function renderObserverHtml(data, options = {}) {
@@ -192,7 +192,7 @@ export function renderObserverHtml(data, options = {}) {
             },
         };
     }
-    const sharing = studyAnalysisSharingProblems(analysis);
+    const sharing = analysisSharingProblems(analysis);
     if (data.publicSafety && (sharing.sensitive || sharing.unverified)) {
         const share = data.publicSafety.share;
         data = {

package/dist/observer/data.d.ts

@@ -31,18 +31,18 @@ export interface ObserverData {
         lifecycle: RunBundle["lifecycle"];
         knownGaps: string[];
         /**
-         * What happened to the PARTICIPANTS, with the denominator attached. `status` above collapses the
+         * What happened to the participants, with the denominator attached. `status` above collapses the
          * run to one word for a gate; this is the study result, and it is what the person watching
          * through the glass actually wants to know. Absent on a bundle with no participants.
          *
-         * A viewing room that shows only vivid moments manufactures certainty from n=1 — so the count
+         * A viewing room that shows only vivid moments manufactures certainty from n=1, so the count
          * travels with the outcome here, always (docs/principles/three-roles.md).
          */
         participants?: RunBundle["review"]["participants"];
         /** The same thing as one readable line, so a renderer cannot accidentally show a number
          *  without its denominator. */
         participantsLine?: string;
-        /** The study's per-task completion rates (#414), when the lab declared a protocol. */
+        /** The study's per-task completion rates, when the lab declared a protocol. */
         tasks?: RunBundle["review"]["tasks"];
         /** Pre-formatted like participantsLine, denominator on every number. */
         tasksLine?: string;
@@ -56,8 +56,8 @@ export interface ObserverData {
     };
     laneGroups: ObserverLaneGroup[];
     /**
-     * OPTIONAL run-level cost ESTIMATE projected straight through from the bundle
-     * (humanish.run-cost-summary.v1). Absent when the bundle carries none. The Observer LABELS every
+     * Optional run-level cost estimate projected straight through from the bundle
+     * (humanish.run-cost-summary.v1). Absent when the bundle carries none. The Observer labels every
      * figure as estimated (rates as of <asOf>) and never presents it as an authoritative charge.
      */
     cost?: RunCostSummary;
@@ -68,7 +68,7 @@ export interface ObserverData {
         publishable: false;
         note: string;
         /**
-         * ADDITIVE + OPTIONAL (#584): the result of verification at static render or
+         * Additive + optional: the result of verification at static render or
          * export time. Unverified projections omit this field. The timestamp records
          * that check; it is not an assertion about subsequent file changes.
          */

package/dist/observer/data.js

@@ -1,6 +1,6 @@
 import { actorEnding } from "../actors/stop-cause.js";
 import { isCommsReceivingEvidence, receivingAnalysisContext } from "../comms/receiving-evidence.js";
-import { formatParticipantOutcomes, formatStudyTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
+import { formatParticipantOutcomes, formatRunTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
 import { cuaGoalSource, CUA_COMPLETION_NOTE } from "../actors/goal-source.js";
 export const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
 /** Discard a forged or stale runtime grant before projecting persisted evidence. */
@@ -33,7 +33,7 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
         const sim = bundle.simulations.find((candidate) => candidate.id === stream.simId) ??
             fallbackSimulation(bundle, stream);
         // A natural session can finish its protocol while the participant explicitly reports a
-        // blocker (#690). Match the review's typed-outcome rule without rewriting the raw trace or
+        // blocker. Match the review's typed-outcome rule without rewriting the raw trace or
         // guessing from prose. Never turn an active or failed harness into a participant outcome.
         const status = (stream.status === "passed" || stream.status === "complete") &&
             stream.actor?.completionReason === "goal_satisfied" &&
@@ -47,7 +47,7 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
             status,
             sim,
             kindLabel: kindLabel(stream.kind),
-            statusLabel: statusLabel(status),
+            statusLabel: statusLabel(status, bundle.mode),
             terminalPlain: stripAnsi(stream.terminal?.tail ?? ""),
             timeline: [
                 ...events.filter((event) => event.simId === sim.id || event.streamId === stream.id),
@@ -95,7 +95,7 @@ export function buildObserverData(bundle, generatedAt = new Date().toISOString()
                 ? {}
                 : {
                     tasks: bundle.review.tasks,
-                    tasksLine: formatStudyTaskFunnel(bundle.review.tasks),
+                    tasksLine: formatRunTaskFunnel(bundle.review.tasks),
                 }),
         },
         summary: {
@@ -229,10 +229,11 @@ function kindLabel(kind) {
             return "Summary";
     }
 }
-function statusLabel(status) {
+/** `contract_proof_only` reads "Dry run" on a dry run; a live participant with it has no result. */
+function statusLabel(status, mode) {
     switch (status) {
         case "contract_proof_only":
-            return "Contract proof";
+            return mode === "dry-run" ? "Dry run" : "No verdict";
         case "preparing":
             return "Preparing";
         case "queued":

package/dist/observer/exposure.d.ts

@@ -47,7 +47,7 @@ export type ExposureValidation = {
     };
 };
 /** Why `watch` refuses `--safe`, on every watch path. */
-export declare const WATCH_SAFE_NOT_APPLICABLE_MESSAGE = "watch streams a single live run that is never share_ready; --safe (a share_ready library filter) applies to `serve`, not `watch`. Restrict viewers with edge auth: --allow-email / --allow-domain.";
+export declare const WATCH_SAFE_NOT_APPLICABLE_MESSAGE = "watch streams a single live run that is never share_ready, so --safe (a share_ready library filter for `observe --all`) cannot apply. Restrict viewers with edge auth: --allow-email / --allow-domain.";
 export declare function validateExposure(surface: ExposureSurface, request: ExposureRequest, live?: WatchLiveContext): ExposureValidation;
 export interface ExposableServer {
     readonly port: number;

package/dist/observer/exposure.js

@@ -1,15 +1,15 @@
-// Shared fail-closed exposure validation + tunnel orchestration for BOTH `serve` (a library of
-// finished runs) and `watch` (one live run). Exposure auth is TUNNEL-EDGE only: humanish carries no
+// Shared fail-closed exposure validation + tunnel orchestration for both `serve` (a library of
+// finished runs) and `watch` (one live run). Exposure auth is tunnel-edge only: humanish carries no
 // in-process auth. Exposure is admitted only behind edge auth (ngrok --oauth google, or an operator
-// --public-url they secure) OR, for serve, behind --safe (share_ready runs only). A live watch run
-// is never share_ready (raw, unverified screenshots), so watch --expose ALWAYS requires edge auth.
+// --public-url they secure) or, for serve, behind --safe (share_ready runs only). A live watch run
+// is never share_ready (raw, unverified screenshots), so watch --expose always requires edge auth.
 //
 // This module is pure with respect to the fail-closed matrix (validateExposure) and thin over the
 // tunnel launcher (startExposedObserver), so the CLI just maps flags in and results out.
 import { parsePublicOrigin } from "./http.js";
 import { startNgrokTunnel } from "./tunnel.js";
 /** Why `watch` refuses `--safe`, on every watch path. */
-export const WATCH_SAFE_NOT_APPLICABLE_MESSAGE = "watch streams a single live run that is never share_ready; --safe (a share_ready library filter) applies to `serve`, not `watch`. Restrict viewers with edge auth: --allow-email / --allow-domain.";
+export const WATCH_SAFE_NOT_APPLICABLE_MESSAGE = "watch streams a single live run that is never share_ready, so --safe (a share_ready library filter for `observe --all`) cannot apply. Restrict viewers with edge auth: --allow-email / --allow-domain.";
 function code(surface, suffix) {
     return `HUMANISH_${surface.toUpperCase()}_${suffix}`;
 }
@@ -70,12 +70,12 @@ export function validateExposure(surface, request, live) {
     const warnings = [];
     if (surface === "watch") {
         // A live, in-progress run is never share_ready (raw screenshots, unverified), so --safe would
-        // admit nothing and expose nothing: watch --expose ALWAYS requires edge auth, and the live-follow
+        // admit nothing and expose nothing: watch --expose always requires edge auth, and the live-follow
         // preconditions are checked first so `--dry-run`/`--detach`/`--json` fail with the clearer reason.
         if (live && (live.dryRun || live.detach || live.json)) {
             return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel; it cannot combine with --dry-run, --detach, or --json.");
         }
-        // --safe is a share_ready LIBRARY filter for `serve`; watch streams a single live run that is
+        // --safe is a share_ready library filter for `serve`; watch streams a single live run that is
         // never share_ready, so --safe would silently do nothing here. Reject it rather than ignore it.
         if (request.safe) {
             return fail("SAFE_NOT_APPLICABLE", WATCH_SAFE_NOT_APPLICABLE_MESSAGE);
@@ -85,18 +85,18 @@ export function validateExposure(surface, request, live) {
         }
     }
     else {
-        // serve: --expose must ALWAYS resolve to a reachable public origin (a tunnel or a --public-url),
+        // serve: --expose must always resolve to a reachable public origin (a tunnel or a --public-url),
         // even under --safe. Without one the exposed server is an unreachable loopback no-op, so fail
-        // closed before the origin-less bind. When an origin IS present, keep the edge-auth-OR-safe gate.
+        // closed before the origin-less bind. When an origin is present, keep the edge-auth-or-safe gate.
         if (!request.tunnel && !publicOrigin) {
             return fail("EXPOSE_REQUIRES_ORIGIN", "--expose needs a declared public origin: pass --tunnel ngrok or --public-url <origin>.");
         }
         if (!edgeAuthed && !request.safe) {
-            return fail("EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE", "--expose opens a public URL to local run bundles; require edge auth (--oauth google with --tunnel, or a --public-url you secure) OR --safe (share_ready runs only).");
+            return fail("EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE", "--expose opens a public URL to local run bundles, so it needs edge auth (--oauth google with --tunnel, or a --public-url you secure) or --safe (share_ready runs only).");
         }
     }
     if (request.oauth && request.allowEmails.length === 0 && request.allowDomains.length === 0) {
-        warnings.push("ngrok --oauth google with NO --allow-email/--allow-domain lets ANY Google account that reaches the URL in; add at least one allow rule to restrict who can watch.");
+        warnings.push("ngrok --oauth google without --allow-email or --allow-domain lets in any Google account that reaches the URL. Add at least one allow rule to choose who can watch.");
     }
     const mode = edgeAuthed ? "exposed" : "share-safe-open";
     return {

package/dist/observer/http.js

@@ -1,4 +1,4 @@
-// Shared HTTP hardening primitives for the serve surfaces. Extracted here so BOTH the live
+// Shared HTTP hardening primitives for the serve surfaces. Extracted here so both the live
 // Observer server (src/observer/render.ts) and the run-library server
 // (src/observer/serve.ts) can enforce the identical Host allowlist + security-header posture
 // without a module cycle. This file imports nothing from the serve modules.

package/dist/observer/library.d.ts

@@ -9,7 +9,7 @@ export interface LibraryHistory {
         /** Current contained status-record observation, separate from the evidence verdict. */
         runtimeState?: "running" | "finished" | "interrupted" | "unknown";
         streamCount: number;
-        /** Labeled run-total cost ESTIMATE (null when the run carries no cost summary). */
+        /** Labeled run-total cost estimate (null when the run carries no cost summary). */
         estimatedCostUsd: number | null;
         costRatesAsOf: string | null;
         costPlaceholder: boolean;

package/dist/observer/library.js

@@ -7,8 +7,8 @@ const STATUS_TONES = {
 };
 export function renderLibraryHtml(history, opts) {
     const emptyState = opts.safe
-        ? "No share_ready runs yet — run `humanish verify` to see why."
-        : "No runs yet — run `humanish watch` to create one.";
+        ? "No share_ready runs yet. Run `humanish verify` to see why."
+        : "No runs yet. Run `humanish watch` to create one.";
     return `<!doctype html>
 <html lang="en" data-theme="dark">
 <head>
@@ -39,6 +39,7 @@ function modeLabel(opts) {
     const auth = opts.mode === "exposed" ? "edge-authed" : opts.mode === "share-safe-open" ? "open" : "loopback";
     return opts.safe ? `${auth} · share_ready only` : auth;
 }
+// prose-check: script (the library page's CSS)
 function libraryCss() {
     return `
 :root { color-scheme: dark; }
@@ -80,6 +81,7 @@ main { padding: 1rem 1.1rem 3rem; max-width: 44rem; margin: 0 auto; }
 .empty { color: #9aa3b2; font-size: 0.85rem; padding: 2rem 0; text-align: center; }
 `;
 }
+// prose-check: script (the library page's JavaScript)
 function libraryClientJs() {
     const tones = JSON.stringify(STATUS_TONES);
     return `