humanish 0.106.1 → 0.107.0

package/dist/routes/terminal/types.js

@@ -1,9 +1,6 @@
 import {} from "../../analysis/automatic-completion.js";
-import {} from "../../run/status.js";
-import {} from "../../substrates/e2b/sdk.js";
-import { renderObserver } from "../../observer/render.js";
 import {} from "../../run/bundle.js";
-/** Provider-neutral metadata constant: the lane's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
+/** Provider-neutral metadata constant: the route's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
 export const TERMINAL_PRODUCT_LAB_PROVIDER_METADATA = {
     mode: "terminal-product-lab",
     tool: "humanish",
@@ -25,6 +22,14 @@ export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 export const PRODUCT_SETUP_TIMEOUT_MS = 300_000;
 // How much of a captured stream / log tail rides a (redacted) message field.
 export const TAIL_CHARS = 2000;
+// How much of one decoded agent message or reasoning item the actor trace keeps.
+export const MESSAGE_CHARS = 8000;
+// How many message and reasoning items the actor trace keeps, and their total text bytes. Analysis
+// reads at most 160 KiB of evidence text, and the trace is stored twice (actor.json and run.json).
+export const TEXT_ITEMS_MAX = 200;
+export const TEXT_ITEMS_BYTES = 128 * 1024;
+// The longest stdout line the participant reader holds while waiting for its newline.
+export const PENDING_LINE_CHARS = 1024 * 1024;
 // Hard cap on the retained event-stream + transcript size, so a runaway agent cannot balloon the
 // bundle. Redaction runs PRE-truncation so a cut can never split a secret past the scrubber.
 export const MAX_TRANSCRIPT_BYTES = 512 * 1024;

package/dist/run/active-runs.d.ts

@@ -0,0 +1,13 @@
+import type { PreparedRunArtifactPaths } from "./paths.js";
+import type { RunStatusHandle } from "./status.js";
+export interface ActiveRun {
+    cwd: string;
+    runId: string;
+    /** The run's own directory, so reclaim never resolves the id as an alias. */
+    paths: PreparedRunArtifactPaths;
+    status: Pick<RunStatusHandle, "interrupt">;
+}
+/** Register a started run; the returned function removes it. */
+export declare function registerActiveRun(run: ActiveRun): () => void;
+/** The runs started in this process that have not closed, oldest first. */
+export declare function activeRuns(): ActiveRun[];

package/dist/run/active-runs.js

@@ -0,0 +1,12 @@
+const active = new Set();
+/** Register a started run; the returned function removes it. */
+export function registerActiveRun(run) {
+    active.add(run);
+    return () => {
+        active.delete(run);
+    };
+}
+/** The runs started in this process that have not closed, oldest first. */
+export function activeRuns() {
+    return [...active];
+}

package/dist/run/bundle-shape.d.ts

@@ -1,7 +1,8 @@
-import { type ReviewSummary, type RunBundle } from "./bundle.js";
+import { type ReviewSummary, type RunAdapterScore, type RunBundle } from "./bundle.js";
 import { type StoredCleanupResult, type RunPointer } from "./results.js";
 export declare function isRunBundle(value: unknown): value is RunBundle;
 export declare function isCleanupResult(value: unknown): value is StoredCleanupResult;
+export declare function isRunAdapterScore(value: unknown): value is RunAdapterScore;
 export declare const ARCHIVE_SHA256_PATTERN: RegExp;
 export declare function isReviewSummary(value: unknown): value is ReviewSummary;
 export declare function isRunPointer(value: unknown): value is RunPointer;

package/dist/run/bundle-shape.js

@@ -47,14 +47,14 @@ export function isRunBundle(value) {
         (value.subject === undefined || isRunSubjectProvenance(value.subject)) &&
         (value.desktopBrowser === undefined || isDesktopBrowserEvidence(value.desktopBrowser)) &&
         (value.rerun === undefined || isRunRerunLineage(value.rerun)) &&
-        // Optional shared-world fields. Tolerant SHAPE guard only; the interaction semantics
+        // Optional shared-world fields. Tolerant shape guard only; the interaction semantics
         // (timeline well-formedness, single-plane, delta-on-pass) are the verify check's job.
         (value.attributionClass === undefined ||
             value.attributionClass === "isolated" ||
             value.attributionClass === "shared-world") &&
         (value.sharedWorld === undefined || isSharedWorldEvidence(value.sharedWorld)) &&
         // Optional, adapter-namespaced product score (the extension seam). When present, validate only
-        // its SHAPE; core never reads the adapter's `data` payload.
+        // its shape; core never reads the adapter's `data` payload.
         (value.adapterScore === undefined || isRunAdapterScore(value.adapterScore)) &&
         // Optional scorer provenance. Library callers may omit it; when present it must be
         // well-shaped.
@@ -171,7 +171,7 @@ function isRunScorerProvenance(value) {
         value.exports.length > 0 &&
         value.exports.every((name) => name === "score" || name === "deriveFeedback" || name === "deriveArtifacts"));
 }
-function isRunAdapterScore(value) {
+export function isRunAdapterScore(value) {
     return (isRecord(value) &&
         value.schema === "humanish.adapter-score.v1" &&
         typeof value.namespace === "string" &&
@@ -182,7 +182,7 @@ function isRunAdapterScore(value) {
         typeof value.summary === "string" &&
         (value.data === undefined || isRecord(value.data)));
 }
-// The local-tree archive content pin: sha256 hex, full 64 chars (NOT the repo's 16-char
+// The local-tree archive content pin: sha256 hex, full 64 chars (unlike the repo's 16-char
 // display-digest convention -- this value is the provenance pin itself, persisted in full).
 export const ARCHIVE_SHA256_PATTERN = /^[a-f0-9]{64}$/;
 function isRunSubjectProvenance(value) {

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