humanish 0.107.0 → 0.109.0

package/dist/run/status.d.ts

@@ -1,4 +1,5 @@
 import type { RunBundle } from "./bundle.js";
+import { type RunStudyProvenance } from "./study-provenance.js";
 import { type PreparedOutputRoot } from "./contained-output.js";
 import type { ExecutionOutcome } from "./judge.js";
 export declare const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
@@ -12,15 +13,6 @@ export declare const RUN_STATUS_TOUCH_MS = 5000;
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export declare const RUN_STATUS_STALE_MS: number;
-/** Which manifest a run came from, when it came from one. */
-export interface RunLabProvenance {
-    /** The lab id as declared in its manifest (`config.id`). */
-    id: string;
-    /** Repo-relative manifest path, when the run came from a file on disk. */
-    path?: string;
-    /** `committed` = humanish/labs, `ignored` = a local overlay, `explicit` = a path the operator passed. */
-    origin?: "committed" | "ignored" | "explicit";
-}
 type RunStatusState = "running" | "finished" | "interrupted";
 /** The signals the CLI's run handler records when it stops a run. */
 export type RunInterruptSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
@@ -40,6 +32,11 @@ interface RunStatusOutcome {
     };
     /** The run-level estimate, `null` when declared absent (never coerced to 0). */
     estimatedCostUsd?: number | null;
+    /**
+     * `cost.fullyEstimated`: false when some participant or desktop usage has no price, so the
+     * estimate is a lower bound. Absent means unknown, as in every record written before 0.109.
+     */
+    estimatedCostComplete?: boolean;
     durationMs?: number;
 }
 /** The outcome a finalized status record carries, read from the bundle that was just written. */
@@ -49,8 +46,13 @@ export interface RunStatusRecord {
     runId: string;
     state: RunStatusState;
     mode: "dry-run" | "live";
-    /** Absent when the run did not come from a lab manifest (a library caller, a bare `run`). */
-    lab?: RunLabProvenance;
+    /** Absent when the run did not come from a study file (a library caller, a bare `run`). */
+    study?: RunStudyProvenance;
+    /**
+     * `study`'s value, as runs saved by 0.108 and earlier wrote it. humanish no longer writes it.
+     * Read either through studyProvenanceOf.
+     */
+    lab?: RunStudyProvenance;
     /** The pid that owns the run, for local liveness checks. */
     pid: number;
     startedAt: string;
@@ -68,7 +70,7 @@ export interface RunStatusHandle {
      *  still has a record to classify. */
     readonly started: Promise<void>;
     /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
-     *  Idempotent — a second call is a no-op, so a backend with several exit paths is safe. */
+     *  Idempotent: a second call is a no-op, so a route with several exit paths is safe. */
     finish(outcome?: RunStatusOutcome): Promise<void>;
     /** After finish, add the result's ok and execution outcome to the finished record, so status.json
      *  and the result agree. Before finish it does nothing. */
@@ -85,12 +87,12 @@ export interface RunStatusHandle {
 export interface BeginRunStatusOptions {
     runId: string;
     mode: "dry-run" | "live";
-    lab?: RunLabProvenance | undefined;
+    study?: RunStudyProvenance | undefined;
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
  * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d — this file can never be the reason a process stays alive.
+ * `unref`'d, so this file can never be the reason a process stays alive.
  */
 export declare function beginRunStatus(runPaths: PreparedOutputRoot, options: BeginRunStatusOptions): RunStatusHandle;
 /** The three ways a run reads from disk. `interrupted` is a record its stopped process wrote, or a
@@ -103,19 +105,4 @@ export type RunLiveness = "running" | "interrupted" | "finished";
 export declare function classifyRunStatus(record: Pick<RunStatusRecord, "state" | "updatedAt">, nowMs: number, staleMs?: number): RunLiveness;
 /** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
 export declare function isRunStatusRecord(value: unknown): value is RunStatusRecord;
-/**
- * The legacy bridge: infer a lab id for a bundle written before this contract, where the only
- * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
- * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
- * remainder is not an id. Ids may contain colons (the removed meta-lab wrote `oss:meta`), so
- * only the first segment is stripped. Returns undefined when the bundle carries no such marker.
- */
-export declare function inferLegacyLabId(bundle: {
-    persona?: {
-        source?: string;
-    };
-    scenario?: {
-        source?: string;
-    };
-}): string | undefined;
 export {};

package/dist/run/status.js

@@ -1,14 +1,15 @@
 // Run identity and liveness on disk: one small record per run, written by every backend, that says
-// which lab the run belongs to and whether it is still alive. A reader can list and classify runs
+// which study the run belongs to and whether it is still alive. A reader can list and classify runs
 // from it without parsing every bundle, and can tell a live run from an abandoned one.
 //
 // run.json remains the evidence of record. This file is a derived index and liveness record:
 // `verify` never gates on it, nothing here is a claim about what a participant did, and when the
 // two disagree run.json wins and this file can be rebuilt from it.
 //
-// Public safety: it holds only the run id, the lab id/path/origin (the strings `humanish lab list`
+// Public safety: it holds only the run id, the study id/path/origin (the strings `humanish study list`
 // prints), the mode, a local pid and timestamps. It holds no hostname or user/path identity: an
 // operator may share the run directory, so a share-safety gate must have nothing to strip here.
+import { isProvenanceField, studyFields } from "./study-provenance.js";
 import { writeContainedOutputFile } from "./contained-output.js";
 import { redactText } from "../evidence/redaction.js";
 export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
@@ -41,12 +42,15 @@ export function runStatusOutcome(bundle) {
         ...(bundle.cost?.estimatedTotalUsd === undefined
             ? {}
             : { estimatedCostUsd: bundle.cost.estimatedTotalUsd }),
+        ...(typeof bundle.cost?.fullyEstimated === "boolean"
+            ? { estimatedCostComplete: bundle.cost.fullyEstimated }
+            : {}),
     };
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
  * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d — this file can never be the reason a process stays alive.
+ * `unref`'d, so this file can never be the reason a process stays alive.
  */
 export function beginRunStatus(runPaths, options) {
     const iso = () => new Date().toISOString();
@@ -56,7 +60,7 @@ export function beginRunStatus(runPaths, options) {
         runId: options.runId,
         state: "running",
         mode: options.mode,
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        ...studyFields(options.study),
         pid: process.pid,
         startedAt,
         updatedAt: startedAt,
@@ -170,30 +174,7 @@ export function isRunStatusRecord(value) {
         return false;
     if (typeof record.startedAt !== "string" || typeof record.updatedAt !== "string")
         return false;
-    if (record.lab !== undefined) {
-        if (record.lab === null || typeof record.lab !== "object")
-            return false;
-        if (typeof record.lab.id !== "string")
-            return false;
-    }
+    if (!isProvenanceField(record.study) || !isProvenanceField(record.lab))
+        return false;
     return true;
 }
-/**
- * The legacy bridge: infer a lab id for a bundle written before this contract, where the only
- * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
- * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
- * remainder is not an id. Ids may contain colons (the removed meta-lab wrote `oss:meta`), so
- * only the first segment is stripped. Returns undefined when the bundle carries no such marker.
- */
-export function inferLegacyLabId(bundle) {
-    for (const source of [bundle.persona?.source, bundle.scenario?.source]) {
-        if (typeof source !== "string")
-            continue;
-        if (!source.startsWith("lab:"))
-            continue;
-        const id = source.slice("lab:".length).trim();
-        if (id !== "")
-            return id;
-    }
-    return undefined;
-}

package/dist/run/stored-runs.js

@@ -1,4 +1,5 @@
 import { lstat, readdir } from "node:fs/promises";
+import { runNotFoundMessage } from "./run-not-found.js";
 import path from "node:path";
 import { redactText } from "../evidence/redaction.js";
 import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, validatePreparedRunArtifactPaths, } from "./paths.js";
@@ -66,7 +67,7 @@ export async function cleanupRun(cwdInput, runInput, hooks = {}) {
     if (!resolved) {
         return cleanupRefusal(cwd, runInput, checkedAt, {
             code: "HUMANISH_RUN_NOT_FOUND",
-            message: `Run not found: ${runInput}`,
+            message: await runNotFoundMessage(cwd, runInput),
         });
     }
     const runPaths = resolved;

package/dist/run/stream-shape.js

@@ -140,7 +140,7 @@ export function isRunSimulationStatus(value) {
         value === "running" ||
         value === "passed" ||
         // Participant outcomes (docs/principles/three-roles.md). This runtime allowlist is the actual
-        // gate — the TS union alone does not validate a bundle read back from disk.
+        // gate; the TS union alone does not validate a bundle read back from disk.
         value === "abandoned" ||
         value === "incomplete" ||
         value === "complete" ||

package/dist/run/streams.d.ts

@@ -64,14 +64,14 @@ export interface RunDesktopGeometry {
             source: "xdpyinfo";
         };
         /**
-         * The device preset as declared by the lab, present only when it differs from `requested`
+         * The device preset as declared by the study, present only when it differs from `requested`
          * because the rendered width was floored to MIN_DESKTOP_RENDER_WIDTH.
          *
          * Without this, a floored run is indistinguishable from a faithful one: `verified` compares
          * the floored number with itself and reports a match, so a reader of the bundle sees
          * requested 500 / verified 500 and reasonably concludes a 500-wide preset was asked for. A
-         * `mobile` (414) and a `small-mobile` (360) seat both render at 500 and look identical here.
-         * When this field is set, the preset width did not render; see #221.
+         * `mobile` (414) and a `small-mobile` (360) participant both render at 500 and look identical
+         * here. When this field is set, the preset width did not render.
          */
         declared?: {
             width: number;
@@ -96,7 +96,7 @@ export interface RunDesktopGeometry {
         source: "cdp";
     };
     /**
-     * Mobile fidelity beyond viewport size (#221), present only when the lab asked for it. `requested`
+     * Mobile fidelity beyond viewport size, present only when the study asked for it. `requested`
      * is what was applied through CDP; `resolved` is what the page reported about itself afterwards
      * and is the proof, never copied from the request. A run without this block is a
      * responsive-viewport study, whatever its preset is named.
@@ -122,7 +122,7 @@ export interface RunDesktopGeometry {
         };
         /**
          * Page targets the participant drove after the launch page (a link that opened in a new tab)
-         * whose own read-back reported the requested viewport width (#623). Absent when the
+         * whose own read-back reported the requested viewport width. Absent when the
          * participant never left the launch tab; a later tab that did not report the width is a
          * participant warning instead.
          */
@@ -234,9 +234,9 @@ export interface RunStream {
     };
     actor?: ActorTrace;
     /**
-     * Mid-run partial actor evidence (#441): the redacted trace items recorded so far,
+     * Mid-run partial actor evidence: the redacted trace items recorded so far,
      * flushed while a live participant is still running so the attached Observer's timeline can
-     * grow. It is deliberately not an ActorTrace: a running participant has no honest status,
+     * grow. It is deliberately not an ActorTrace: a running participant has no final status,
      * completionReason, or completedAt, and this shape cannot claim them. Present only on
      * `inProgress` bundles; the final write replaces it with the real `actor` and never
      * carries it.

package/dist/run/study-provenance.d.ts

@@ -0,0 +1,49 @@
+/** Which study a run came from, when it came from one. */
+export interface RunStudyProvenance {
+    /** The study id its file declares (`config.id`). */
+    id: string;
+    /** Project-relative path of the study file, when the run came from a file on disk. */
+    path?: string;
+    /**
+     * `committed` = humanish/studies or humanish/labs, `ignored` = a local overlay, `explicit` = a
+     * path the operator passed.
+     */
+    origin?: "committed" | "ignored" | "explicit";
+}
+/** Whether a saved record's `study` or `lab` field is absent or shaped like a provenance. */
+export declare function isProvenanceField(value: unknown): boolean;
+/**
+ * A saved record's study: a valid `study`, else a valid `lab`, else the id its persona or scenario
+ * source names by convention.
+ */
+export declare function studyProvenanceOf(record: {
+    study?: unknown;
+    lab?: unknown;
+    persona?: {
+        source?: unknown;
+    };
+    scenario?: {
+        source?: unknown;
+    };
+}): RunStudyProvenance | undefined;
+/**
+ * `study`, as run.json and status.json write it. 0.108 wrote `lab` beside it with the same value;
+ * 0.109 stopped, and studyProvenanceOf still reads `lab` from those runs.
+ */
+export declare function studyFields(study: RunStudyProvenance | undefined): {
+    study?: RunStudyProvenance;
+};
+/**
+ * The study id a run names by the `study:<id>` or `lab:<id>` convention on its persona or scenario
+ * source, the only attribution a run written before `lab` and `study` has. A prefix with an empty
+ * remainder is not an id. Ids may contain colons (`lab:oss:meta`), so only the prefix is stripped.
+ * Readers keep both prefixes for good: saved runs say `lab:`.
+ */
+export declare function inferLegacyStudyId(bundle: {
+    persona?: {
+        source?: unknown;
+    };
+    scenario?: {
+        source?: unknown;
+    };
+}): string | undefined;

package/dist/run/study-provenance.js

@@ -0,0 +1,66 @@
+// Which study a saved run came from. run.json and status.json write it as `study`; runs saved by
+// 0.108 and earlier also carry `lab` with the same value. Every reader goes through
+// studyProvenanceOf, which also reads a run older than both fields by the `study:<id>` or
+// `lab:<id>` convention on its persona and scenario sources.
+const ORIGINS = ["committed", "ignored", "explicit"];
+/** `value` as a provenance when it has an id, keeping only its fields that are valid. */
+function provenance(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const record = value;
+    if (typeof record.id !== "string" || record.id === "")
+        return undefined;
+    const origin = record.origin;
+    return {
+        id: record.id,
+        ...(typeof record.path === "string" ? { path: record.path } : {}),
+        ...(typeof origin === "string" && ORIGINS.includes(origin)
+            ? { origin: origin }
+            : {}),
+    };
+}
+/** Whether a saved record's `study` or `lab` field is absent or shaped like a provenance. */
+export function isProvenanceField(value) {
+    if (value === undefined)
+        return true;
+    if (value === null || typeof value !== "object")
+        return false;
+    return typeof value.id === "string";
+}
+/**
+ * A saved record's study: a valid `study`, else a valid `lab`, else the id its persona or scenario
+ * source names by convention.
+ */
+export function studyProvenanceOf(record) {
+    const declared = provenance(record.study) ?? provenance(record.lab);
+    if (declared !== undefined)
+        return declared;
+    const id = inferLegacyStudyId(record);
+    return id === undefined ? undefined : { id };
+}
+/**
+ * `study`, as run.json and status.json write it. 0.108 wrote `lab` beside it with the same value;
+ * 0.109 stopped, and studyProvenanceOf still reads `lab` from those runs.
+ */
+export function studyFields(study) {
+    return study === undefined ? {} : { study };
+}
+/**
+ * The study id a run names by the `study:<id>` or `lab:<id>` convention on its persona or scenario
+ * source, the only attribution a run written before `lab` and `study` has. A prefix with an empty
+ * remainder is not an id. Ids may contain colons (`lab:oss:meta`), so only the prefix is stripped.
+ * Readers keep both prefixes for good: saved runs say `lab:`.
+ */
+export function inferLegacyStudyId(bundle) {
+    for (const source of [bundle.persona?.source, bundle.scenario?.source]) {
+        if (typeof source !== "string")
+            continue;
+        const prefix = ["study:", "lab:"].find((candidate) => source.startsWith(candidate));
+        if (prefix === undefined)
+            continue;
+        const id = source.slice(prefix.length).trim();
+        if (id !== "")
+            return id;
+    }
+    return undefined;
+}

package/dist/run/study-result.d.ts

@@ -0,0 +1,11 @@
+/** The schema of a study's result on every route. */
+export declare const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
+/** The fields every route's result carries to name its route and its study. */
+export interface StudyResultIdentity<R extends string> {
+    schema: typeof STUDY_RESULT_SCHEMA;
+    route: R;
+    /** The study's `id`. */
+    studyId: string;
+}
+/** The identity fields for a result of route `route` from the study `studyId`. */
+export declare function studyResultIdentity<R extends string>(route: R, studyId: string): StudyResultIdentity<R>;

package/dist/run/study-result.js

@@ -0,0 +1,9 @@
+// The schema every route's result carries when a study runs: preview, computer use, scripted,
+// terminal and shared world. `route` says which, and route-specific fields stay on their route's
+// result type.
+/** The schema of a study's result on every route. */
+export const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
+/** The identity fields for a result of route `route` from the study `studyId`. */
+export function studyResultIdentity(route, studyId) {
+    return { schema: STUDY_RESULT_SCHEMA, route, studyId };
+}

package/dist/run/text.d.ts

@@ -1,2 +1,4 @@
 /** Escape a literal string for use inside a RegExp source. */
 export declare function escapeRegExp(value: string): string;
+/** "1 run", "2 runs"; `plural` names the irregular form, as in plural(n, "analysis", "analyses"). */
+export declare function plural(count: number, singular: string, pluralForm?: string): string;

package/dist/run/text.js

@@ -2,3 +2,7 @@
 export function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/** "1 run", "2 runs"; `plural` names the irregular form, as in plural(n, "analysis", "analyses"). */
+export function plural(count, singular, pluralForm = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : pluralForm}`;
+}

package/dist/run-study.d.ts

@@ -0,0 +1,112 @@
+import type { LocalVmInput } from "./routes/computer-use/types.js";
+import { type LateScorer } from "./study/route-inputs.js";
+import { type StudyRoute } from "./study/plan.js";
+import type { StudyDeps } from "./study/study-deps.js";
+import type { RunStudyDriving, RunStudyHomes } from "./study/run-study-homes.js";
+import { type StudyConfig } from "./study/types.js";
+import type { ObserverResult } from "./observer/render.js";
+import { type CuaActorStudyResult } from "./routes/computer-use/types.js";
+import { type PreviewStudyResult } from "./routes/preview.js";
+import { type ScriptedBrowserStudyResult } from "./routes/scripted/types.js";
+import { type ConcurrentSharedWorldStudyResult } from "./routes/shared-world/types.js";
+import { type TerminalProductStudyResult } from "./routes/terminal/types.js";
+import { type RunScorerProvenance } from "./run/bundle.js";
+import type { RunStudyProvenance } from "./run/study-provenance.js";
+/**
+ * Runs a study on its route. The options are checked against the route and mapped into the route's
+ * hook bags before anything runs. Each route closes the run it started on every exit through its
+ * own run scope (`src/run/run.ts`).
+ */
+export declare function runStudyWith(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): Promise<StudyOutcome>;
+/**
+ * The package's study runner (`src/index.ts`): runStudyWith with the public options only. A
+ * JavaScript caller that passes a field RunStudyOptions no longer has, or a humanish.lab.v2 config,
+ * is refused in the route's own result envelope before anything runs.
+ */
+export declare function runStudy(config: StudyConfig, options: RunStudyOptions): Promise<StudyOutcome>;
+/** A study planned once: the route's refusal, or the run of its plan. */
+export type PreparedStudy = {
+    readonly ok: false;
+    readonly outcome: StudyOutcome;
+} | {
+    readonly ok: true;
+    /** Runs the plan. A scorer loaded after planning joins the run's hooks; it changes no plan. */
+    run(scorer?: LateScorer): Promise<StudyOutcome>;
+};
+/**
+ * Normalizes the options and plans the study once, so a caller can present a refusal before it loads
+ * anything the run needs. A local browser study's provider is bound first, so the plan is made with
+ * it, and its desktop goes to the computer-use run as `localVm`; with inProcess the caller drives
+ * the app in process and needs no desktop.
+ */
+export declare function prepareStudy(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): Promise<PreparedStudy>;
+/**
+ * What a package caller passes to runStudy: the run's settings and the typed homes (`RunStudyHomes`,
+ * `RunStudyDriving`). Each wins over the config when provided.
+ */
+export type RunStudyOptions = RunStudyBase & RunStudyHomes & RunStudyDriving;
+interface RunStudyBase {
+    cwd: string;
+    runId?: string;
+    dryRun?: boolean;
+    open?: boolean;
+    /** Participant count override: preview participants or computer-use desktops. */
+    count?: number;
+    /** CUA fan-out only: create a new run for failed/selected participants from a prior run. */
+    rerun?: {
+        sourceRunId: string;
+        participantIds?: string[];
+    };
+    onObserverReady?: (observer: ObserverResult & {
+        ok: true;
+    }) => Promise<void> | void;
+}
+/** runStudyWith's options inside the package: the public ones plus what only the CLI and tests set. */
+export type InternalRunStudyOptions = RunStudyOptions & RunStudyInternals;
+interface RunStudyInternals {
+    /**
+     * Which manifest this run came from. planStudy puts it on the plan, and the route reads
+     * plan.study for the run's status record and bundle. Absent for a library caller that passes a
+     * StudyConfig directly; that run records no study.
+     */
+    study?: RunStudyProvenance;
+    /**
+     * Config-declared scorer provenance, forwarded alongside the
+     * loaded scorer. Its presence is the "declared" marker the terminal route reads to flip a
+     * status:"fail" verdict; the browser routes stamp it as evidence (they already flip). Core-computed
+     * (path + digest), never adopter-supplied; absent for library callers.
+     */
+    scorerProvenance?: RunScorerProvenance;
+    /** The local VM study's desktop, analysis gate and signal, for a local browser study. */
+    localVm?: LocalVmInput;
+}
+/** A run's result and the route it ran on. */
+interface RouteOutcome<R extends StudyRoute, T> {
+    route: R;
+    result: T;
+}
+export type StudyOutcome = RouteOutcome<"preview", PreviewStudyResult> | RouteOutcome<"computer-use", CuaActorStudyResult> | RouteOutcome<"scripted", ScriptedBrowserStudyResult> | RouteOutcome<"terminal", TerminalProductStudyResult> | RouteOutcome<"shared-world", ConcurrentSharedWorldStudyResult>;
+/**
+ * A plan past its route's local checks that need no scorer: the refusal they returned, or the
+ * route's run, which takes a scorer loaded after them.
+ */
+export type AdmittedPlan<R extends StudyRoute = StudyRoute> = {
+    readonly ok: false;
+    readonly outcome: Extract<StudyOutcome, {
+        route: R;
+    }>;
+} | {
+    readonly ok: true;
+    run(scorer?: LateScorer): Promise<Extract<StudyOutcome, {
+        route: R;
+    }>>;
+};
+/** The result of a run on route `R`, the `result` of that route's `StudyOutcome`. */
+export type StudyResult<R extends StudyRoute = StudyRoute> = {
+    preview: PreviewStudyResult;
+    "computer-use": CuaActorStudyResult;
+    scripted: ScriptedBrowserStudyResult;
+    terminal: TerminalProductStudyResult;
+    "shared-world": ConcurrentSharedWorldStudyResult;
+}[R];
+export {};