humanish 0.107.0 → 0.109.0

package/dist/routes/terminal/types.js

@@ -1,7 +1,8 @@
 import {} from "../../analysis/automatic-completion.js";
 import {} from "../../run/bundle.js";
-/** Provider-neutral metadata constant: the route's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
-export const TERMINAL_PRODUCT_LAB_PROVIDER_METADATA = {
+import {} from "../../run/study-result.js";
+/** Provider-neutral metadata constant: the route's non-secret tag (mirrors CUA_ACTOR_STUDY_PROVIDER_METADATA). */
+export const TERMINAL_PRODUCT_STUDY_PROVIDER_METADATA = {
     mode: "terminal-product-lab",
     tool: "humanish",
 };
@@ -13,7 +14,7 @@ export const UPLOAD_MAX_BYTES = 64 * 1024 * 1024;
 /**
  * Server-side reclamation buffer past the codex command's own wall-clock (caps.maxMinutes) kill.
  * Shorter than the desktop routes' SANDBOX_TIMEOUT_BUFFER_MS (src/substrates/e2b/lifetime.ts):
- * when #158 set it, the terminal sandbox ran nothing but the codex command, and after its kill only
+ * when this buffer was set, the terminal sandbox ran nothing but the codex command, and after its kill only
  * teardown remained.
  */
 export const TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS = 5 * 60_000;
@@ -31,6 +32,5 @@ 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.
+// bundle. Redaction runs pre-truncation so a cut can never split a secret past the scrubber.
 export const MAX_TRANSCRIPT_BYTES = 512 * 1024;
-export const TERMINAL_PRODUCT_LAB_SCHEMA = "humanish.terminal-lab-result.v1";

package/dist/run/bundle-shape.js

@@ -156,9 +156,9 @@ function isDesktopBrowserEvidence(value) {
 }
 /** Short lowercase-hex content digest (digestText default is 12 chars; tolerate longer future digests). */
 const SCORER_DIGEST_PATTERN = /^[a-f0-9]{12,64}$/;
-/** Shape guard for RunScorerProvenance (#316), mirroring isRunSubjectProvenance: tolerated-absent in
+/** Shape guard for RunScorerProvenance, mirroring isRunSubjectProvenance: tolerated-absent in
  *  isRunBundle, well-shaped when present. Semantics (does the digest still match the file) are not a
- *  verify concern — the block is core-stamped evidence of what was loaded, not a re-execution proof. */
+ *  verify concern: the block is core-stamped evidence of what was loaded and proves no re-execution. */
 function isRunScorerProvenance(value) {
     return (isRecord(value) &&
         value.schema === "humanish.scorer-provenance.v1" &&
@@ -183,7 +183,7 @@ export function isRunAdapterScore(value) {
         (value.data === undefined || isRecord(value.data)));
 }
 // 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).
+// 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) {
     if (!isRecord(value))

package/dist/run/bundle.d.ts

@@ -1,7 +1,7 @@
 import type { CommsReceivingEvidence } from "../comms/receiving-types.js";
 import { type CapturedGitState } from "./git-state.js";
 import type { SharedWorldEvidence } from "./shared-world-evidence.js";
-import type { RunLabProvenance } from "./status.js";
+import { type RunStudyProvenance } from "./study-provenance.js";
 import type { RunSimulationStatus, RunStream, RunStreamKind } from "./streams.js";
 export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
 /** The run bundle file, relative to the run directory. */
@@ -10,8 +10,8 @@ export declare const REVIEW_SCHEMA = "humanish.review.v1";
 export declare const PUBLIC_TARGET_CWD = "[target-cwd]";
 /**
  * A namespaced, product-agnostic score a thin adapter attaches to the bundle via a route's `score`
- * hook, on terminal-product or a browser route (the layer-6 extension seam, issue #154 acceptance
- * #8). Core never reads its `data` and knows none of the adopter's nouns — the `namespace` (e.g.
+ * hook, on terminal-product or a browser route (the adapter extension seam).
+ * 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 the adopter's repo and is summarized into the generic
@@ -20,7 +20,7 @@ export declare const PUBLIC_TARGET_CWD = "[target-cwd]";
  */
 export interface RunAdapterScore {
     schema: "humanish.adapter-score.v1";
-    /** The adapter's namespace — non-core, product-scoped (e.g. an adopter slug). Required + non-empty. */
+    /** The adapter's namespace: non-core, product-scoped (e.g. an adopter slug). Required + non-empty. */
     namespace: string;
     status: "pass" | "partial" | "fail";
     /** A 0-100 summary the adapter derived from its own (off-core) rubric. */
@@ -56,9 +56,8 @@ 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
-     * 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
+     * Optional, adapter-namespaced product-noun block (the adapter extension seam). 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
      * primitives. They ride under a single namespaced field so core's feedback enums
@@ -69,7 +68,7 @@ export interface RunFeedbackCandidate {
     adapter?: {
         /** Non-core, product-scoped namespace (e.g. an adopter slug). Required + non-empty. */
         namespace: string;
-        /** The adapter's product nouns. Core never reads these keys — it stays product-agnostic. */
+        /** The adapter's product nouns. Core never reads these keys, so it stays product-agnostic. */
         data: Record<string, unknown>;
     };
 }
@@ -87,11 +86,11 @@ export interface RunAdapterArtifact {
     note: string;
 }
 /**
- * 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
+ * Provenance for a config-declared adopter scorer: the repo-relative entry path and a digest
+ * of its entry-module bytes, recorded so a `review.scorer.ref`/`--scorer` run 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, because its code is its
- * provenance, so this block is absent there and every pre-#316 bundle stays byte-stable + verifiable.
+ * caller (hooks passed directly through RunStudyOptions) has implicit provenance, because its code is its
+ * provenance, so this block is absent there and every older bundle stays byte-stable + verifiable.
  *
  * 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
@@ -136,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
- * pins "same recipe" across bundles while the lab YAML in the consumer's repo stays the
+ * pins "same recipe" across bundles while the study YAML in the consumer's repo stays the
  * plaintext source of truth (publish-safe by construction).
  */
 export interface RunSubjectStateStepRecord {
@@ -151,7 +150,7 @@ export interface RunSubjectStateStepRecord {
     durationMs?: number;
 }
 /**
- * Structured subject provenance (invariant 5): what the subject was, as a code pin (repo/commit,
+ * Structured subject provenance: 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).
@@ -179,16 +178,16 @@ export interface RunSubjectProvenance {
     state: {
         /**
          * seeded: live run, steps declared, all ran ok, no external state declared.
-         * unpinned: external state declared (seed records, if any, still attached — migrating
+         * 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
+         * declared-not-run: steps declared but not (all) executed ok: dry-run contract bundles
          *   and failed live provisioning.
-         * undeclared: no subject.state block (stateless apps, app-url subjects) — the explicit
-         *   "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
+         * undeclared: no subject.state block (stateless apps, app-url subjects), the explicit
+         *   "absence declared" marker that provenance requires when there is none.
+         * external-public: 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). 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
+         *   an owned target, not an uncontrolled external DB). The marker for the external-public
          *   plane class; verify asserts it in place of the getHost seeded gate.
          */
         provenance: "seeded" | "unpinned" | "declared-not-run" | "undeclared" | "external-public";
@@ -197,7 +196,7 @@ export interface RunSubjectProvenance {
     };
 }
 /**
- * How well a run attributed interaction between actors: a separate honesty axis, orthogonal to the
+ * How well a run attributed interaction between actors: a separate evidence 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 participants drove one
  * mutable plane and their per-participant attribution is weaker (its ceiling is pinned in `sharedWorld.attributionLimits`).
@@ -254,7 +253,7 @@ export interface RunBundle {
     };
     review: ReviewSummary;
     feedbackCandidates: RunFeedbackCandidate[];
-    /** Structured subject provenance (invariant 5). Optional and additive: emitted by the
+    /** Structured subject provenance. Optional and additive: emitted by the
      * computer-use and shared-world backends and the clone scripted-browser route; tolerated absent
      * everywhere else. */
     subject?: RunSubjectProvenance;
@@ -275,7 +274,7 @@ export interface RunBundle {
         requested: "default" | "chrome" | "chromium" | "firefox";
         resolved?: string;
         /**
-         * Synthetic media devices the browser was launched with (#509): the camera feed's origin and
+         * Synthetic media devices the browser was launched with: the camera feed's origin and
          * in-sandbox path, how the permission dialog is answered, and the exact flags.
          */
         media?: {
@@ -297,7 +296,7 @@ export interface RunBundle {
      */
     rerun?: RunRerunLineage;
     /**
-     * The interaction-attribution honesty axis (#164). Absent == `isolated` (every existing bundle
+     * The interaction-attribution evidence axis. Absent == `isolated` (every existing bundle
      * byte-stable). Set to `shared-world` by the shared-world backend, paired with `sharedWorld`.
      */
     attributionClass?: RunAttributionClass;
@@ -307,15 +306,15 @@ 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 route attaches it here
+     * Optional, adapter-namespaced product score (the adapter extension seam).
+     * 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
-     * from `review.scorer.ref` / `--scorer`; absent for library callers and every pre-#316 bundle
+     * Optional provenance for a config-declared scorer. Present only when the scorer was loaded
+     * from `review.scorer.ref` / `--scorer`; absent for library callers and every older bundle
      * (tolerated-absent in isRunBundle so those still verify). Evidence, not a gate.
      */
     scorerProvenance?: RunScorerProvenance;
@@ -332,12 +331,13 @@ export interface RunBundle {
      */
     providerResources?: RunProviderResource[];
     /**
-     * Which lab manifest produced this run (#455). Optional + additive: absent on every bundle
-     * written before this contract and on library callers who pass a LabConfig directly (the run is
-     * then honestly lab-less rather than guessed). For older bundles a reader may fall back to
-     * `inferLegacyLabId`, which reads only the historical `persona.source = "lab:<id>"` convention.
+     * Which study file produced this run. Absent on a bundle written before this field and on a
+     * library caller's run (the run then has no study id rather than a guessed one). Read it, and
+     * `lab` and the source convention of older bundles, through studyProvenanceOf.
      */
-    lab?: RunLabProvenance;
+    study?: RunStudyProvenance;
+    /** `study`'s value, as runs saved by 0.108 and earlier wrote it. humanish no longer writes it. */
+    lab?: RunStudyProvenance;
     /**
      * 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
@@ -350,7 +350,7 @@ export interface RunBundle {
 /**
  * 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
+ * `reason` and contributes nothing to the summary total. `estimatedCostUsd` is never
  * coerced to 0.
  */
 export interface RunCostLine {
@@ -406,7 +406,7 @@ export interface RunCostSummary {
     };
     /** Host-side create->teardown span in minutes; null when no sandbox was created. */
     desktopMinutes: number | null;
-    /** Honest "estimated; <x> unmeasured" statement. */
+    /** The "estimated; <x> unmeasured" statement. */
     note: string;
 }
 export interface RunProviderResource {
@@ -440,7 +440,7 @@ export interface RunRerunLineage {
 /**
  * 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
+ * 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).
@@ -450,7 +450,7 @@ export interface RunRerunLineage {
  * product, is what went wrong.
  */
 export interface ParticipantOutcomes {
-    /** Participants whose sessions reached a terminal state — the denominator for every count below. */
+    /** Participants whose sessions reached a terminal state: the denominator for every count below. */
     total: number;
     /** Recorded successful sessions; completion provenance depends on the actor and its evidence. */
     reachedGoal: number;
@@ -482,14 +482,14 @@ export interface ReviewSummary {
      * The study result, separate from the verdict above.
      *
      * `verdict` answers a gate-shaped question and has to collapse a run to one word. This answers
-     * the research question — what happened to the people in the study — and does not collapse: a run
+     * the research question (what happened to the people in the study) and does not collapse: a run
      * where two of three participants finished is not usefully "fail", and a run where the harness
      * broke is a different thing from one where a persona gave up. Absent on a dry-run contract
      * bundle, which has no participants.
      */
     participants?: ParticipantOutcomes;
     /**
-     * The study's per-task completion rates (#414) — present only when the lab declared a protocol
+     * The study's per-task completion rates, present only when the study declared a protocol
      * and at least one session produced a funnel. Absent means no protocol was measured, never that
      * everyone finished.
      */
@@ -497,27 +497,27 @@ export interface ReviewSummary {
 }
 /**
  * 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.
+ * 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 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 RunTaskFunnel {
-    /** Sessions that produced a funnel — the denominator for every count below. */
+    /** Sessions that produced a funnel: the denominator for every count below. */
     sessions: number;
     tasks: Array<{
         id: string;
         /** Participants whose sessions corroborated this task complete. */
         completed: number;
-        /** Sessions whose protocol declared this task — its denominator. */
+        /** Sessions whose protocol declared this task: its denominator. */
         sessions: number;
         /** False when the task declared no success criterion: asked for, never measurable. */
         observable: boolean;
         /** Sessions where this task's criteria were never evaluated, because the observations they
          *  read never arrived. Counted apart from failures: "0/3 completed" with 3 unmeasured is a
-         *  statement about our instrument, not about the participants (#514). */
+         *  statement about our instrument, not about the participants. */
         unmeasured: number;
     }>;
 }
@@ -526,12 +526,12 @@ 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 manifest the run came from, as the plan carried it to startRun. */
+    readonly study?: RunStudyProvenance | undefined;
 }
 /**
  * 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
+ * start time and study; 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(run: BundleRun, args: {
@@ -541,7 +541,7 @@ export declare function bundleHead(run: BundleRun, args: {
     cwd?: string;
     artifactRoot?: string;
     source: RunBundle["source"];
-}): Pick<RunBundle, "schema" | "publication" | "runId" | "mode" | "simCount" | "createdAt" | "cwd" | "artifactRoot" | "lab" | "source">;
+}): Pick<RunBundle, "schema" | "publication" | "runId" | "mode" | "simCount" | "createdAt" | "cwd" | "artifactRoot" | "study" | "source">;
 /** The files every run directory holds, as the bundle names them. */
 export declare function bundleArtifacts(): RunBundle["artifacts"];
 export declare function buildRunSource(args: {

package/dist/run/bundle.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { captureGitState } from "./git-state.js";
+import { studyFields } from "./study-provenance.js";
 export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v1";
 /** The run bundle file, relative to the run directory. */
 export const RUN_BUNDLE_FILE = "run.json";
@@ -7,7 +8,7 @@ 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. The run supplies its id, mode,
- * start time and lab; the route passes the participant count and source. The public target cwd
+ * start time and study; 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(run, args) {
@@ -20,7 +21,7 @@ export function bundleHead(run, args) {
         createdAt: run.createdAt,
         cwd: args.cwd ?? PUBLIC_TARGET_CWD,
         artifactRoot: args.artifactRoot ?? path.join(".humanish", "runs", run.runId),
-        ...(run.lab === undefined ? {} : { lab: run.lab }),
+        ...studyFields(run.study),
         source: args.source,
     };
 }

package/dist/run/cost-summary.js

@@ -152,8 +152,8 @@ function costTotals(breakdown) {
 function costNote(args, totals) {
     const { estimatedTotalUsd, anyNull, placeholder, minRatesAsOf } = totals;
     const estimateNote = estimatedTotalUsd === null
-        ? `No priced spend lines this run — every cost line is DECLARED ABSENT (unknown rate / no usage / no duration); nothing is guessed. ${args.participants.some((participant) => participant.trace.executionProfile?.billing === "account-unknown") ? "Account billing remains unknown; API prices do not measure account spend." : "Add a rate to src/run/pricing.ts to estimate this model."}`
-        : `Estimated ${estimatedTotalUsd} USD total${anyNull ? " (LOWER BOUND — some lines unmeasured/unpriced)" : ""}${placeholder ? "; includes PLACEHOLDER rate(s) — confirm before trusting the magnitude" : ""}. Every figure is an ESTIMATE (rates as of ${minRatesAsOf} — the OLDEST contributing rate, since an aggregate is only as fresh as its stalest input), a rate-table multiply, NOT an authoritative provider charge.`;
+        ? `No cost line in this run has a price: each lacks a rate, usage or a duration, and none is guessed. ${args.participants.some((participant) => participant.trace.executionProfile?.billing === "account-unknown") ? "Account billing remains unknown; API prices do not measure account spend." : "Each line's reason says what is missing."}`
+        : `Estimated ${estimatedTotalUsd} USD total${anyNull ? " (a lower bound: some lines are unmeasured or unpriced)" : ""}${placeholder ? "; it uses a placeholder rate, so confirm the rate before relying on the amount" : ""}. Every figure multiplies usage by a rate table (rates as of ${minRatesAsOf}, the oldest rate used), so it is an estimate and not the provider's charge.`;
     return (estimateNote +
         ((args.desktops?.length ?? 0) > 0
             ? args.desktops.some((usage) => usage.observation !== undefined && "resources" in usage.observation)
@@ -205,7 +205,7 @@ export function spendFreeCostSummary() {
         breakdown: [],
         tokenUsage: { input: 0, output: 0, total: 0 },
         desktopMinutes: null,
-        note: "No model request and no hosted desktop: this run spent $0 by construction.",
+        note: "This run made no model request and used no hosted desktop, so it cost $0.",
     };
 }
 // Convert a host-side desktop span (ms) into billed minutes, or undefined when no sandbox ran.

package/dist/run/costs.d.ts

@@ -1,3 +1,4 @@
+import { type PreparedRunArtifactPaths } from "./paths.js";
 import type { RunIndexEntry } from "./run-index.js";
 /** Additive accounting for retained attempts. Null means no estimate, never an invented zero. */
 export interface CostTotals {
@@ -25,3 +26,25 @@ 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 readCostTotals(cwd: string, entry: RunIndexEntry): Promise<CostRow>;
+/** One run's analysis history, every distinct attempt counted once. */
+export interface AnalysisAccounting {
+    attempts: number;
+    /** Attempts that sent a request and recorded its usage. */
+    dispatched: number;
+    notDispatched: number;
+    /** Dispatched or possibly dispatched attempts without a complete price. */
+    unpriced: number;
+    /** A dispatch marker survives with no usable final accounting. */
+    unresolved: number;
+    /** The known estimates of the dispatched attempts; 0 when every attempt sent nothing. */
+    estimatedUsd: number | null;
+    /** Who billed the dispatched attempts. */
+    providers: Array<"openai" | "codex">;
+    /** History that could not be read whole; ANALYSIS_HISTORY_NOT_RECORDED when there is none. */
+    warnings: string[];
+}
+/**
+ * The single reader of a run's analysis spend. Stats totals and every surface that shows one
+ * run's cost read it, so they cannot disagree. Receipts are read without opening evidence.
+ */
+export declare function readAnalysisAccounting(prepared: PreparedRunArtifactPaths): Promise<AnalysisAccounting>;

package/dist/run/costs.js

@@ -47,7 +47,13 @@ export async function readCostTotals(cwd, entry) {
     // uncertain, whatever a run-cost warning is named.
     const runWarnings = [];
     const analysisWarnings = [];
-    costs.runEstimatedUsd = isKnownUsd(entry.estimatedCostUsd) ? entry.estimatedCostUsd : null;
+    // A dry run makes no model request and creates no desktop, so with no figure it costs $0. A
+    // recorded unknown (null) figure stays unknown.
+    costs.runEstimatedUsd = isKnownUsd(entry.estimatedCostUsd)
+        ? entry.estimatedCostUsd
+        : entry.estimatedCostUsd === undefined && entry.mode === "dry-run"
+            ? 0
+            : null;
     try {
         const prepared = await bindExistingRunArtifactPaths(cwd, entry.runId);
         const bytes = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
@@ -81,49 +87,14 @@ export async function readCostTotals(cwd, entry) {
             costs.incompleteRunEstimates = 1;
             runWarnings.push("RUN_COST_COMPLETENESS_UNKNOWN");
         }
-        const [history, automatic] = await Promise.all([
-            readAnalysisAccountingRecords(prepared),
-            readAutomaticAnalysisAccounting(prepared),
-        ]);
-        analysisWarnings.push(...history.warnings);
-        const records = new Map(history.records.map((record) => [record.id, record]));
-        if (automatic === "unknown")
-            analysisWarnings.push("AUTOMATIC_ANALYSIS_ACCOUNTING_UNKNOWN");
-        else if (automatic) {
-            if (automatic.uncertain)
-                analysisWarnings.push("AUTOMATIC_ANALYSIS_ACCOUNTING_UNKNOWN");
-            const id = automatic.reused ? automatic.analysisId : automatic.attemptId;
-            if (id && (automatic.started || automatic.analysisId !== null) && !records.has(id)) {
-                records.set(id, { id, receipt: null, start: null, legacy: false });
-            }
-        }
-        for (const record of records.values()) {
-            costs.analysisAttempts += 1;
-            if (record.legacy)
-                analysisWarnings.push("ANALYSIS_LEGACY_REPORT_ACCOUNTING");
-            const usage = record.receipt?.usage;
-            if (!usage) {
-                costs.analysisUnpricedAttempts += 1;
-                costs.analysisUnresolvedAttempts += 1;
-                continue;
-            }
-            if (!usage.dispatched) {
-                costs.analysisNotDispatchedAttempts += 1;
-                costs.analysisEstimatedUsd = sumKnown(costs.analysisEstimatedUsd, 0);
-            }
-            else {
-                costs.analysisDispatchedAttempts += 1;
-                if (isKnownUsd(usage.estimatedCostUsd)) {
-                    costs.analysisEstimatedUsd = sumKnown(costs.analysisEstimatedUsd, usage.estimatedCostUsd);
-                }
-                if (!isKnownUsd(usage.estimatedCostUsd) || !usage.usageComplete)
-                    costs.analysisUnpricedAttempts += 1;
-            }
-        }
-        // A skipped/queued automatic job says nothing about historical manual requests.
-        // Only final no-dispatch receipts contribute a supported zero to recorded attempts.
-        if (records.size === 0)
-            analysisWarnings.push("ANALYSIS_HISTORY_NOT_RECORDED");
+        const analysis = await readAnalysisAccounting(prepared);
+        analysisWarnings.push(...analysis.warnings);
+        costs.analysisAttempts = analysis.attempts;
+        costs.analysisDispatchedAttempts = analysis.dispatched;
+        costs.analysisNotDispatchedAttempts = analysis.notDispatched;
+        costs.analysisUnpricedAttempts = analysis.unpriced;
+        costs.analysisUnresolvedAttempts = analysis.unresolved;
+        costs.analysisEstimatedUsd = analysis.estimatedUsd;
         costs.analysisHistoryUncertainRuns = analysisWarnings.length > 0 ? 1 : 0;
     }
     catch {
@@ -138,3 +109,67 @@ export async function readCostTotals(cwd, entry) {
         warnings: [...new Set([...runWarnings, ...analysisWarnings])],
     };
 }
+/**
+ * The single reader of a run's analysis spend. Stats totals and every surface that shows one
+ * run's cost read it, so they cannot disagree. Receipts are read without opening evidence.
+ */
+export async function readAnalysisAccounting(prepared) {
+    const accounting = {
+        attempts: 0,
+        dispatched: 0,
+        notDispatched: 0,
+        unpriced: 0,
+        unresolved: 0,
+        estimatedUsd: null,
+        providers: [],
+        warnings: [],
+    };
+    const [history, automatic] = await Promise.all([
+        readAnalysisAccountingRecords(prepared),
+        readAutomaticAnalysisAccounting(prepared),
+    ]);
+    accounting.warnings.push(...history.warnings);
+    const records = new Map(history.records.map((record) => [record.id, record]));
+    if (automatic === "unknown")
+        accounting.warnings.push("AUTOMATIC_ANALYSIS_ACCOUNTING_UNKNOWN");
+    else if (automatic) {
+        if (automatic.uncertain)
+            accounting.warnings.push("AUTOMATIC_ANALYSIS_ACCOUNTING_UNKNOWN");
+        const id = automatic.reused ? automatic.analysisId : automatic.attemptId;
+        if (id && (automatic.started || automatic.analysisId !== null) && !records.has(id)) {
+            records.set(id, { id, receipt: null, start: null, legacy: false });
+        }
+    }
+    const providers = new Set();
+    for (const record of records.values()) {
+        accounting.attempts += 1;
+        if (record.legacy)
+            accounting.warnings.push("ANALYSIS_LEGACY_REPORT_ACCOUNTING");
+        const usage = record.receipt?.usage;
+        if (!usage) {
+            accounting.unpriced += 1;
+            accounting.unresolved += 1;
+            continue;
+        }
+        if (!usage.dispatched) {
+            accounting.notDispatched += 1;
+            accounting.estimatedUsd = sumKnown(accounting.estimatedUsd, 0);
+            continue;
+        }
+        accounting.dispatched += 1;
+        if (record.receipt)
+            providers.add(record.receipt.provider);
+        if (isKnownUsd(usage.estimatedCostUsd)) {
+            accounting.estimatedUsd = sumKnown(accounting.estimatedUsd, usage.estimatedCostUsd);
+        }
+        if (!isKnownUsd(usage.estimatedCostUsd) || !usage.usageComplete)
+            accounting.unpriced += 1;
+    }
+    // A skipped or queued automatic job says nothing about earlier manual requests. Only final
+    // no-dispatch receipts contribute a supported zero.
+    if (records.size === 0)
+        accounting.warnings.push("ANALYSIS_HISTORY_NOT_RECORDED");
+    accounting.providers = [...providers].sort();
+    accounting.warnings = [...new Set(accounting.warnings)];
+    return accounting;
+}

package/dist/run/detail.d.ts

@@ -9,7 +9,7 @@ interface RunThought {
     at?: string;
 }
 export interface RunParticipant {
-    /** Stream id — stable within a run, and what distinguishes participants 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 participant's own label, else the persona id. */
     label: string;
@@ -17,11 +17,11 @@ export interface RunParticipant {
     personaId?: string;
     /**
      * The persona's declared traits (`patience:medium`, `skill:medium`, …). This is the abbreviated
-     * persona a reader actually wants beside a live thought — it says who is struggling, which a
+     * persona a reader actually wants beside a live thought. It says who is struggling, which a
      * name alone does not.
      */
     traits: string[];
-    /** `running`, `passed`, `failed`, `contract_proof_only` — the participant'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;
@@ -30,7 +30,7 @@ export interface RunParticipant {
     actions?: number;
     /**
      * 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
+     * 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.
      */
     thoughts?: number;
@@ -49,13 +49,13 @@ export interface RunDetail {
     observerPath?: string;
 }
 /**
- * Read one run's participants. Returns null when the run has no readable bundle yet — an ordinary
+ * 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
  * 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
+ * (the only view that needs this) the one case that never renders. Nothing read here is treated
  * as a claim about what a participant did; it is what to put on a screen.
  */
 export declare function readRunDetail(cwdInput: string, runId: string): Promise<RunDetail | null>;

package/dist/run/detail.js

@@ -20,7 +20,7 @@ const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
  *
  * 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.
+ * because a partial thought read mid-write would be quoted as though the participant had finished it.
  */
 function latestThought(trace) {
     const items = trace.items ?? [];
@@ -70,7 +70,7 @@ function participantFrom(stream, index) {
  *
  * 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
+ * the cost as unknown until the moment the run ends. That is the half of a run where knowing what
  * it is costing actually changes what you do.
  */
 function costOf(trace) {
@@ -95,13 +95,13 @@ function costOf(trace) {
     }
 }
 /**
- * Read one run's participants. Returns null when the run has no readable bundle yet — an ordinary
+ * 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
  * 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
+ * (the only view that needs this) the one case that never renders. Nothing read here is treated
  * as a claim about what a participant did; it is what to put on a screen.
  */
 export async function readRunDetail(cwdInput, runId) {