humanish 0.106.1 → 0.108.0

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,11 +1,12 @@
 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";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
-import { loadStudyAnalysis } from "../analysis/load.js";
+import { loadAnalysis } from "../analysis/load.js";
 import { physicalCwdOf, runIdOf, bindExistingRunArtifactPaths, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths, } from "../run/paths.js";
 import { writeContainedOutputFile } from "../run/contained-output.js";
 import { loadRunBundlePrepared } from "../run/locate.js";
@@ -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,14 +85,14 @@ 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 loadStudyAnalysis(preparedRunPaths));
+    const analysis = projectShareCheckedAnalysis(await loadAnalysis(preparedRunPaths));
     const observerData = buildObserverData(loaded.bundle);
     observerData.publicSafety.share = {
         status: verified.shareSafety.status,
@@ -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

@@ -4,14 +4,14 @@ import { type PinnedDirectory } from "./pinned-files.js";
 export interface ObserverRuntimeStreamUrl {
     streamId: string;
     url: string;
-    /** Set when the lane'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). */
+    /** 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". */
     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

@@ -2,8 +2,8 @@
 // URLs, its analysis, and its media with byte ranges. serveObserver (render.ts) and the library
 // server (serve.ts) both route requests through them.
 import path from "node:path";
-import { isStudyAnalysisRecordPath, projectShareCheckedAnalysis } from "../analysis/sharing.js";
-import { loadStudyAnalysis } from "../analysis/load.js";
+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 { RUN_STATUS_FILE, RUN_STATUS_STALE_MS, isRunStatusRecord } from "../run/status.js";
@@ -23,7 +23,7 @@ async function readObserverAnalysis(runRoot) {
             prepared.runRootIdentity.ino !== runRoot.ino) {
             throw new Error("ANALYSIS_STORAGE_CHANGED");
         }
-        return projectShareCheckedAnalysis(await loadStudyAnalysis(prepared));
+        return projectShareCheckedAnalysis(await loadAnalysis(prepared));
     }
     catch {
         return {
@@ -51,7 +51,7 @@ export async function serveRunPath(runRoot, relativePath, response, runtimeStrea
     const derivedLeaf = path.posix.basename(cleanedRelativePath);
     if (derivedRoot === ".analysis-lock" ||
         derivedLeaf.startsWith(".humanish-write-") ||
-        isStudyAnalysisRecordPath(cleanedRelativePath)) {
+        isAnalysisRecordPath(cleanedRelativePath)) {
         writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
         return;
     }
@@ -148,7 +148,7 @@ async function withLocalRunStatus(runRoot, input) {
             if (record.state === "finished") {
                 state = "finished";
             }
-            else if (now - updated <= RUN_STATUS_STALE_MS) {
+            else if (record.state === "running" && now - updated <= RUN_STATUS_STALE_MS) {
                 state = "running";
             }
         }
@@ -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.d.ts

@@ -28,6 +28,8 @@ export interface ServeResult {
     };
     runsListed: number;
     shareReadyCount?: number;
+    /** With --safe: the runs left out, grouped by grade and reasons. */
+    hiddenRuns?: HiddenRunGroup[];
     entryRunId?: string;
     opened?: boolean;
     openCommand?: string;
@@ -46,9 +48,22 @@ interface ServeControlPlane {
         runId?: string;
     }>;
 }
+/** Why verify kept a run out of a share-safe library: its grade and reason codes. */
+interface ShareRefusal {
+    status: string;
+    reasons: string[];
+}
+/** Runs a share-safe library left out for the same grade and reasons. */
+export interface HiddenRunGroup {
+    status: string;
+    reasons: string[];
+    runs: number;
+}
 export interface ShareSafetyAdmission {
     /** The files verify found share_ready, or null when the run is not admitted. */
     admit(runId: string): Promise<AdmittedRun | null>;
+    /** Why verify refused the run, after admit returned null for it; undefined otherwise. */
+    refusal(runId: string): ShareRefusal | undefined;
 }
 export declare function createShareSafetyAdmission(cwd: string, options?: {
     verifyImpl?: typeof verifyRun;
@@ -79,6 +94,8 @@ export interface ServeLibraryServer {
     mode: ServeMode;
     runsListed: number;
     shareReadyCount?: number;
+    /** With safe: the runs left out, grouped by grade and reasons. */
+    hiddenRuns?: HiddenRunGroup[];
     entryRunId?: string;
     addPublicOrigin(origin: string): void;
     close(): Promise<void>;

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";
@@ -19,11 +20,17 @@ export function createShareSafetyAdmission(cwd, options = {}) {
     // content hash at read time, which drops the entry.
     const cache = new Map();
     const shareReady = (verified) => verified.ok === true && verified.shareSafety.status === "share_ready";
-    const verifyAdmission = async (runId, runDirectory, before, forget) => {
+    const verifyAdmission = async (runId, runDirectory, before, entry, forget) => {
         // A run verify refuses is never served, so its bytes are never hashed. Hashing reads every
         // byte, and one large file in a refused run would otherwise cost startup time for nothing.
-        if (!shareReady(await verifyImpl(cwd, runId)))
+        const verified = await verifyImpl(cwd, runId);
+        if (!shareReady(verified)) {
+            entry.refusal = {
+                status: verified.shareSafety.status === "share_ready" ? "blocked" : verified.shareSafety.status,
+                reasons: verified.shareSafety.reasons.map((reason) => reason.code),
+            };
             return null;
+        }
         // Admitted: hash, verify again, and hash after, so the served bytes are the ones verify scanned.
         const hashesBefore = await hashRunInventory(runDirectory, before);
         if (!hashesBefore)
@@ -62,12 +69,31 @@ export function createShareSafetyAdmission(cwd, options = {}) {
                 if (cache.get(runId) === entry)
                     cache.delete(runId);
             };
-            entry.admitted = verifyAdmission(runId, runDirectory, before, forget).catch(() => null);
+            entry.admitted = verifyAdmission(runId, runDirectory, before, entry, forget).catch(() => {
+                entry.refusal = { status: "unverifiable", reasons: ["VERIFY_FAILED"] };
+                return null;
+            });
             cache.set(runId, entry);
             return entry.admitted;
         },
+        refusal(runId) {
+            return cache.get(runId)?.refusal;
+        },
     };
 }
+/** The refused runs grouped by grade and reasons, the largest group first. */
+function hiddenRunGroups(refusals) {
+    const groups = new Map();
+    for (const refusal of refusals) {
+        const key = `${refusal.status}\0${refusal.reasons.join(",")}`;
+        const group = groups.get(key);
+        if (group)
+            group.runs += 1;
+        else
+            groups.set(key, { ...refusal, runs: 1 });
+    }
+    return [...groups.values()].sort((left, right) => right.runs - left.runs);
+}
 function sameHashes(left, right) {
     return left.size === right.size && [...left].every(([key, hash]) => right.get(key) === hash);
 }
@@ -190,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) {
@@ -207,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
@@ -215,10 +244,15 @@ export async function serveObserverLibrary(cwdInput, options) {
     const allRuns = (await listRuns(cwd)).runs;
     let runsListed;
     let shareReadyCount;
+    let hiddenRuns;
     if (options.safe) {
         const admitted = await Promise.all(allRuns.map((run) => admission.admit(run.runId)));
         shareReadyCount = admitted.filter((run) => run !== null).length;
         runsListed = shareReadyCount;
+        // A run refused before verify ran, such as one whose files cannot be listed, is unverifiable.
+        hiddenRuns = hiddenRunGroups(allRuns
+            .filter((_run, index) => admitted[index] === null)
+            .map((run) => admission.refusal(run.runId) ?? { status: "unverifiable", reasons: ["VERIFY_FAILED"] }));
     }
     else {
         runsListed = allRuns.length;
@@ -247,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;
@@ -266,6 +300,7 @@ export async function serveObserverLibrary(cwdInput, options) {
             mode,
             runsListed,
             ...(shareReadyCount !== undefined ? { shareReadyCount } : {}),
+            ...(hiddenRuns !== undefined ? { hiddenRuns } : {}),
             ...(entryRunId ? { entryRunId } : {}),
             // A tunnel's public origin is only known after the tunnel starts (post bind); this lets the
             // caller declare it, extending the Host allowlist so the authenticated edge forwarding under

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