humanish 0.107.0 → 0.109.0

package/dist/observer/render.js

@@ -1,4 +1,7 @@
 import { spawn } from "node:child_process";
+import { runNotFoundMessage } from "../run/run-not-found.js";
+import { readAnalysisAccounting } from "../run/costs.js";
+import { analysisCostOf } from "../run/run-cost.js";
 import { accessSync, constants } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
@@ -22,6 +25,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 +53,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,14 +87,18 @@ 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) {
         throw new Error("Observer output directory does not match the selected run.");
     }
     const observerPath = path.join(preparedRunPaths.physicalRunRoot, "observer", "index.html");
-    const analysis = projectShareCheckedAnalysis(await loadAnalysis(preparedRunPaths));
+    const spend = analysisCostOf(await readAnalysisAccounting(preparedRunPaths));
+    const analysis = {
+        ...projectShareCheckedAnalysis(await loadAnalysis(preparedRunPaths)),
+        ...(spend === null ? {} : { spend }),
+    };
     const observerData = buildObserverData(loaded.bundle);
     observerData.publicSafety.share = {
         status: verified.shareSafety.status,
@@ -118,7 +129,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 +301,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 +333,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<{
@@ -27,6 +27,7 @@ export declare function buildHistoryIndex(proofRoot: PinnedDirectory, admitRun?:
         estimatedCostUsd: number | null;
         costRatesAsOf: string | null;
         costPlaceholder: boolean;
+        costLabel: string | null;
     }>;
 }>;
 /** internal: consumed by src/observer/serve.ts */

package/dist/observer/run-routes.js

@@ -5,34 +5,55 @@ import path from "node:path";
 import { isAnalysisRecordPath, projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { listRuns } from "../run/stored-runs.js";
-import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment } from "../run/paths.js";
+import { readAnalysisAccounting } from "../run/costs.js";
+import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, } from "../run/paths.js";
+import { analysisCostOf, runCost, runCostLabel } from "../run/run-cost.js";
 import { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord } from "../run/status.js";
 import { renderObserverHtml } from "./artifact.js";
 import { buildObserverData, recordedStreamEmbed, withObserverEndings, } from "./data.js";
 import { buildArtifactSecurityHeaders } from "./http.js";
 import { assertPinnedDirectory, openContainedFile, pinDirectChildDirectory, readContainedFile, relativeToRoot, sha256OfOpenedFile, } from "./pinned-files.js";
+/** The run's artifact paths, only when they are still the pinned directory being served. */
+async function servedRunPaths(runRoot) {
+    const runId = path.basename(runRoot.physicalPath);
+    const cwd = path.dirname(path.dirname(path.dirname(runRoot.physicalPath)));
+    const prepared = await bindExistingRunArtifactPaths(cwd, runId);
+    if (prepared.physicalRunRoot !== runRoot.physicalPath ||
+        prepared.runRootIdentity.birthtimeNs !== runRoot.birthtimeNs ||
+        prepared.runRootIdentity.dev !== runRoot.dev ||
+        prepared.runRootIdentity.ino !== runRoot.ino) {
+        throw new Error("ANALYSIS_STORAGE_CHANGED");
+    }
+    return prepared;
+}
 /** Analysis cannot grant filesystem authority or make an otherwise readable recording disappear. */
 async function readObserverAnalysis(runRoot) {
+    let loaded;
     try {
-        const runId = path.basename(runRoot.physicalPath);
-        const cwd = path.dirname(path.dirname(path.dirname(runRoot.physicalPath)));
-        const prepared = await bindExistingRunArtifactPaths(cwd, runId);
-        if (prepared.physicalRunRoot !== runRoot.physicalPath ||
-            prepared.runRootIdentity.birthtimeNs !== runRoot.birthtimeNs ||
-            prepared.runRootIdentity.dev !== runRoot.dev ||
-            prepared.runRootIdentity.ino !== runRoot.ino) {
-            throw new Error("ANALYSIS_STORAGE_CHANGED");
-        }
-        return projectShareCheckedAnalysis(await loadAnalysis(prepared));
+        loaded = projectShareCheckedAnalysis(await loadAnalysis(await servedRunPaths(runRoot)));
     }
     catch {
-        return {
+        loaded = {
             state: "invalid",
             analysis: null,
             corrections: [],
             warnings: ["Analysis could not be validated against this recording."],
         };
     }
+    const spend = await readServedAnalysisSpend(runRoot);
+    return spend === undefined ? loaded : { ...loaded, spend };
+}
+/**
+ * The run's analysis spend, read by the same reader as stats, so a request whose report could not
+ * be validated still counts. Undefined when the run sent none or its history cannot be bound.
+ */
+async function readServedAnalysisSpend(runRoot) {
+    try {
+        return analysisCostOf(await readAnalysisAccounting(await servedRunPaths(runRoot))) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 /** internal: consumed by src/observer/serve.ts */
 export async function serveRunPath(runRoot, relativePath, response, runtimeStreamUrls = [], request) {
@@ -161,7 +182,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 {
@@ -219,6 +240,7 @@ admitRun) {
         if (admitRun && !root)
             return null;
         const data = root ? await readObserverData(root) : null;
+        const spend = root && data ? await readServedAnalysisSpend(root) : undefined;
         // listRuns read run.json before admission, so an admitted run's fields come from its
         // guarded read instead.
         return {
@@ -233,6 +255,9 @@ admitRun) {
             estimatedCostUsd: data?.cost?.estimatedTotalUsd ?? null,
             costRatesAsOf: data?.cost?.ratesAsOf ?? null,
             costPlaceholder: data?.cost?.placeholder ?? false,
+            // What the row shows: participants and desktops plus the run's analyses, as every
+            // surface that shows one run's cost reads it.
+            costLabel: data ? (runCostLabel(runCost(data.cost, spend)) ?? null) : null,
         };
     }));
     await assertPinnedDirectory(proofRoot);

package/dist/observer/serve.d.ts

@@ -41,7 +41,7 @@ export interface ServeResult {
 }
 interface ServeControlPlane {
     startRun?(request: {
-        labId: string;
+        studyId: string;
         dryRun: boolean;
     }): Promise<{
         accepted: boolean;

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}`),
             });
         });