humanish 0.107.0 → 0.108.0

package/dist/observer/artifact.js

@@ -11,7 +11,7 @@ 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 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-
@@ -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 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

@@ -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,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 `

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;
 }
 /**

package/dist/observer/render.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { runNotFoundMessage } from "../run/run-not-found.js";
 import { accessSync, constants } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
@@ -22,6 +23,10 @@ const observerPreparedRunPaths = new WeakMap();
 export function attachObserverRuntimeStreamUrls(result, streams) {
     observerRuntimeStreamUrls.set(result, streams.filter((stream) => stream.streamId && stream.url));
 }
+async function runNotFound(cwd, runInput) {
+    const message = await runNotFoundMessage(cwd, runInput);
+    return observerRunError(cwd, runInput, "HUMANISH_RUN_NOT_FOUND", message);
+}
 export async function renderObserver(cwdInput, runInput, options = {}) {
     const cwd = path.resolve(cwdInput);
     let selection;
@@ -46,7 +51,7 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
         selection = null;
     }
     if (!selection) {
-        return observerRunError(cwd, runInput, "HUMANISH_RUN_NOT_FOUND", `Run not found: ${runInput}`);
+        return runNotFound(cwd, runInput);
     }
     let preparedRunPaths;
     try {
@@ -80,7 +85,7 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
     const loaded = await loadRunBundlePrepared(selectedPhysicalCwd, preparedRunPaths);
     await validatePreparedRunArtifactPaths(preparedRunPaths);
     if (!loaded) {
-        return observerRunError(cwd, runInput, "HUMANISH_RUN_NOT_FOUND", `Run not found: ${runInput}`);
+        return runNotFound(cwd, runInput);
     }
     if (loaded.bundle.runId !== selection.runId ||
         (await realpath(loaded.runDir)) !== preparedRunPaths.physicalRunRoot) {
@@ -118,7 +123,7 @@ export async function renderObserver(cwdInput, runInput, options = {}) {
         warnings: [
             loaded.bundle.mode === "live"
                 ? "Observer renders verified local evidence artifacts; runtime stream auth URLs are not persisted."
-                : "Observer renders local contract evidence only; dry-run participants do not claim product behavior proof.",
+                : "This is a dry run: its participants are synthetic and no product behavior was tested.",
             "Before filing public feedback, use `humanish feedback issue` so redaction and public-safety checks gate the payload.",
             ...(openResult.warning ? [openResult.warning] : []),
         ],
@@ -290,7 +295,7 @@ export function desktopOpener(target, host) {
     if (host.platform === "win32")
         return { command: "cmd", args: ["/c", "start", "", target] };
     if (!host.env.DISPLAY && !host.env.WAYLAND_DISPLAY)
-        return { reason: "no display is available (DISPLAY and WAYLAND_DISPLAY are unset)" };
+        return { reason: "no display is available (`DISPLAY` and `WAYLAND_DISPLAY` are unset)" };
     if (!host.onPath("xdg-open"))
         return { reason: "xdg-open is not installed" };
     return { command: "xdg-open", args: [target] };
@@ -322,7 +327,7 @@ export function openTarget(target, host = { platform: process.platform, env: pro
             detached: true,
             stdio: "ignore",
         });
-        // An opener that disappears after the PATH check still fails asynchronously (ENOENT). The
+        // An opener that disappears after the `PATH` check still fails asynchronously (ENOENT). The
         // served URL remains usable; an opener must never crash its server.
         child.on("error", () => { });
         child.unref();

package/dist/observer/run-routes.d.ts

@@ -5,13 +5,13 @@ export interface ObserverRuntimeStreamUrl {
     streamId: string;
     url: string;
     /** Set when the participant's sandbox is gone (finished or torn down). An ended stream's live URL is a
-     *  dead noVNC page — the overlay stops injecting it so the tile falls back to the recorded
-     *  evidence (keyframe replay/screenshot) instead of rendering "sandbox not found" (#357). */
+     *  dead noVNC page; the overlay stops injecting it so the tile falls back to the recorded
+     *  evidence (keyframe replay/screenshot) instead of rendering "sandbox not found". */
     ended?: boolean;
 }
 /** internal: consumed by src/observer/serve.ts */
 export declare function serveRunPath(runRoot: PinnedDirectory, relativePath: string, response: ServerResponse, runtimeStreamUrls?: ObserverRuntimeStreamUrl[], request?: Pick<IncomingMessage, "method" | "headers">): Promise<void>;
-/** internal: exported for the #357 lifecycle tests. */
+/** internal: exported for the stream lifecycle tests. */
 export declare function withRuntimeStreamUrls(data: ObserverData, runtimeStreamUrls: ObserverRuntimeStreamUrl[]): ObserverData;
 /** internal: consumed by src/observer/serve.ts */
 export declare function buildHistoryIndex(proofRoot: PinnedDirectory, admitRun?: (runId: string, pinned: PinnedDirectory) => Promise<PinnedDirectory | null>): Promise<{

package/dist/observer/run-routes.js

@@ -161,7 +161,7 @@ async function withLocalRunStatus(runRoot, input) {
         return data;
     }
 }
-/** internal: exported for the #357 lifecycle tests. */
+/** internal: exported for the stream lifecycle tests. */
 export function withRuntimeStreamUrls(data, runtimeStreamUrls) {
     const byStream = new Map(runtimeStreamUrls.map((stream) => [stream.streamId, stream]));
     return {

package/dist/observer/serve.js

@@ -1,4 +1,5 @@
 import { listenOnLoopback, PortInUseError } from "./listen.js";
+import { runNotFoundMessage } from "../run/run-not-found.js";
 import { createServer } from "node:http";
 import path from "node:path";
 import { pinDirectChildDirectory, pinDirectory } from "./pinned-files.js";
@@ -215,7 +216,10 @@ export async function serveObserverLibrary(cwdInput, options) {
         if (!resolved || !pinned) {
             return {
                 ok: false,
-                error: { code: "HUMANISH_RUN_NOT_FOUND", message: `Run not found: ${options.entryRunId}` },
+                error: {
+                    code: "HUMANISH_RUN_NOT_FOUND",
+                    message: await runNotFoundMessage(cwd, options.entryRunId),
+                },
             };
         }
         if (options.safe && (await admission.admit(resolved)) === null) {
@@ -232,7 +236,7 @@ export async function serveObserverLibrary(cwdInput, options) {
         }
         entryRunId = resolved;
     }
-    // Counts are computed over the UNCAPPED run list, not the 80-item history
+    // Counts are computed over the uncapped run list, not the 80-item history
     // index: an edge-authed surface (non-safe) grants access to every run by direct
     // URL, and share-safe modes admit every share_ready run per request, so a
     // count capped at 80 would understate exactly what the exposure warning
@@ -277,7 +281,7 @@ export async function serveObserverLibrary(cwdInput, options) {
     }
     catch (error) {
         if (error instanceof PortInUseError) {
-            // The most expected failure a serve command has, named instead of HUMANISH_UNEXPECTED (#484).
+            // The most expected failure a serve command has, named instead of HUMANISH_UNEXPECTED.
             return { ok: false, error: { code: "HUMANISH_SERVE_PORT_IN_USE", message: error.message } };
         }
         throw error;

package/dist/observer/tunnel.js

@@ -54,7 +54,7 @@ export async function startNgrokTunnel(options) {
         child.once("error", (error) => {
             settle({
                 error: error.code === "ENOENT"
-                    ? new ServeTunnelError("HUMANISH_SERVE_TUNNEL_NOT_FOUND", "ngrok binary not found on PATH. Install ngrok, or run your own tunnel and pass --public-url <origin>.")
+                    ? new ServeTunnelError("HUMANISH_SERVE_TUNNEL_NOT_FOUND", "ngrok binary not found on `PATH`. Install ngrok, or run your own tunnel and pass --public-url <origin>.")
                     : new ServeTunnelError("HUMANISH_SERVE_TUNNEL_START_FAILED", `ngrok failed to start: ${error.message}`),
             });
         });