humanish 0.107.0 → 0.109.0

package/dist/guest/runtime.js

@@ -1,6 +1,6 @@
 import { attachBrowserControlDispatcher } from "../browser-control/dispatcher.js";
 import { encodeGuestBootstrap, GuestBootstrapReader, GUEST_BOOTSTRAP_LIMITS, guestReadyTimeoutMs, } from "./bootstrap.js";
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 /** One admitted desktop and one dispatcher. The owner retains physical teardown. */
 export async function runGuestRuntime(options) {
     const owner = new AbortController();
@@ -77,7 +77,7 @@ export async function runGuestRuntime(options) {
         reader = new GuestBootstrapReader(options.transport, options.revision, authority, false, terminal);
         const identity = await reader.identity;
         if (authority.aborted)
-            throw new CuaExecutorError("session_revoked", "not_dispatched");
+            throw new ComputerUseExecutorError("session_revoked", "not_dispatched");
         clearTimeout(timer);
         timer = setTimeout(() => {
             void close();
@@ -87,7 +87,7 @@ export async function runGuestRuntime(options) {
         desktop = await Promise.race([
             preparing,
             new Promise((_, reject) => {
-                const stop = () => reject(new CuaExecutorError("session_revoked", "not_dispatched"));
+                const stop = () => reject(new ComputerUseExecutorError("session_revoked", "not_dispatched"));
                 authority.addEventListener("abort", stop, { once: true });
                 void preparing.finally(() => authority.removeEventListener("abort", stop)).catch(() => { });
                 if (authority.aborted)
@@ -95,7 +95,7 @@ export async function runGuestRuntime(options) {
             }),
         ]);
         if (authority.aborted)
-            throw new CuaExecutorError("session_revoked", "not_dispatched");
+            throw new ComputerUseExecutorError("session_revoked", "not_dispatched");
         reader.handoff();
         dispatcher = attachBrowserControlDispatcher({
             transport: options.transport,
@@ -105,14 +105,14 @@ export async function runGuestRuntime(options) {
             isAuthorized: () => !authority.aborted,
             ...(desktop.finishRecording ? { finishRecording: desktop.finishRecording } : {}),
         });
-        // No await in this handoff: an immediate HELLO already has its sole receiver.
+        // No await in this handoff: an immediate hello already has its sole receiver.
         options.transport.write(encodeGuestBootstrap(identity, true), (error) => {
             if (error)
                 terminal();
         });
         options.transport.resume();
         if (authority.aborted || options.transport.destroyed)
-            throw new CuaExecutorError("session_revoked", "not_dispatched");
+            throw new ComputerUseExecutorError("session_revoked", "not_dispatched");
         options.marker("R");
         clearTimeout(timer);
         return { close, closed };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-export { runPackageLab as runLab } from "./run-lab.js";
-export type { LabOutcome, LabResult, RunLabOptions } from "./run-lab.js";
-export type { LabEvent } from "./lab/run-lab-events.js";
-export type { ProviderContext } from "./lab/run-lab-homes.js";
-export { routeOf } from "./lab/plan.js";
-export type { LabRoute } from "./lab/plan.js";
-export { parseLabConfig } from "./lab/config.js";
-export { LAB_CONFIG_SCHEMA } from "./lab/types.js";
-export type { LabConfig } from "./lab/types.js";
+export { runStudy } from "./run-study.js";
+export type { StudyOutcome, StudyResult, RunStudyOptions } from "./run-study.js";
+export type { StudyEvent } from "./study/run-study-events.js";
+export type { ProviderContext } from "./study/run-study-homes.js";
+export { routeOf } from "./study/plan.js";
+export type { StudyRoute } from "./study/plan.js";
+export { parseStudy } from "./study/config.js";
+export { STUDY_SCHEMA } from "./study/types.js";
+export type { StudyConfig } from "./study/types.js";
 export { verifyRun } from "./verify/verify.js";
 export type { VerifyResult } from "./verify/verify.js";
 export { renderObserver } from "./observer/render.js";
@@ -14,16 +14,16 @@ export type { ObserverResult } from "./observer/render.js";
 export type { RunBundle, RunFeedbackCandidate } from "./run/bundle.js";
 export type { ActorTrace } from "./actors/contract.js";
 export { runComputerUseLoop, stableProgressKey } from "./actors/computer-use/loop.js";
-export type { CuaAction, CuaExecutor, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaTurn, CuaTurnRequest, } from "./actors/computer-use/loop.js";
+export type { CuaAction as ComputerUseAction, CuaExecutor as ComputerUseExecutor, CuaLoopOptions as ComputerUseLoopOptions, CuaLoopResult as ComputerUseLoopResult, CuaObservation as ComputerUseObservation, CuaProvider as ComputerUseProvider, CuaSafetyCheck as ComputerUseSafetyCheck, CuaTurn as ComputerUseTurn, CuaTurnRequest as ComputerUseTurnRequest, } from "./actors/computer-use/loop.js";
 export type { ActorCapabilities } from "./actors/contract.js";
 export { createOpenAiResponsesProvider } from "./actors/computer-use/openai-provider.js";
 export type { OpenAiResponsesProviderOptions } from "./actors/computer-use/openai-provider.js";
-export { CuaAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+export { ComputerUseAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
 export { defaultRedactionHooks } from "./evidence/redaction.js";
 export type { RedactionHooks } from "./evidence/redaction.js";
 export type { E2BDesktopSandbox } from "./substrates/e2b/sdk.js";
-export { browserScorer, terminalScorer } from "./lab/adapter-scorer-loader.js";
-export type { AdapterScorerModule, AdapterScoringContext } from "./lab/adapter-scorer-loader.js";
-export type { BrowserLabScoringContext } from "./lab/adapter-extension.js";
+export { browserScorer, terminalScorer } from "./study/adapter-scorer-loader.js";
+export type { AdapterScorerModule, AdapterScoringContext } from "./study/adapter-scorer-loader.js";
+export type { BrowserScoringContext } from "./study/adapter-extension.js";
 export type { TerminalProductScoringContext } from "./routes/terminal/types.js";
 export type { RunAdapterArtifact, RunAdapterScore } from "./run/bundle.js";

package/dist/index.js

@@ -1,18 +1,18 @@
-// The library surface: what an adopter needs to run a lab, read a run, bring a participant or
+// The library surface: what an adopter needs to run a study, read a run, bring a participant or
 // score a run. Everything else is internal and reached through the `humanish` bin. See
 // docs/contracts/schemas.md, "Library options", and the site's library page.
-// Run a lab.
-export { runPackageLab as runLab } from "./run-lab.js";
-export { routeOf } from "./lab/plan.js";
-export { parseLabConfig } from "./lab/config.js";
-export { LAB_CONFIG_SCHEMA } from "./lab/types.js";
+// Run a study.
+export { runStudy } from "./run-study.js";
+export { routeOf } from "./study/plan.js";
+export { parseStudy } from "./study/config.js";
+export { STUDY_SCHEMA } from "./study/types.js";
 // Read a run.
 export { verifyRun } from "./verify/verify.js";
 export { renderObserver } from "./observer/render.js";
 // Bring a participant.
 export { runComputerUseLoop, stableProgressKey } from "./actors/computer-use/loop.js";
 export { createOpenAiResponsesProvider } from "./actors/computer-use/openai-provider.js";
-export { CuaAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
+export { ComputerUseAdmissionLimitError } from "./actors/computer-use/admission-limit.js";
 export { defaultRedactionHooks } from "./evidence/redaction.js";
 // Score a run.
-export { browserScorer, terminalScorer } from "./lab/adapter-scorer-loader.js";
+export { browserScorer, terminalScorer } from "./study/adapter-scorer-loader.js";

package/dist/keys/key-resolution.d.ts

@@ -1,6 +1,6 @@
 export interface ResolvedKeyFill {
     name: string;
-    /** Human-readable source label (a path or command name) — never a value. */
+    /** Human-readable source label (a path or command name), never a value. */
     source: string;
 }
 export interface KeyResolutionDeps {
@@ -29,8 +29,8 @@ export interface KeySourceProbe {
     /** The command/path that would fill it when missing. */
     hint: string;
 }
-/** The nearest fill instruction for a missing key — used by doctor rows and appended to
- *  *_KEYS_MISSING errors so the failure names the fix, not just the absence (#436). */
+/** The nearest fill instruction for a missing key. Doctor rows use it, and it is appended to
+ *  *_KEYS_MISSING errors so the failure names the fix. */
 export declare function missingKeyHint(name: string): string;
 /** One shared suffix for *_KEYS_MISSING messages: where discovery looked, and what fills each
  *  missing key. Pure text; never values. */
@@ -47,10 +47,10 @@ export declare function probeKeySources(names: readonly string[], args: {
 /** Resolve a `humanish keys set` target: a vendor alias or a raw env name. Null = invalid. */
 export declare function resolveKeyName(vendorOrName: string): string | null;
 /** Write one key into the user store (0700 dir, 0600 file). Only allowlisted provider names
- *  are storable (the store feeds implicit discovery — an arbitrary-name store would be an env
+ *  are storable (the store feeds implicit discovery, so an arbitrary-name store would be an env
  *  injection vector with extra steps). The value must be a single non-empty line that
  *  round-trips the store's own parser byte-identically, and the write refuses symlinks at the
- *  file and its parent directory (red-team findings). */
+ *  file and its parent directory. */
 export declare function setUserKey(name: string, value: string, env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): {
     path: string;
 };

package/dist/keys/key-resolution.js

@@ -1,21 +1,21 @@
-// Provider-key discovery (#436): resolve the keys a live run needs through each vendor's
+// Provider-key discovery: resolve the keys a live run needs through each vendor's
 // native chain instead of demanding a per-repo --env-file that operators hand-copy keys into.
 //
-// The chain, per key, FILL-ONLY (a rung never overrides anything already present):
-//   1. process env — including whatever --env-file just loaded (explicit always wins);
-//   2. `.humanish/local/provider.env` — the project-local overlay this CLI's own --help
+// The chain, per key, fill-only (a rung never overrides anything already present):
+//   1. process env, including whatever --env-file just loaded (explicit always wins);
+//   2. `.humanish/local/provider.env`, the project-local overlay this CLI's own --help
 //      examples document;
 //   3. the owning vendor's native store, where one exists:
 //        E2B_API_KEY  <- ~/.e2b/config.json (written by `e2b auth login`);
 //        GH_TOKEN     <- `gh auth token` (the gh CLI's credential chain);
 //   4. the humanish user-level store `$XDG_CONFIG_HOME/humanish/keys.env`, written only by
-//      `humanish keys set` (0600, prompted or --stdin) — the fallback for vendors that ship
+//      `humanish keys set` (0600, prompted or --stdin), the fallback for vendors that ship
 //      no machine chain of their own (OpenAI, Anthropic).
 //
 // Every fill is announced by key name + source, never by value. The subject app's own
 // `.env`/`.env.local` are never read: those hold product credentials, a different class
-// (#11); this module only reads humanish-owned files and vendor-owned stores.
-// `HUMANISH_STRICT_KEYS=1` disables every rung below process env (the pre-#436 behavior).
+// of secret; this module only reads humanish-owned files and vendor-owned stores.
+// `HUMANISH_STRICT_KEYS=1` disables every rung below process env.
 import { spawn } from "node:child_process";
 import { chmodSync, closeSync, constants as fsConstants, existsSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, writeSync, } from "node:fs";
 import { homedir } from "node:os";
@@ -24,7 +24,7 @@ import { loadEnvFile } from "./env-file.js";
 /** The only names implicit discovery may fill (and `humanish keys set` may store). Everything
  *  else in an overlay/store file is ignored-and-named: a repo-planted NODE_OPTIONS/LD_PRELOAD
  *  must never enter process env off a file the operator did not explicitly pass (an explicit
- *  --env-file remains the operator's own full-file load). Red-team finding, #436. */
+ *  --env-file remains the operator's own full-file load). */
 const KNOWN_PROVIDER_KEYS = [
     "OPENAI_API_KEY",
     "ANTHROPIC_API_KEY",
@@ -52,7 +52,7 @@ export function userKeyStorePath(env, deps = {}) {
     const home = deps.homeDir ?? homedir();
     const declared = env.XDG_CONFIG_HOME?.trim();
     // The XDG spec: a relative XDG_CONFIG_HOME must be ignored. Honoring one would make the
-    // key store cwd-relative — `humanish keys set` would write a secret into the current repo.
+    // key store cwd-relative: `humanish keys set` would write a secret into the current repo.
     const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
         ? declared
         : path.join(home, ".config");
@@ -151,16 +151,16 @@ export async function discoverProviderKeys(args) {
     const fills = [];
     const ignored = [];
     // Fill-only means presence wins, including an explicitly-set empty value: an operator who
-    // exported OPENAI_API_KEY="" said "off", and a rung that "fixes" that has overridden them
-    // (red-team finding). Only a truly-unset name is fillable.
+    // exported OPENAI_API_KEY="" said "off", and a rung that "fixes" that has overridden them.
+    // Only a truly-unset name is fillable.
     const fillable = (name) => env[name] === undefined;
     const fill = (name, value, source) => {
         env[name] = value;
         fills.push({ name, source });
     };
     // Rung 2: the documented project-local overlay. Parsed atomically against a scratch env so a
-    // file loadEnvFile rejects can never half-apply (red-team finding: earlier lines used to land
-    // in env unannounced before the parse error aborted). Only allowlisted provider names cross
+    // file loadEnvFile rejects can never half-apply: otherwise lines before the parse error would
+    // land in env unannounced. Only allowlisted provider names cross
     // from the file into the real env.
     const overlayPath = path.resolve(cwd, PROJECT_OVERLAY_RELATIVE);
     if (isRegularFile(overlayPath) && !dirIsSymlink(overlayPath)) {
@@ -196,7 +196,7 @@ export async function discoverProviderKeys(args) {
     }
     // Rung 4: the humanish user-level store, read with the same lenient parser `keys set`/`list`
     // use, so one hand-mangled line degrades to that line alone instead of silently voiding the
-    // whole store (red-team finding: the strict parser disagreed with the store's own reader).
+    // whole store, as the strict parser would.
     const storePath = userKeyStorePath(env, deps);
     if (isRegularFile(storePath) && !dirIsSymlink(storePath)) {
         for (const [name, value] of readStoreEntries(storePath)) {
@@ -213,11 +213,11 @@ export async function discoverProviderKeys(args) {
         if (announced === undefined || announced.has(fill_.name))
             announce(`humanish keys: ${fill_.name} from ${fill_.source}`);
     for (const name of ignored)
-        announce(`humanish keys: ignored non-provider name ${name} — implicit discovery fills provider keys only; pass the file via --env-file to load everything in it`);
+        announce(`humanish keys: ignored ${name}, which is not a provider key. Discovery loads provider keys only; pass the file with --env-file to load every name in it.`);
     return fills;
 }
 /** True when the file's parent directory is (or traverses) a symlink at its last component:
- *  the dir-level retarget that defeats a file-level lstat check (red-team finding). */
+ *  the dir-level retarget that defeats a file-level lstat check. */
 function dirIsSymlink(filePath) {
     try {
         return lstatSync(path.dirname(filePath)).isSymbolicLink();
@@ -230,8 +230,8 @@ function storeLabel(env, deps) {
     const home = deps.homeDir ?? homedir();
     return userKeyStorePath(env, deps).replace(home, "~");
 }
-/** The nearest fill instruction for a missing key — used by doctor rows and appended to
- *  *_KEYS_MISSING errors so the failure names the fix, not just the absence (#436). */
+/** The nearest fill instruction for a missing key. Doctor rows use it, and it is appended to
+ *  *_KEYS_MISSING errors so the failure names the fix. */
 export function missingKeyHint(name) {
     switch (name) {
         case "E2B_API_KEY":
@@ -273,7 +273,7 @@ export async function probeKeySources(names, args) {
     return names.map((name) => {
         const inEnv = args.env[name] !== undefined && args.env[name]?.trim() !== "";
         // GH_TOKEN and GITHUB_TOKEN are one credential with two spellings; a doctor row that says
-        // "missing" while GITHUB_TOKEN sits in the env would be wrong (red-team nit).
+        // "missing" while GITHUB_TOKEN sits in the env would be wrong.
         const aliasInEnv = name === "GH_TOKEN" &&
             args.env.GITHUB_TOKEN !== undefined &&
             args.env.GITHUB_TOKEN.trim() !== "";
@@ -294,10 +294,10 @@ export function resolveKeyName(vendorOrName) {
     return ENV_NAME.test(vendorOrName) ? vendorOrName : null;
 }
 /** Write one key into the user store (0700 dir, 0600 file). Only allowlisted provider names
- *  are storable (the store feeds implicit discovery — an arbitrary-name store would be an env
+ *  are storable (the store feeds implicit discovery, so an arbitrary-name store would be an env
  *  injection vector with extra steps). The value must be a single non-empty line that
  *  round-trips the store's own parser byte-identically, and the write refuses symlinks at the
- *  file and its parent directory (red-team findings). */
+ *  file and its parent directory. */
 export function setUserKey(name, value, env, deps = {}) {
     const trimmed = value.trim();
     if (trimmed.length === 0 || /[\u0000-\u001f\u007f]/.test(trimmed)) {
@@ -363,8 +363,8 @@ function readStoreEntries(storePath) {
 function writeStore(storePath, entries) {
     const body = [...entries.entries()].map(([name, value]) => `${name}=${value}`).join("\n");
     const text = body.length > 0 ? `${body}\n` : "";
-    // O_NOFOLLOW: a symlinked keys.env must never carry the write to its target (red-team
-    // reproduced writing a secret through the link into an attacker-chosen file).
+    // O_NOFOLLOW: a symlinked keys.env must never carry the write to its target, which would put a
+    // secret into an attacker-chosen file.
     const fd = openSync(storePath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_NOFOLLOW, 0o600);
     try {
         ftruncateSync(fd, 0);

package/dist/observer/artifact.d.ts

@@ -1,8 +1,8 @@
 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
- * lab work starts. A missing artifact must cost seconds at startup, never a completed
+ * Resolve (and in a repo checkout, build) the Observer artifact before any run or
+ * study work starts. A missing artifact must cost seconds at startup, never a completed
  * 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

@@ -11,8 +11,8 @@ 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
- * lab work starts. A missing artifact must cost seconds at startup, never a completed
+ * Resolve (and in a repo checkout, build) the Observer artifact before any run or
+ * study work starts. A missing artifact must cost seconds at startup, never a completed
  * 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 = {}) {

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 study 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

@@ -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),
@@ -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,10 +9,12 @@ 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;
+        /** The row's cost text: participants and desktops plus the run's analyses (src/run/run-cost.ts). */
+        costLabel: string | null;
     }>;
 }
 export interface LibraryRenderOptions {

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 `
@@ -125,7 +127,10 @@ function libraryClientJs() {
       var metaBits = [run.mode || "unknown", run.streamCount + " participants", run.createdAt || ""];
       // Labeled cost token: ALWAYS "~$X est." (never a bare "$X"), so the library never implies an
       // authoritative charge. Null = omitted (advisory, fail-open on display).
-      if (run.estimatedCostUsd != null) {
+      if (run.costLabel) {
+        metaBits.push(run.costLabel + (run.costPlaceholder ? " (placeholder)" : ""));
+        if (run.costRatesAsOf) meta.title = "estimated, rates as of " + run.costRatesAsOf;
+      } else if (run.estimatedCostUsd != null) {
         metaBits.push("~$" + Number(run.estimatedCostUsd).toFixed(2) + " est." + (run.costPlaceholder ? " (placeholder)" : ""));
         if (run.costRatesAsOf) meta.title = "estimated, rates as of " + run.costRatesAsOf;
       }

package/dist/observer/listen.js

@@ -1,9 +1,10 @@
 // One loopback bind for every humanish server, with the one failure people actually hit named.
 //
-// `listen EADDRINUSE` used to surface as HUMANISH_UNEXPECTED, the command-boundary catch-all for
-// "a handler threw" (#484). Something already serving on the port is the most expected condition
-// a serve command has: a second session, a forgotten background one, someone's dev server. It only
-// bites with an explicit --port, which is exactly when a person is asking for a stable address.
+// `listen EADDRINUSE` becomes PortInUseError: HUMANISH_UNEXPECTED, the command-boundary catch-all
+// for "a handler threw", would misname it. Something already serving on the port is the most
+// expected condition a serve command has: a second session, a forgotten background one, someone's
+// dev server. It only bites with an explicit --port, which is exactly when a person is asking for a
+// stable address.
 export class PortInUseError extends Error {
     port;
     holder;

package/dist/observer/render.d.ts

@@ -48,7 +48,7 @@ export declare function serveObserver(result: ObserverResult, options?: Observer
 export interface DesktopOpenerHost {
     platform: NodeJS.Platform;
     env: NodeJS.ProcessEnv;
-    /** Whether an executable with this name is on the host's PATH. */
+    /** Whether an executable with this name is on the host's `PATH`. */
     onPath(name: string): boolean;
 }
 /**