humanish 0.106.0 → 0.107.0

package/dist/run/bundle.d.ts

@@ -14,9 +14,9 @@ export declare const PUBLIC_TARGET_CWD = "[target-cwd]";
  * #8). Core never reads its `data` and knows none of the adopter's nouns — the `namespace` (e.g.
  * `"acme-pixelforge"`) scopes the whole record so core schemas stay product-agnostic and a future
  * inert-field audit does not misfire on a noun core never owned. The adopter's real scorecard
- * (component weights, product rubric) lives in ITS repo and is summarized into the generic
- * status/score/summary; everything product-specific rides under `data`. This is NOT a built-in
- * product scorer — it is the SEAM the adopter's scorer plugs into without forking core.
+ * (component weights, product rubric) lives in the adopter's repo and is summarized into the generic
+ * status/score/summary; everything product-specific rides under `data`. Core ships no built-in
+ * product scorer; this is the seam the adopter's scorer plugs into without forking core.
  */
 export interface RunAdapterScore {
     schema: "humanish.adapter-score.v1";
@@ -56,14 +56,14 @@ export interface RunFeedbackCandidate {
     proposed_next_state: "watch" | "adapter-hardening" | "target-app-setup" | "actor-auth" | "setup-quality-review" | "study-quality-review";
     acceptance_proof: string[];
     /**
-     * OPTIONAL, ADAPTER-NAMESPACED product-noun block (the layer-6 extension seam, issue #154
+     * Optional, adapter-namespaced product-noun block (the layer-6 extension seam, issue #154
      * acceptance #8 + the "record product-specific concepts as NON-core nouns" list). A thin adapter
      * records product-specific concepts — public CLI/product command observed, hosted product
      * success-or-blocker, feedback id/draft observed, media/job/asset ids, explicit
-     * no-media/no-provider-spend proof, defection/friction risk — WITHOUT making any of them core
+     * no-media/no-provider-spend proof, defection/friction risk, without making any of them core
      * primitives. They ride under a single namespaced field so core's feedback enums
      * (`evidence.kind`, `proposed_next_state`) stay product-agnostic and a future inert-field audit
-     * never misfires on a noun core never owned. Core validates only the SHAPE (a non-empty
+     * never misfires on a noun core never owned. Core validates only the shape (a non-empty
      * `namespace` + a `data` record); the keys inside `data` are the adapter's, never core's.
      */
     adapter?: {
@@ -89,19 +89,19 @@ export interface RunAdapterArtifact {
 /**
  * Provenance for a CONFIG-DECLARED adopter scorer (#316): the repo-relative entry path and a digest
  * of its ENTRY-MODULE bytes, recorded so a `review.scorer.ref`/`--scorer` run honestly states which
- * out-of-tree judgment it attached. Core-computed (path + digest), never adopter-supplied. A LIBRARY
- * caller (hooks passed directly through RunLabOptions) has implicit provenance — their code IS their
- * provenance — so this block is ABSENT there and every pre-#316 bundle stays byte-stable + verifiable.
+ * out-of-tree judgment it attached. Core-computed (path + digest), never adopter-supplied. A library
+ * caller (hooks passed directly through RunLabOptions) has implicit provenance, because its code is its
+ * provenance, so this block is absent there and every pre-#316 bundle stays byte-stable + verifiable.
  *
- * The digest pins the entry file's IDENTITY, not its behavioral closure: a `export { score } from
+ * The digest pins the entry file's identity only; modules it loads are outside it: a `export { score } from
  * "../outside.mjs"` re-export is not captured, and `import()` re-opens the path (a benign same-author
- * TOCTOU). Treat it as evidence-not-gate, and do NOT extend the loader to less-trusted config.
+ * TOCTOU). Treat it as evidence-not-gate, and do not extend the loader to less-trusted config.
  */
 export interface RunScorerProvenance {
     schema: "humanish.scorer-provenance.v1";
     /** Repo-relative entry path (e.g. "scorers/example.mjs"), clamped inside the target cwd. */
     ref: string;
-    /** digestText over the readContainedRegularFile ENTRY bytes — the entry module only, not a lockfile of the executed graph. */
+    /** digestText over the readContainedRegularFile entry bytes: the entry module only, with no lockfile of the executed graph. */
     digest: string;
     /** Which door declared it: the committed manifest, or the CLI `--scorer` override. */
     source: "manifest" | "cli-flag";
@@ -135,7 +135,7 @@ export interface RunEvent {
 /**
  * One executed (or declared) subject-state seed step. Live records carry execution fields
  * (ok/exitCode/timedOut/durationMs); dry-run "declared, not run" records carry only the
- * declaration (name, phase, command DIGEST). The command itself never persists — the digest
+ * declaration (name, phase, command digest). The command itself never persists; the digest
  * pins "same recipe" across bundles while the lab YAML in the consumer's repo stays the
  * plaintext source of truth (publish-safe by construction).
  */
@@ -151,8 +151,8 @@ export interface RunSubjectStateStepRecord {
     durationMs?: number;
 }
 /**
- * Structured subject provenance (invariant 5): what the subject WAS — code pin (repo/commit,
- * or a local-tree archive digest) AND state story. Optional additive field on
+ * Structured subject provenance (invariant 5): what the subject was, as a code pin (repo/commit,
+ * or a local-tree archive digest) and state story. Optional additive field on
  * humanish.run-bundle.v1; absent on bundles from backends that have not adopted it (and on all
  * pre-existing bundles).
  */
@@ -165,7 +165,7 @@ export interface RunSubjectProvenance {
     commit?: string;
     /**
      * Local-tree-route only (additive): 64 lowercase-hex sha256 over the sorted packed-entries
-     * list (docs/contracts/schemas.md). This is the provenance PIN for the local-tree route: a
+     * list (docs/contracts/schemas.md). This is the provenance pin for the local-tree route: a
      * dirty working tree cannot be commit-pinned, so the archive content digest stands in for it.
      */
     archiveSha256?: string;
@@ -174,11 +174,11 @@ export interface RunSubjectProvenance {
      * at pack time. Absent when the packed root was not a git work tree at all.
      */
     dirty?: boolean;
-    /** Declared env NAMES provisioned for the subject — names only, values never. */
+    /** Declared env names provisioned for the subject; names only, never values. */
     envNames?: string[];
     state: {
         /**
-         * seeded: live run, steps declared, ALL ran ok, no external state declared.
+         * seeded: live run, steps declared, all ran ok, no external state declared.
          * unpinned: external state declared (seed records, if any, still attached — migrating
          *   an external DB is still unpinned overall).
          * declared-not-run: steps declared but not (all) executed ok — dry-run contract bundles
@@ -187,7 +187,7 @@ export interface RunSubjectProvenance {
          *   "absence declared" marker invariant 5 requires.
          * external-public: (#164 phase 2) an operator-DECLARED, operator-OWNED public deployment used
          *   directly as the shared plane — humanish neither provisioned nor seeded it (no getHost, no
-         *   clone, no in-sandbox filesystem). NOT "seeded" (nothing was seeded), NOT "unpinned" (this is
+         *   clone, no in-sandbox filesystem). It is not "seeded" (nothing was seeded) and not "unpinned" (this is
          *   an owned target, not an uncontrolled external DB). The honest marker for the external-public
          *   plane class; verify asserts it in place of the getHost seeded gate.
          */
@@ -197,10 +197,10 @@ export interface RunSubjectProvenance {
     };
 }
 /**
- * How well a run attributed INTERACTION between actors — a new, ORTHOGONAL honesty axis to the
+ * How well a run attributed interaction between actors: a separate honesty axis, orthogonal to the
  * persona-sampling evidence classes (which answer "how representative is the actor?"). Absent ==
- * `isolated` (every existing bundle byte-stable). `shared-world` means N roles drove ONE mutable
- * plane and their per-role attribution is weaker (its ceiling is pinned in `sharedWorld.attributionLimits`).
+ * `isolated` (every existing bundle byte-stable). `shared-world` means N participants drove one
+ * mutable plane and their per-participant attribution is weaker (its ceiling is pinned in `sharedWorld.attributionLimits`).
  */
 type RunAttributionClass = "isolated" | "shared-world";
 export interface RunBundle {
@@ -259,15 +259,15 @@ export interface RunBundle {
      * everywhere else. */
     subject?: RunSubjectProvenance;
     /**
-     * The custom E2B desktop TEMPLATE (image) the run's sandbox(es) actually launched on, from
-     * `execution.desktop.template` — so the evidence shows WHICH image ran (a subject needing
+     * The custom E2B desktop template (image) the run's sandbox(es) actually launched on, from
+     * `execution.desktop.template`, so the evidence shows which image ran (a subject needing
      * runtimes the stock `desktop` image lacks runs on an adopter's template). Optional + additive:
      * present only when a template was configured (absent == the stock `desktop` template, every
      * pre-existing bundle byte-stable). A template name is public-safe (not a secret).
      */
     desktopTemplate?: string;
     /**
-     * Browser family requested for hosted desktop actor lanes and the in-sandbox command that opened
+     * Browser family requested for hosted desktop participants and the in-sandbox command that opened
      * it, when explicitly configured. Optional + additive; absent means the historical default opener
      * path was used or the backend does not create a headed desktop.
      */
@@ -291,8 +291,8 @@ export interface RunBundle {
         };
     };
     /**
-     * Optional lineage for a run that intentionally re-executes selected lanes from a prior
-     * multi-lane run. This keeps retry-like workflows explicit: the new run is linked to the old
+     * Optional lineage for a run that intentionally re-executes selected participants from a
+     * prior multi-participant run. This keeps retry-like workflows explicit: the new run is linked to the old
      * evidence, but it never mutates or silently "fixes" the original verdict.
      */
     rerun?: RunRerunLineage;
@@ -307,20 +307,20 @@ export interface RunBundle {
      */
     sharedWorld?: SharedWorldEvidence;
     /**
-     * OPTIONAL, ADAPTER-NAMESPACED product score (the layer-6 extension seam, issue #154 acceptance
-     * #8). A thin adapter's `score` hook returns a `RunAdapterScore`; the lane attaches it here
-     * WITHOUT core knowing any product noun (the score is namespaced + its breakdown lives in `data`).
+     * Optional, adapter-namespaced product score (the layer-6 extension seam, issue #154 acceptance
+     * #8). A thin adapter's `score` hook returns a `RunAdapterScore`; the route attaches it here
+     * without core knowing any product noun (the score is namespaced + its breakdown lives in `data`).
      * The default mission-based verdict (`review`) is unchanged when no scorer hook is given.
      */
     adapterScore?: RunAdapterScore;
     /**
-     * OPTIONAL provenance for a CONFIG-DECLARED scorer (#316). Present only when the scorer was loaded
+     * Optional provenance for a config-declared scorer (#316). Present only when the scorer was loaded
      * from `review.scorer.ref` / `--scorer`; absent for library callers and every pre-#316 bundle
      * (tolerated-absent in isRunBundle so those still verify). Evidence, not a gate.
      */
     scorerProvenance?: RunScorerProvenance;
     /**
-     * OPTIONAL, ADAPTER-NAMESPACED product/state proof artifacts. Core validates
+     * Optional, adapter-namespaced product/state proof artifacts. Core validates
      * shape and local relative artifact references, then verifies the referenced
      * files exist. The adapter owns the payload schema under `namespace`.
      */
@@ -339,31 +339,33 @@ export interface RunBundle {
      */
     lab?: RunLabProvenance;
     /**
-     * OPTIONAL, ADDITIVE run-level cost ESTIMATE (humanish.run-cost-summary.v1): the sum of every
-     * lane's model-token estimate PLUS the E2B desktop-minute estimate, carrying the SAME
+     * Optional, additive run-level cost estimate (humanish.run-cost-summary.v1): the sum of every
+     * participant's model-token estimate plus the E2B desktop-minute estimate, carrying the same
      * null-discipline the terminal cost ledger already ships. Absent on pre-existing bundles and
-     * dry runs; a live run that spends nothing records an explicit zero with no lines. Every dollar figure here is an ESTIMATE,
+     * dry runs; a live run that spends nothing records an explicit zero with no lines. Every dollar figure here is an estimate,
      * never an authoritative charge; verify asserts its LABELING/provenance, never its magnitude.
      */
     cost?: RunCostSummary;
 }
 /**
- * One contributing cost line of a RunCostSummary. A line is PRESENT even when it cannot be priced
- * (records that we TRIED and could not) — an unpriceable line carries estimatedCostUsd: null + a
- * `reason` and contributes NOTHING to the summary total (invariant 5). `estimatedCostUsd` is NEVER
+ * One contributing cost line of a RunCostSummary. A line is present even when it cannot be priced
+ * (it records that we tried and could not): an unpriceable line carries estimatedCostUsd: null + a
+ * `reason` and contributes nothing to the summary total (invariant 5). `estimatedCostUsd` is never
  * coerced to 0.
  */
 export interface RunCostLine {
     kind: "model-tokens" | "desktop-minutes";
     laneId?: string;
     modelId?: string;
-    /** null = NOT MEASURED / no rate; never coerced to 0. */
+    /** null = not measured / no rate; never coerced to 0. */
     estimatedCostUsd: number | null;
     reason?: "no_rate_for_model" | "no_rate_for_desktop" | "no_token_usage" | "no_duration" | "closing_usage_unreported" | "interaction_usage_unreported" | "no_desktop_resources" | "desktop_lifetime_incomplete" | "account_billing_unknown";
     /** Pricing provenance date; non-null iff estimatedCostUsd is non-null. */
     ratesAsOf: string | null;
     source?: string;
     placeholder?: boolean;
+    /** A model-tokens line priced from runtime-turn totals at the base tier (ActorEstimatedCost). */
+    basis?: "aggregated_turns_base_rate";
     /** Optional allocation evidence on newer desktop lines; older aggregate lines remain valid. */
     desktop?: {
         minutes: number | null;
@@ -378,15 +380,15 @@ export interface RunCostLine {
     };
 }
 /**
- * The run-level cost ESTIMATE. `estimatedTotalUsd` is the rounded sum of ONLY the non-null
- * `breakdown` lines; it is null iff EVERY line is null (never 0-coerced). `fullyEstimated` is
- * false when any applicable line is null (the total is then a LOWER BOUND). Every non-null dollar
+ * The run-level cost estimate. `estimatedTotalUsd` is the rounded sum of only the non-null
+ * `breakdown` lines; it is null iff every line is null (never 0-coerced). `fullyEstimated` is
+ * false when any applicable line is null (the total is then a lower bound). Every non-null dollar
  * figure carries `ratesAsOf`; `placeholder` is true when any contributing rate is a stand-in.
  */
 export interface RunCostSummary {
     schema: "humanish.run-cost-summary.v1";
     currency: "usd";
-    /** Sum of the KNOWN (non-null) lines; null iff every applicable line is null; 0 with no lines
+    /** Sum of the known (non-null) lines; null iff every applicable line is null; 0 with no lines
      *  for a spend-free run. */
     estimatedTotalUsd: number | null;
     /** Oldest asOf across contributing rates; null when nothing was priced. */
@@ -436,14 +438,14 @@ export interface RunRerunLineage {
     }>;
 }
 /**
- * What happened to the PARTICIPANTS in a study, with the denominator attached.
+ * What happened to the participants in a study, with the denominator attached.
  *
  * A stakeholder watching through the glass forms conclusions from vivid moments — that is the
  * classic failure of the viewing room, and it is why researchers synthesize rather than letting the
  * room decide. So anything shown to a stakeholder carries its count, or it becomes a machine for
  * manufacturing certainty from n=1 (docs/principles/three-roles.md).
  *
- * These are OUTCOMES, not scores. `abandoned` is the most valuable thing a usability study
+ * These are outcomes, not scores. `abandoned` is the most valuable thing a usability study
  * produces, and `harnessFailed` is the only member that says the instrument, rather than the
  * product, is what went wrong.
  */
@@ -463,7 +465,7 @@ export interface ParticipantOutcomes {
     /**
      * Participants who reported friction or a defect on the way, whatever their outcome.
      *
-     * This is NOT a failure count and it overlaps the others on purpose — someone can reach the goal
+     * This is not a failure count, and it overlaps the others on purpose: someone can reach the goal
      * and still tell you the road there was broken. A live two-persona run made the case: both
      * participants signed in, so "2/2 reached the goal" was true, and the keyboard-first one also
      * reported that the signature step could not be completed without a mouse. Reporting only the
@@ -491,18 +493,18 @@ export interface ReviewSummary {
      * and at least one session produced a funnel. Absent means no protocol was measured, never that
      * everyone finished.
      */
-    tasks?: StudyTaskFunnel;
+    tasks?: RunTaskFunnel;
 }
 /**
  * The study's task funnel: for each declared task, how many participants completed it, out of how
  * many sessions produced a funnel. This is "where did people get stuck" as data — the number a
  * researcher reads first — where the per-participant funnels answer it one journey at a time.
  *
- * Aggregated by task id in declaration order. Every lane in a run shares the actor's protocol, so
+ * Aggregated by task id in declaration order. Every participant in a run shares the actor's protocol, so
  * ids line up across participants; a funnel missing a task id (a future mixed-protocol route)
  * simply does not count toward that task's denominator.
  */
-export interface StudyTaskFunnel {
+export interface RunTaskFunnel {
     /** Sessions that produced a funnel — the denominator for every count below. */
     sessions: number;
     tasks: Array<{
@@ -519,20 +521,25 @@ export interface StudyTaskFunnel {
         unmeasured: number;
     }>;
 }
+/** The run a bundle belongs to: the Run startRun returned, or a test's stand-in. */
+export interface BundleRun {
+    readonly runId: string;
+    readonly mode: RunBundle["mode"];
+    readonly createdAt: string;
+    /** The manifest the run came from (#455), as the plan carried it to startRun. */
+    readonly lab?: RunLabProvenance | undefined;
+}
 /**
- * The fields every run bundle starts with, in the saved order. A route passes its run, mode and
- * participant count; the public target cwd and the run's own artifact root are the defaults.
+ * The fields every run bundle starts with, in the saved order. The run supplies its id, mode,
+ * start time and lab; the route passes the participant count and source. The public target cwd
+ * and the run's own artifact root are the defaults.
  */
-export declare function bundleHead(args: {
+export declare function bundleHead(run: BundleRun, args: {
     /** Publication restrictions (real communications), saved right after the schema. */
     publication?: RunBundle["publication"];
-    runId: string;
-    mode: RunBundle["mode"];
     participants: number;
-    createdAt: string;
     cwd?: string;
     artifactRoot?: string;
-    lab?: RunLabProvenance;
     source: RunBundle["source"];
 }): Pick<RunBundle, "schema" | "publication" | "runId" | "mode" | "simCount" | "createdAt" | "cwd" | "artifactRoot" | "lab" | "source">;
 /** The files every run directory holds, as the bundle names them. */

package/dist/run/bundle.js

@@ -6,20 +6,21 @@ export const RUN_BUNDLE_FILE = "run.json";
 export const REVIEW_SCHEMA = "humanish.review.v1";
 export const PUBLIC_TARGET_CWD = "[target-cwd]";
 /**
- * The fields every run bundle starts with, in the saved order. A route passes its run, mode and
- * participant count; the public target cwd and the run's own artifact root are the defaults.
+ * The fields every run bundle starts with, in the saved order. The run supplies its id, mode,
+ * start time and lab; the route passes the participant count and source. The public target cwd
+ * and the run's own artifact root are the defaults.
  */
-export function bundleHead(args) {
+export function bundleHead(run, args) {
     return {
         schema: RUN_BUNDLE_SCHEMA,
         ...(args.publication === undefined ? {} : { publication: args.publication }),
-        runId: args.runId,
-        mode: args.mode,
+        runId: run.runId,
+        mode: run.mode,
         simCount: args.participants,
-        createdAt: args.createdAt,
+        createdAt: run.createdAt,
         cwd: args.cwd ?? PUBLIC_TARGET_CWD,
-        artifactRoot: args.artifactRoot ?? path.join(".humanish", "runs", args.runId),
-        ...(args.lab === undefined ? {} : { lab: args.lab }),
+        artifactRoot: args.artifactRoot ?? path.join(".humanish", "runs", run.runId),
+        ...(run.lab === undefined ? {} : { lab: run.lab }),
         source: args.source,
     };
 }

package/dist/run/cost-summary.js

@@ -66,6 +66,7 @@ function modelCostLines(participants) {
             ratesAsOf: est.ratesAsOf,
             ...(est.source === undefined ? {} : { source: est.source }),
             ...(est.placeholder ? { placeholder: true } : {}),
+            ...(est.basis === undefined ? {} : { basis: est.basis }),
         });
     }
     return breakdown;
@@ -123,8 +124,8 @@ function costTotals(breakdown) {
     let anyKnown = false;
     let anyNull = false;
     let placeholder = false;
-    // Aggregate freshness is CONSERVATIVE: an aggregate estimate is only as current as its OLDEST
-    // contributing rate, so ratesAsOf takes the MIN (oldest) asOf — MAX would overclaim freshness the
+    // Aggregate freshness is conservative: an aggregate estimate is only as current as its oldest
+    // contributing rate, so ratesAsOf takes the minimum (oldest) asOf; the maximum would overclaim freshness the
     // moment operator-edited rates in src/run/pricing.ts diverge. Each breakdown line keeps its own true asOf.
     let minRatesAsOf = null;
     for (const line of breakdown) {

package/dist/run/costs.d.ts

@@ -1,6 +1,6 @@
 import type { RunIndexEntry } from "./run-index.js";
 /** Additive accounting for retained attempts. Null means no estimate, never an invented zero. */
-export interface StudyCosts {
+export interface CostTotals {
     estimatedTotalUsd: number | null;
     runEstimatedUsd: number | null;
     analysisEstimatedUsd: number | null;
@@ -16,12 +16,12 @@ export interface StudyCosts {
     /** No retained history, legacy report-only usage, or unreadable/conflicting accounting. */
     analysisHistoryUncertainRuns: number;
 }
-export interface StudyCostRow {
+export interface CostRow {
     runId: string;
-    costs: StudyCosts;
+    costs: CostTotals;
     warnings: string[];
 }
-export declare function emptyStudyCosts(): StudyCosts;
-export declare function addStudyCosts(into: StudyCosts, next: StudyCosts): void;
+export declare function emptyCostTotals(): CostTotals;
+export declare function addCostTotals(into: CostTotals, next: CostTotals): void;
 /** A read-only, bounded accounting pass. Never validates findings, dispatches, repairs or writes. */
-export declare function readStudyCosts(cwd: string, entry: RunIndexEntry): Promise<StudyCostRow>;
+export declare function readCostTotals(cwd: string, entry: RunIndexEntry): Promise<CostRow>;

package/dist/run/costs.js

@@ -2,11 +2,11 @@ import { round6 } from "./pricing.js";
 import { bindExistingRunArtifactPaths } from "./paths.js";
 import { contradictsAccountBilling } from "../verify/costs.js";
 import { EVIDENCE_LIMITS } from "../analysis/evidence.js";
-import { readBoundedStudyFile } from "./study-files.js";
-import { readAutomaticStudyAnalysisAccounting } from "../analysis/job.js";
-import { readStudyAnalysisAccountingRecords } from "../analysis/store-executions.js";
+import { readBoundedFile } from "./evidence-files.js";
+import { readAutomaticAnalysisAccounting } from "../analysis/job.js";
+import { readAnalysisAccountingRecords } from "../analysis/store-executions.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
-export function emptyStudyCosts() {
+export function emptyCostTotals() {
     return {
         estimatedTotalUsd: null,
         runEstimatedUsd: null,
@@ -24,7 +24,7 @@ const isKnownUsd = (value) => typeof value === "number" && Number.isFinite(value
 function sumKnown(a, b) {
     return a === null && b === null ? null : round6((a ?? 0) + (b ?? 0));
 }
-export function addStudyCosts(into, next) {
+export function addCostTotals(into, next) {
     for (const key of ["estimatedTotalUsd", "runEstimatedUsd", "analysisEstimatedUsd"]) {
         into[key] = sumKnown(into[key], next[key]);
     }
@@ -41,8 +41,8 @@ export function addStudyCosts(into, next) {
     }
 }
 /** A read-only, bounded accounting pass. Never validates findings, dispatches, repairs or writes. */
-export async function readStudyCosts(cwd, entry) {
-    const costs = emptyStudyCosts();
+export async function readCostTotals(cwd, entry) {
+    const costs = emptyCostTotals();
     // Run-cost and analysis-history warnings stay apart: only the second kind makes the history
     // uncertain, whatever a run-cost warning is named.
     const runWarnings = [];
@@ -50,7 +50,7 @@ export async function readStudyCosts(cwd, entry) {
     costs.runEstimatedUsd = isKnownUsd(entry.estimatedCostUsd) ? entry.estimatedCostUsd : null;
     try {
         const prepared = await bindExistingRunArtifactPaths(cwd, entry.runId);
-        const bytes = await readBoundedStudyFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
+        const bytes = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
         let bundle = null;
         try {
             bundle = bytes ? JSON.parse(bytes.toString("utf8")) : null;
@@ -82,8 +82,8 @@ export async function readStudyCosts(cwd, entry) {
             runWarnings.push("RUN_COST_COMPLETENESS_UNKNOWN");
         }
         const [history, automatic] = await Promise.all([
-            readStudyAnalysisAccountingRecords(prepared),
-            readAutomaticStudyAnalysisAccounting(prepared),
+            readAnalysisAccountingRecords(prepared),
+            readAutomaticAnalysisAccounting(prepared),
         ]);
         analysisWarnings.push(...history.warnings);
         const records = new Map(history.records.map((record) => [record.id, record]));

package/dist/run/detail.d.ts

@@ -9,9 +9,9 @@ interface RunThought {
     at?: string;
 }
 export interface RunParticipant {
-    /** Stream id — stable within a run, and what distinguishes lanes of one study. */
+    /** Stream id — stable within a run, and what distinguishes participants of one study. */
     id: string;
-    /** What to call them on screen: the lane's own label, else the persona id. */
+    /** What to call them on screen: the participant's own label, else the persona id. */
     label: string;
     /** The persona id, when the trace recorded one. */
     personaId?: string;
@@ -21,7 +21,7 @@ export interface RunParticipant {
      * name alone does not.
      */
     traits: string[];
-    /** `running`, `passed`, `failed`, `contract_proof_only` — the lane's own word for itself. */
+    /** `running`, `passed`, `failed`, `contract_proof_only` — the participant's own word for itself. */
     status?: string;
     /** Why the actor stopped, when it has. */
     completionReason?: string;
@@ -29,7 +29,7 @@ export interface RunParticipant {
     turns?: number;
     actions?: number;
     /**
-     * Thoughts recorded so far. The mid-run flush carries the trace ITEMS but not the `counts` block,
+     * Thoughts recorded so far. The mid-run flush carries the trace items but not the `counts` block,
      * so a live participant has no turn count to show — but the thoughts can be counted directly, and
      * "8 thoughts" is a true statement about progress rather than an inferred turn number.
      */
@@ -52,7 +52,7 @@ export interface RunDetail {
  * Read one run's participants. Returns null when the run has no readable bundle yet — an ordinary
  * state for a run that has just started, not a failure.
  *
- * Reads the bundle NARROWLY rather than through `loadRunBundle`, which applies the strict
+ * Reads the bundle narrowly rather than through `loadRunBundle`, which applies the strict
  * evidence-of-record guard. That guard is right for verification and wrong here: a mid-run flush is
  * a partial document by definition, so validating it as a complete bundle would make the live view
  * — the only view that needs this — the one case that never renders. Nothing read here is treated

package/dist/run/detail.js

@@ -1,4 +1,4 @@
-// What ONE run is doing right now: who is in it, what they are thinking, how far they have got.
+// What one run is doing right now: who is in it, what they are thinking, how far they have got.
 // Unlike the run index, it opens the bundle, which is affordable for the one run someone is
 // looking at.
 //
@@ -7,7 +7,7 @@
 //   - `stream.actor` once it has finished.
 // Reading both means the same screen renders a run the whole way through rather than going blank
 // at the moment it completes.
-import { readAutomaticStudyAnalysis } from "../analysis/automatic.js";
+import { readAutomaticAnalysis } from "../analysis/automatic.js";
 import path from "node:path";
 import { estimateActorCostForExecution } from "./pricing.js";
 import { resolveRunPath } from "./locate.js";
@@ -18,7 +18,7 @@ const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
 /**
  * The latest reasoning a participant has recorded.
  *
- * Takes the LAST reasoning item rather than the newest by timestamp: the trace is append-ordered by
+ * Takes the last reasoning item rather than the newest by timestamp: the trace is append-ordered by
  * construction, and half of a live flush may not carry `at` yet. An item still in flight is skipped
  * — a partial thought read mid-write would be quoted as though the participant had finished it.
  */
@@ -68,7 +68,7 @@ function participantFrom(stream, index) {
 /**
  * What a participant has spent, priced the same way whether the run is finished or in flight.
  *
- * A finished trace carries its own `estimatedCost`. A live one carries the RUNNING usage and the
+ * A finished trace carries its own `estimatedCost`. A live one carries the running usage and the
  * model it prices at, so the same estimator gives a figure mid-run instead of the screen reporting
  * the cost as unknown until the moment the run ends — which is the half of a run where knowing what
  * it is costing actually changes what you do.
@@ -98,7 +98,7 @@ function costOf(trace) {
  * Read one run's participants. Returns null when the run has no readable bundle yet — an ordinary
  * state for a run that has just started, not a failure.
  *
- * Reads the bundle NARROWLY rather than through `loadRunBundle`, which applies the strict
+ * Reads the bundle narrowly rather than through `loadRunBundle`, which applies the strict
  * evidence-of-record guard. That guard is right for verification and wrong here: a mid-run flush is
  * a partial document by definition, so validating it as a complete bundle would make the live view
  * — the only view that needs this — the one case that never renders. Nothing read here is treated
@@ -126,7 +126,7 @@ export async function readRunDetail(cwdInput, runId) {
     }
     const streams = Array.isArray(bundle.streams) ? bundle.streams : [];
     const observerAbsolute = path.join(runPaths.absoluteRunRoot, "observer", "index.html");
-    const automaticAnalysis = await readAutomaticStudyAnalysis(cwd, runId);
+    const automaticAnalysis = await readAutomaticAnalysis(cwd, runId);
     return {
         ...(automaticAnalysis === undefined ? {} : { automaticAnalysis }),
         schema: RUN_DETAIL_SCHEMA,

package/dist/run/dry-run.js

@@ -37,7 +37,7 @@ async function runDryRunInScope(options, scope) {
     if (participants === null) {
         return refused(requestedCwd, warnings, {
             code: "HUMANISH_INVALID_SIM_COUNT",
-            message: "--sims must be a positive integer.",
+            message: "--count must be a positive integer.",
         });
     }
     // Bind the physical project, as the lab routes do: a symlinked cwd retargeted mid-run cannot
@@ -66,6 +66,8 @@ async function runDryRunInScope(options, scope) {
         mode: options.dryRun ? "dry-run" : "live",
         lab: options.lab,
         renderReview: renderReviewMarkdown,
+        // The run starts at the time its id and source were stamped with.
+        now: () => Date.parse(createdAt),
         ...(options.observer === undefined ? {} : { observer: { open: options.observer.open } }),
     });
     if (!started.ok)
@@ -85,16 +87,7 @@ async function runDryRunInScope(options, scope) {
     });
     const judgment = judgePreview();
     const bundle = {
-        ...bundleHead({
-            runId,
-            mode: "dry-run",
-            participants,
-            createdAt,
-            cwd,
-            artifactRoot,
-            ...(options.lab === undefined ? {} : { lab: options.lab }),
-            source,
-        }),
+        ...bundleHead(run, { participants, cwd, artifactRoot, source }),
         persona: inputs.persona,
         scenario: inputs.scenario,
         lifecycle: [
@@ -211,7 +204,7 @@ async function renderPreviewObserver(finished, warnings) {
         return undefined;
     }
 }
-/** One synthetic stream per lane kind; the preview cycles through them. */
+/** One synthetic stream per stream kind (UI, terminal and the rest); the preview cycles through them. */
 const SYNTHETIC_STREAM_TEMPLATES = [
     {
         kind: "ui",

package/dist/run/{study-files.d.ts → evidence-files.d.ts}

@@ -4,7 +4,7 @@ import { type PreparedOutputRoot } from "./contained-output.js";
  * percent-decoded up to five times, and each round must still be a plain relative path, so an
  * encoded `..` or separator cannot survive into a later decode.
  */
-export declare function isStudyEvidencePath(value: string): boolean;
+export declare function isEvidencePath(value: string): boolean;
 /**
  * True when `value` (at most `maxLength` characters) stays a plain relative path through up to five
  * rounds of percent-decoding: no round may match `unsafe`, have an empty, `.` or `..` segment, or
@@ -16,13 +16,13 @@ export declare function decodesToPlainRelativePath(value: string, maxLength: num
  * not turn an analysis budget into an unbounded read. No returned bytes have
  * authority to select another file or initiate a network request.
  */
-export declare function readBoundedStudyFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<Buffer | null>;
+export declare function readBoundedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<Buffer | null>;
 /**
  * After a bounded read returned nothing: true when the file is absent, false when something is
  * there that could not be read. Errors other than ENOENT propagate.
  */
 export declare function pathMissing(filePath: string): Promise<boolean>;
-export type BoundedStudyFileResult = {
+export type BoundedFileResult = {
     state: "read";
     bytes: Buffer;
 } | {
@@ -32,4 +32,4 @@ export type BoundedStudyFileResult = {
     state: "unavailable";
 };
 /** Size refusals are distinguished only after the same contained regular-file checks. */
-export declare function readBoundedStudyFileResult(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedStudyFileResult>;
+export declare function readBoundedFileResult(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;