humanish 0.107.0 → 0.108.0

package/dist/run/judge.d.ts

@@ -6,7 +6,7 @@ export interface BlockerFacts {
     completionReason: ActorCompletionReason;
     /** A harness-owned stop condition ended the session: a matched stopWhen or a completed dwell window. */
     stopConditionMatched: boolean;
-    /** What the participant declared in a field, when its provider has one (#570). */
+    /** What the participant declared in a field, when its provider has one. */
     declaredOutcome?: ParticipantDeclaredOutcome;
     /** The route's reading of the closing report: it describes a blocker or asks for instructions. */
     closingReportReadsBlocked: boolean;
@@ -23,7 +23,7 @@ export interface SessionEnding extends BlockerFacts {
 export declare function hollowCompletion(ending: SessionEnding): boolean;
 /**
  * The participant said it reached the goal but reported a blocker. A declared outcome is its own
- * word and wins (#570). Without one, the closing report is read, unless a stop condition ended the
+ * word and wins. Without one, the closing report is read, unless a stop condition ended the
  * session: a matched stopWhen is structured completion evidence and overrides the text.
  */
 export declare function selfReportedBlocker(ending: BlockerFacts): boolean;
@@ -60,12 +60,18 @@ export declare function participantHarnessFailed(participant: ParticipantFacts):
  * goal_satisfied claim with zero engagement is a session that ran out before anything happened;
  * one whose final message describes a blocker is a participant who could not proceed and said so.
  * Both keep their trace status (the claim is evidence); neither is a participant who reached the
- * goal. One rule for the single participant and the fan-out roll-up (#476).
+ * goal. One rule for the single participant and the fan-out roll-up.
  */
 export declare function participantStatus(status: ActorStatus, judgments: {
     noEngagement: boolean;
     selfReportedBlocker: boolean;
 } | undefined): ActorStatus;
+/**
+ * A verdict as review.md prints it. The schema keeps `contract_proof_only`, which a dry run always
+ * gets and a live run gets while it is in progress or when no participant result came back, so
+ * the reader sees "dry run" or "no verdict" by the run's mode.
+ */
+export declare function verdictText(verdict: Verdict, mode: "dry-run" | "live"): string;
 /** The review verdict for one participant's status. */
 export declare function verdictForStatus(status: ActorStatus): Verdict;
 declare const judged: unique symbol;
@@ -77,7 +83,7 @@ export interface Judgment {
     readonly verdict: Verdict;
     /**
      * The run met its route's pass rule: every expected participant passed and, on shared-world,
-     * the seats showed the concurrency verify requires. A dry run passes as a contract.
+     * the participants showed the concurrency verify requires. A dry run passes as a contract.
      */
     readonly passed: boolean;
     /** A type-only mark that judgmentOf made this judgment; it does not exist at runtime. */
@@ -126,13 +132,13 @@ export interface OutcomePolicy {
 export type JudgedRoute = "computer-use" | "shared-world" | "terminal" | "scripted" | "preview";
 /** Each route's outcome policy, in one place. */
 export declare const OUTCOME_POLICIES: Readonly<Record<JudgedRoute, OutcomePolicy>>;
-/** What a shared-world run observed about its one world, beside how each seat ended. */
+/** What a shared-world run observed about its one world, beside how each participant ended. */
 export interface SharedWorldFacts {
-    /** Two or more seats were live at the same time. */
+    /** Two or more participants were live at the same time. */
     overlap: boolean;
     /** Provisioned plane only: the shared state changed at or after the first overlap started. */
     stateChangedUnderOverlap?: boolean;
-    /** External-public plane only: every seat reached one lobby. */
+    /** External-public plane only: every participant reached one lobby. */
     lobbyConvergence?: boolean;
 }
 /** A shared-world run's judgment, with the world facts its review and result also report. */
@@ -162,15 +168,15 @@ export declare function judgeParticipants(args: {
     participants: ParticipantFacts[];
 }): Judgment;
 /**
- * Why a shared-world run whose seats all passed still fails, or undefined when its world facts
- * meet what verify's shared-world check requires of a pass: two seats live at the same time and,
- * on the provisioned plane, a shared-state change at or after the first overlap started.
+ * Why a shared-world run whose participants all passed still fails, or undefined when its world
+ * facts meet what verify's shared-world check requires of a pass: two participants live at the same
+ * time and, on the provisioned plane, a shared-state change at or after the first overlap started.
  */
 export declare function sharedWorldShortfall(world: SharedWorldFacts): string | undefined;
 /**
- * A shared-world run: it passes only when every expected seat passed and the world facts have no
- * shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run still
- * in progress are contracts. Lobby convergence is recorded but not read.
+ * A shared-world run: it passes only when every expected participant passed and the world facts
+ * have no shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run
+ * still in progress are contracts. Lobby convergence is recorded but not read.
  */
 export declare function judgeSharedWorld(args: {
     dryRun: boolean;

package/dist/run/judge.js

@@ -24,7 +24,7 @@ export function hollowCompletion(ending) {
 }
 /**
  * The participant said it reached the goal but reported a blocker. A declared outcome is its own
- * word and wins (#570). Without one, the closing report is read, unless a stop condition ended the
+ * word and wins. Without one, the closing report is read, unless a stop condition ended the
  * session: a matched stopWhen is structured completion evidence and overrides the text.
  */
 export function selfReportedBlocker(ending) {
@@ -65,7 +65,7 @@ export function participantHarnessFailed(participant) {
  * goal_satisfied claim with zero engagement is a session that ran out before anything happened;
  * one whose final message describes a blocker is a participant who could not proceed and said so.
  * Both keep their trace status (the claim is evidence); neither is a participant who reached the
- * goal. One rule for the single participant and the fan-out roll-up (#476).
+ * goal. One rule for the single participant and the fan-out roll-up.
  */
 export function participantStatus(status, judgments) {
     if (status !== "passed" || judgments === undefined)
@@ -76,6 +76,16 @@ export function participantStatus(status, judgments) {
         return "blocked";
     return status;
 }
+/**
+ * A verdict as review.md prints it. The schema keeps `contract_proof_only`, which a dry run always
+ * gets and a live run gets while it is in progress or when no participant result came back, so
+ * the reader sees "dry run" or "no verdict" by the run's mode.
+ */
+export function verdictText(verdict, mode) {
+    if (verdict !== "contract_proof_only")
+        return verdict;
+    return mode === "dry-run" ? "dry run" : "no verdict";
+}
 /** The review verdict for one participant's status. */
 export function verdictForStatus(status) {
     switch (status) {
@@ -148,9 +158,9 @@ export function judgeParticipants(args) {
     return judgmentOf(verdict, args.dryRun);
 }
 /**
- * Why a shared-world run whose seats all passed still fails, or undefined when its world facts
- * meet what verify's shared-world check requires of a pass: two seats live at the same time and,
- * on the provisioned plane, a shared-state change at or after the first overlap started.
+ * Why a shared-world run whose participants all passed still fails, or undefined when its world
+ * facts meet what verify's shared-world check requires of a pass: two participants live at the same
+ * time and, on the provisioned plane, a shared-state change at or after the first overlap started.
  */
 export function sharedWorldShortfall(world) {
     if (!world.overlap) {
@@ -162,9 +172,9 @@ export function sharedWorldShortfall(world) {
     return undefined;
 }
 /**
- * A shared-world run: it passes only when every expected seat passed and the world facts have no
- * shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run still
- * in progress are contracts. Lobby convergence is recorded but not read.
+ * A shared-world run: it passes only when every expected participant passed and the world facts
+ * have no shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run
+ * still in progress are contracts. Lobby convergence is recorded but not read.
  */
 export function judgeSharedWorld(args) {
     const passed = args.participants.length === args.expected &&

package/dist/run/paths.d.ts

@@ -49,7 +49,7 @@ export declare function createRunArtifactPaths(cwdInput: string, runId: string):
 export declare function validatePreparedRunArtifactPaths(prepared: PreparedRunArtifactPaths): Promise<PreparedRunArtifactPaths>;
 /**
  * The physical project directory for a caller's cwd, bound before a run is resolved so a symlinked
- * cwd retargeted later cannot move reads or writes to another project (#1012). A cwd that does not
+ * cwd retargeted later cannot move reads or writes to another project. A cwd that does not
  * resolve is returned as given, so the caller still reports it missing.
  */
 export declare function resolvePhysicalCwd(cwdInput: string): Promise<string>;

package/dist/run/paths.js

@@ -107,7 +107,7 @@ export async function validatePreparedRunArtifactPaths(prepared) {
 }
 /**
  * The physical project directory for a caller's cwd, bound before a run is resolved so a symlinked
- * cwd retargeted later cannot move reads or writes to another project (#1012). A cwd that does not
+ * cwd retargeted later cannot move reads or writes to another project. A cwd that does not
  * resolve is returned as given, so the caller still reports it missing.
  */
 export async function resolvePhysicalCwd(cwdInput) {

package/dist/run/pricing.d.ts

@@ -25,7 +25,7 @@ export interface ModelRate {
         inputMultiplier: number;
         outputMultiplier: number;
     };
-    /** "YYYY-MM-DD" the entry was last checked against `source`. */
+    /** The `YYYY-MM-DD` date the entry was last checked against `source`. */
     asOf: string;
     /** Public pricing page the number came from (a comment/URL, never a secret). */
     source: string;
@@ -83,7 +83,7 @@ export interface ActorEstimatedCost {
         /** Of `inputTokens`, how many were billed at the reduced cached rate. Present only when the
          *  provider reported cache hits and the rate sheet models a cached rate. */
         cachedInputTokens?: number;
-        /** Of `inputTokens`, how many were billed at the cache-WRITE rate (OpenAI 5.6+). */
+        /** Of `inputTokens`, how many were billed at the cache-write rate (OpenAI 5.6+). */
         cacheWriteInputTokens?: number;
         /** How many requests crossed the long-context threshold and were re-tiered. Present only
          *  when per-request `turns` records made exact tiering possible. */
@@ -104,6 +104,11 @@ export interface DesktopCostEstimate {
     usdPerSecond?: number;
 }
 export declare const MODEL_RATES: Record<string, ModelRate>;
+/**
+ * The refusal for a spend cap on a model this table cannot price. It names the priced models,
+ * since an npm install cannot edit this file.
+ */
+export declare function unpricedCapMessage(model: string): string;
 export declare const DESKTOP_RATE: DesktopRate;
 export declare function isDesktopResources(value: unknown): value is DesktopResources;
 /** Price one observed allocation. Missing quantities/rates stay unknown, never a stock guess. */
@@ -113,8 +118,8 @@ export declare function estimateAllocatedDesktopCost(minutes: number | undefined
 export declare function round6(n: number): number;
 /**
  * Estimate one actor trace's model-token cost from its trace tokenUsage + model id. Deterministic;
- * the rate table is injectable (tests pass a fake sheet). Returns a DECLARED-ABSENT estimate
- * (estimatedCostUsd: null + a reason) for a missing rate or missing usage — never a guessed cost.
+ * the rate table is injectable (tests pass a fake sheet). Returns a declared-absent estimate
+ * (estimatedCostUsd: null + a reason) for a missing rate or missing usage, never a guessed cost.
  */
 export declare function estimateActorCostForExecution(usage: ActorTokenUsage | undefined, modelId: string | undefined, profile?: {
     billing?: unknown;
@@ -128,7 +133,7 @@ export declare function estimateAggregatedTurnCost(tokenUsage: ActorTokenUsage |
 export declare function estimateActorCost(tokenUsage: ActorTokenUsage | undefined, modelId: string | undefined, rates?: Record<string, ModelRate>): ActorEstimatedCost;
 /**
  * Estimate the E2B desktop-minute cost from a host-side create->teardown span (minutes). The rate
- * is injectable. Returns a DECLARED-ABSENT estimate (null + "no_duration") when no duration was
- * measured (no sandbox / unmeasurable span) — never a guessed 0.
+ * is injectable. Returns a declared-absent estimate (null + "no_duration") when no duration was
+ * measured (no sandbox / unmeasurable span), never a guessed 0.
  */
 export declare function estimateDesktopCost(minutes: number | undefined, rate?: DesktopRate): DesktopCostEstimate;

package/dist/run/pricing.js

@@ -6,10 +6,10 @@
 // This module is pure (node builtins only, no deps) and deterministic: the estimator functions take
 // an optional injected rate table/rate so tests drive assertions with a fake sheet and never depend
 // on the live numbers below. An unknown model/desktop rate yields a declared-absent estimate
-// (estimatedCostUsd: null + a reason) and never a guessed or silent-zero cost (invariant 5). A bare
+// (estimatedCostUsd: null + a reason) and never a guessed or silent-zero cost. A bare
 // `costUsd` elsewhere in the contract means a provider actually billed that amount; the
 // token-derived estimate here always lives under `estimatedCostUsd` so a reader can never confuse
-// an estimate for an authoritative charge (invariant 6).
+// an estimate for an authoritative charge.
 export const PRICING_SCHEMA = "humanish.pricing.v1";
 export const ACTOR_ESTIMATED_COST_SCHEMA = "humanish.actor-estimated-cost.v1";
 // The gpt-5.6 long-context tier: >272K input tokens re-prices the full request at 2x
@@ -44,14 +44,14 @@ const GPT6_ASTRA_AS_OF = "2026-09-03";
 // case-insensitive on a trimmed id). An id missing here is declared absent, never guessed.
 export const MODEL_RATES = {
     // OpenAI computer-use-preview (the classic CUA model). ~$3 / 1M input, ~$12 / 1M output.
-    // source: openai.com/api/pricing (verify — providers change without notice).
+    // source: openai.com/api/pricing (verify: providers change without notice).
     "computer-use-preview": {
         inputUsdPerToken: 3e-6,
         outputUsdPerToken: 12e-6,
         asOf: "2026-08-01",
         source: "openai.com/api/pricing (computer-use-preview)",
     },
-    // gpt-5.5: the PREVIOUS-generation CUA default, kept so pinned labs and old bundles still
+    // gpt-5.5: the previous-generation CUA default, kept so pinned labs and old bundles still
     // price. Pre-5.6 models bill no cache-write fee (prompt-caching guide) and no long-context
     // tier was published for it.
     "gpt-5.5": {
@@ -59,7 +59,7 @@ export const MODEL_RATES = {
         outputUsdPerToken: 30e-6,
         cachedInputUsdPerToken: 0.5e-6,
         asOf: "2026-08-05",
-        source: "openrouter.ai/openai/gpt-5.5 (gpt-5.5 no longer on openai.com/api/pricing; see #334)",
+        source: "openrouter.ai/openai/gpt-5.5 (gpt-5.5 is no longer listed on openai.com/api/pricing)",
     },
     // The gpt-5.6 family (live sheet 2026-08-18, standard tier, short-context base rates;
     // the longContext block prices the >272K re-tier when per-request turns are recorded).
@@ -96,6 +96,13 @@ const DESKTOP_RESOURCE_RATE = {
 // 2026-09-05 had 8 vCPU / 8 GiB. This is the largest CPU/RAM combination on that public sheet, not
 // a provider billing ceiling or a claim about custom/enterprise templates. Runtime CUA estimates
 // use observed allocation resources through estimateAllocatedDesktopCost instead of this fallback.
+/**
+ * The refusal for a spend cap on a model this table cannot price. It names the priced models,
+ * since an npm install cannot edit this file.
+ */
+export function unpricedCapMessage(model) {
+    return `execution.caps sets a spend cap (maxUsd or maxTotalUsd), but humanish has no rate for model "${model}", so it cannot enforce the cap and refuses to start. Priced models: ${Object.keys(MODEL_RATES).sort().join(", ")}. Use one of them, or remove maxUsd and maxTotalUsd to run without a cap.`;
+}
 export const DESKTOP_RATE = {
     usdPerMinute: 0.00888,
     asOf: "2026-09-05",
@@ -158,8 +165,8 @@ export function round6(n) {
 }
 /**
  * Estimate one actor trace's model-token cost from its trace tokenUsage + model id. Deterministic;
- * the rate table is injectable (tests pass a fake sheet). Returns a DECLARED-ABSENT estimate
- * (estimatedCostUsd: null + a reason) for a missing rate or missing usage — never a guessed cost.
+ * the rate table is injectable (tests pass a fake sheet). Returns a declared-absent estimate
+ * (estimatedCostUsd: null + a reason) for a missing rate or missing usage, never a guessed cost.
  */
 export function estimateActorCostForExecution(usage, modelId, profile) {
     return profile?.billing === "account-unknown"
@@ -207,7 +214,7 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     const outTok = tokenUsage.output ?? 0;
     // Long-context tiering needs to know each request's input size (the provider re-prices whole
     // requests past the threshold), so it engages only when per-turn usage records exist and their
-    // input sums to the reported total — a partial turn ledger must not silently price the missing
+    // input sums to the reported total, because a partial turn ledger must not silently price the missing
     // remainder at the wrong tier. Otherwise totals price on the base (short-context) rate, which is
     // the under-estimate direction and never trips a cap early.
     const turns = tokenUsage.turns ?? [];
@@ -232,12 +239,12 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     // and on a session that threads provider state it is the majority of input, and pricing it at the
     // full rate overstates real spend by up to ~10x. Cache writes bill at their own rate (1.25x on
     // OpenAI 5.6+) as the total rate for those tokens; a sheet without a write rate prices writes as
-    // plain input (pre-5.6: writes are free-of-extra-fee, i.e. plain input). Every piece is honestly
-    // absent: no reported split means no discount and no surcharge assumed.
+    // plain input (pre-5.6: writes are free-of-extra-fee, i.e. plain input). An unreported piece
+    // stays absent: no reported split means no discount and no surcharge assumed.
     const priceRequest = (usage, tierable) => {
         const reqIn = usage.input ?? 0;
         const reqOut = usage.output ?? 0;
-        // Tiering applies only to a real per-REQUEST record: session totals crossing the threshold
+        // Tiering applies only to a real per-request record: session totals crossing the threshold
         // say nothing about any single request, so totals always price on the base tier.
         const long = tierable && rate.longContext !== undefined && reqIn > rate.longContext.thresholdInputTokens;
         const inMul = long ? rate.longContext.inputMultiplier : 1;
@@ -293,8 +300,8 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
 }
 /**
  * Estimate the E2B desktop-minute cost from a host-side create->teardown span (minutes). The rate
- * is injectable. Returns a DECLARED-ABSENT estimate (null + "no_duration") when no duration was
- * measured (no sandbox / unmeasurable span) — never a guessed 0.
+ * is injectable. Returns a declared-absent estimate (null + "no_duration") when no duration was
+ * measured (no sandbox / unmeasurable span), never a guessed 0.
  */
 export function estimateDesktopCost(minutes, rate = DESKTOP_RATE) {
     if (minutes === undefined || !Number.isFinite(minutes) || minutes < 0) {

package/dist/run/projection.d.ts

@@ -8,12 +8,12 @@ export interface LabRollup {
     live: number;
     /** The newest run of this lab, whatever its state. */
     latest?: RunIndexEntry;
-    /** Live runs, newest first — the labs list shows the first one inline. */
+    /** Live runs, newest first; the labs list shows the first one inline. */
     liveRuns: RunIndexEntry[];
 }
 /**
  * Group runs by lab, newest-first within each lab and by recency between labs. Runs with no lab
- * attribution are collected under `unattributed` rather than invented into a lab — the honest
+ * attribution are collected under `unattributed` rather than invented into a study. That is the
  * home for pre-contract runs and library callers.
  */
 export declare function groupRunsByLab(entries: readonly RunIndexEntry[]): {
@@ -35,7 +35,7 @@ export interface LabExpectation {
         max: number;
     };
     medianCostUsd?: number;
-    /** Completed runs whose cost was declared absent — excluded from the median, reported here so
+    /** Completed runs whose cost was declared absent: excluded from the median, reported here so
      *  a partial sample can never masquerade as a full one. */
     costUnknown: number;
 }
@@ -45,7 +45,7 @@ export interface LabExpectation {
  * estimate the operator uses to decide whether to press Start.
  *
  * The mode matters: mixing modes produces a false figure. A dry run spends nothing and
- * takes no time, so a median over nine dry runs and one live one reports that a live run is free —
+ * takes no time, so a median over nine dry runs and one live one reports that a live run is free,
  * next to a control that spends money. Pass the mode the figure is about; omit it only for a
  * summary that is not attached to an action.
  */
@@ -53,7 +53,7 @@ export declare function expectationFor(entries: readonly RunIndexEntry[], mode?:
 /**
  * The one sentence the launch screen shows about time and money, with its denominator attached.
  * A lab with no history says so plainly instead of borrowing another lab's numbers or inventing
- * a range — "no runs yet" is information, and the operator can still press Start.
+ * a range. "No runs yet" is information, and the operator can still press Start.
  */
 export declare function expectationLine(expectation: LabExpectation): string;
 /**
@@ -61,7 +61,7 @@ export declare function expectationLine(expectation: LabExpectation): string;
  *
  * Prefers live figures: cost and duration are what someone reads before spending, and a median
  * diluted by dry runs reports a live study as cheaper and faster than it has ever been. With no
- * live history it reports the count and claims nothing about time or money — which is why this is
+ * live history it reports the count and claims nothing about time or money. That is why this is
  * shared rather than reimplemented per surface, since the two disagreeing is the whole failure.
  */
 export declare function labSummaryLine(row: Pick<LabRow, "runs" | "declared" | "expectation" | "liveExpectation">): string;
@@ -69,7 +69,7 @@ export declare function labSummaryLine(row: Pick<LabRow, "runs" | "declared" | "
 export declare function formatDuration(ms: number): string;
 export interface NormalizedThought {
     lines: string[];
-    /** True when the source text did not fit and was cut — shown, never silent. */
+    /** True when the source text did not fit and was cut; shown, never silent. */
     truncated: boolean;
 }
 /**
@@ -77,7 +77,7 @@ export interface NormalizedThought {
  * arrive with markdown section leads (`**Thinking through setup**`) and hard newlines; a terminal
  * needs plain text wrapped to a line budget.
  *
- * The text is never paraphrased or shortened by meaning — only wrapped, and cut at a word boundary
+ * The text is never paraphrased or shortened by meaning. It is only wrapped, and cut at a word boundary
  * with an ellipsis when it does not fit. `truncated` is how the surface says so.
  */
 export declare function normalizeThought(text: string, options: {
@@ -122,7 +122,7 @@ export interface LabRow {
     /**
      * The shortest label that is unique among the rows it is listed with: the title when no other
      * lab shares it, else the filename, else the full path. A list is only navigable if every row can
-     * be told from every other one, and a title is not guaranteed to be distinct — two manifests in
+     * be told from every other one, and a title is not guaranteed to be distinct: two manifests in
      * this repo carry the same title and the same declared id, differing only by filename.
      */
     label: string;
@@ -139,7 +139,7 @@ export interface LabRow {
     declared: boolean;
     /**
      * How many other manifests declare this same lab id. Above zero, the run history below is shared
-     * between them and cannot be attributed to one file — worth saying, because it is a
+     * between them and cannot be attributed to one file. That is worth saying, because it is a
      * misconfiguration the operator almost certainly does not know about.
      */
     sharesIdWith: number;
@@ -149,7 +149,7 @@ export interface LabRow {
     liveRuns: RunIndexEntry[];
     /** Across every finished run, whatever its mode. A summary, never attached to a spend decision. */
     expectation: LabExpectation;
-    /** Live runs only — the figure that belongs beside anything that spends money. */
+    /** Live runs only: the figure that belongs beside anything that spends money. */
     liveExpectation: LabExpectation;
 }
 export interface DeclaredLab {
@@ -163,16 +163,16 @@ export interface DeclaredLab {
 /**
  * Join declared lab manifests to run history.
  *
- * Neither side alone is the truth. A fresh project has manifests and no runs — those labs are the
+ * Neither side alone is the truth. A fresh project has manifests and no runs, and those labs are the
  * whole screen, and a list built only from history would be empty on exactly the first visit that
  * matters. A long-lived project accumulates runs from labs whose manifest has since been renamed or
- * deleted — that evidence still exists on disk, so dropping those rows would make real runs
+ * deleted. That evidence still exists on disk, so dropping those rows would make real runs
  * unreachable from the surface that is supposed to list them.
  *
  * One row per manifest, not per id. The two are not the same thing: a manifest is addressed by its
  * filename while its runs attribute to the id declared inside it, so several files can legitimately
  * share an id. Collapsing them hides a real file; keying by id duplicates a row with no way to tell
- * the copies apart. Both happen in practice — this repo has exactly that pair.
+ * the copies apart. Both happen in practice: this repo has exactly that pair.
  *
  * Order puts a lab someone is working in first, then labs by how recently they ran, then declared
  * labs that have never run (alphabetically by the displayed label, so the order on screen is the

package/dist/run/projection.js

@@ -1,22 +1,22 @@
-// The disk→view-model projection (#455 PR 2). Pure functions, no I/O, no rendering: this is where
+// The disk→view-model projection. Pure functions, no I/O, no rendering: this is where
 // lab grouping, the trust line's arithmetic, thought normalization and list-window math live, so
 // the parts most likely to be wrong are testable without a terminal.
 //
-// The honesty rules these encode, because they are the ones a UI is most tempted to break:
+// The rules these encode, because they are the ones a UI is most tempted to break:
 //   - a statistic always carries its denominator, and says when it has none;
 //   - an unknown cost is `null` (declared absent), never 0;
 //   - truncation is reported, never silent;
 //   - a participant's reported thinking is quoted, never paraphrased or summarized.
 /**
  * Group runs by lab, newest-first within each lab and by recency between labs. Runs with no lab
- * attribution are collected under `unattributed` rather than invented into a lab — the honest
+ * attribution are collected under `unattributed` rather than invented into a study. That is the
  * home for pre-contract runs and library callers.
  */
 export function groupRunsByLab(entries) {
     const byLab = new Map();
     const unattributed = [];
     for (const entry of entries) {
-        const labId = entry.lab?.id;
+        const labId = entry.study?.id;
         if (labId === undefined) {
             unattributed.push(entry);
             continue;
@@ -63,7 +63,7 @@ function recencyOf(entry) {
  * estimate the operator uses to decide whether to press Start.
  *
  * The mode matters: mixing modes produces a false figure. A dry run spends nothing and
- * takes no time, so a median over nine dry runs and one live one reports that a live run is free —
+ * takes no time, so a median over nine dry runs and one live one reports that a live run is free,
  * next to a control that spends money. Pass the mode the figure is about; omit it only for a
  * summary that is not attached to an action.
  */
@@ -79,7 +79,7 @@ export function expectationFor(entries, mode) {
         .filter((value) => typeof value === "number" && Number.isFinite(value))
         .sort((a, b) => a - b);
     // A cost is unknown whether it was declared absent (`null`) or never recorded at all
-    // (`undefined` — every fail-closed exit finalized with no outcome). Counting only the first
+    // (`undefined`: every fail-closed exit finalized with no outcome). Counting only the first
     // reports "~$1.20 median · 3 runs" for a sample where two runs were never priced, which claims a
     // denominator the figure does not have.
     const costUnknown = finished.filter((entry) => entry.estimatedCostUsd === null || entry.estimatedCostUsd === undefined).length;
@@ -104,7 +104,7 @@ function median(sorted) {
 /**
  * The one sentence the launch screen shows about time and money, with its denominator attached.
  * A lab with no history says so plainly instead of borrowing another lab's numbers or inventing
- * a range — "no runs yet" is information, and the operator can still press Start.
+ * a range. "No runs yet" is information, and the operator can still press Start.
  */
 export function expectationLine(expectation) {
     if (expectation.sample === 0)
@@ -136,7 +136,7 @@ export function expectationLine(expectation) {
  *
  * Prefers live figures: cost and duration are what someone reads before spending, and a median
  * diluted by dry runs reports a live study as cheaper and faster than it has ever been. With no
- * live history it reports the count and claims nothing about time or money — which is why this is
+ * live history it reports the count and claims nothing about time or money. That is why this is
  * shared rather than reimplemented per surface, since the two disagreeing is the whole failure.
  */
 export function labSummaryLine(row) {
@@ -162,7 +162,7 @@ export function formatDuration(ms) {
  * arrive with markdown section leads (`**Thinking through setup**`) and hard newlines; a terminal
  * needs plain text wrapped to a line budget.
  *
- * The text is never paraphrased or shortened by meaning — only wrapped, and cut at a word boundary
+ * The text is never paraphrased or shortened by meaning. It is only wrapped, and cut at a word boundary
  * with an ellipsis when it does not fit. `truncated` is how the surface says so.
  */
 export function normalizeThought(text, options) {
@@ -247,16 +247,16 @@ function labNameFromPath(manifestPath) {
 /**
  * Join declared lab manifests to run history.
  *
- * Neither side alone is the truth. A fresh project has manifests and no runs — those labs are the
+ * Neither side alone is the truth. A fresh project has manifests and no runs, and those labs are the
  * whole screen, and a list built only from history would be empty on exactly the first visit that
  * matters. A long-lived project accumulates runs from labs whose manifest has since been renamed or
- * deleted — that evidence still exists on disk, so dropping those rows would make real runs
+ * deleted. That evidence still exists on disk, so dropping those rows would make real runs
  * unreachable from the surface that is supposed to list them.
  *
  * One row per manifest, not per id. The two are not the same thing: a manifest is addressed by its
  * filename while its runs attribute to the id declared inside it, so several files can legitimately
  * share an id. Collapsing them hides a real file; keying by id duplicates a row with no way to tell
- * the copies apart. Both happen in practice — this repo has exactly that pair.
+ * the copies apart. Both happen in practice: this repo has exactly that pair.
  *
  * Order puts a lab someone is working in first, then labs by how recently they ran, then declared
  * labs that have never run (alphabetically by the displayed label, so the order on screen is the
@@ -267,7 +267,7 @@ export function labRows(declared, entries) {
     const byId = new Map(labs.map((lab) => [lab.labId, lab]));
     const runsOf = new Map();
     for (const entry of entries) {
-        const labId = entry.lab?.id;
+        const labId = entry.study?.id;
         if (labId === undefined)
             continue;
         const bucket = runsOf.get(labId);
@@ -332,8 +332,8 @@ export function labRows(declared, entries) {
 /**
  * Give every row the shortest label that distinguishes it: title, else filename, else path.
  *
- * Falling straight back to the filename whenever a title repeats — rather than decorating the
- * duplicate with a suffix — keeps the label something the operator can act on, because the filename
+ * Falling straight back to the filename whenever a title repeats, instead of decorating the
+ * duplicate with a suffix, keeps the label something the operator can act on, because the filename
  * is exactly what `humanish lab run` takes.
  */
 function assignLabels(rows) {

package/dist/run/reclaim.js

@@ -49,8 +49,8 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
     const runId = runIdOf(runPaths);
     const journal = await reclaimJournal(runPaths, hooks);
     if (journal.kind === "empty") {
-        // Honest empty: nothing journaled means either no sandbox was ever created (cheap interrupt —
-        // nothing to reclaim) or the run predates receipts (0.35.x and earlier — the create-time TTL
+        // Empty: nothing journaled means either no sandbox was ever created (cheap interrupt:
+        // nothing to reclaim) or the run predates receipts (0.35.x and earlier, where the create-time TTL
         // is the only backstop for those). Either way there is no id to act on, and saying so beats
         // pretending a scan happened.
         warnings.push("No sandbox-receipts.ndjson in this run dir: either no sandbox was created before the interrupt, or the run predates create-time receipts. Nothing to reclaim by id; server-side kill-on-timeout covers anything that did exist.");

package/dist/run/results.d.ts

@@ -1,14 +1,14 @@
 import type { ObserverResult } from "../observer/render.js";
 import type { RunProviderResource } from "./bundle.js";
-import type { RunLabProvenance } from "./status.js";
+import type { RunStudyProvenance } from "./study-provenance.js";
 export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
 export interface RunOptions {
-    /** Which manifest produced this run (#455). */
-    lab?: RunLabProvenance;
+    /** Which manifest produced this run. */
+    lab?: RunStudyProvenance;
     cwd: string;
     dryRun?: boolean;
     runId?: string;
-    simCount?: number;
+    participantCount?: number;
     /** Render the run's Observer through the finished run, opening the page when `open` is true.
      *  Without it the preview writes no observer/index.html. */
     observer?: {
@@ -30,7 +30,7 @@ export interface RunResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_ANALYSIS_UNSUPPORTED" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_LAB_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_APP_URL_REMOVED" | "HUMANISH_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
         message: string;
     };
 }

package/dist/run/run-index.d.ts

@@ -1,4 +1,5 @@
-import { type RunLabProvenance, type RunLiveness, type RunStatusRecord } from "./status.js";
+import { type RunLiveness, type RunStatusRecord } from "./status.js";
+import { type RunStudyProvenance } from "./study-provenance.js";
 declare const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
 export interface RunIndexEntry {
     runId: string;
@@ -12,7 +13,7 @@ export interface RunIndexEntry {
      * one run's record carries that pid.
      */
     pid?: number;
-    lab?: RunLabProvenance;
+    study?: RunStudyProvenance;
     startedAt?: string;
     updatedAt?: string;
     completedAt?: string;
@@ -31,7 +32,7 @@ export interface RunIndexResult {
     cwd: string;
     /** Newest first, by the best timestamp each entry has. */
     runs: RunIndexEntry[];
-    /** Directories that could not be read at all, by name — surfaced, never silently dropped. */
+    /** Directories that could not be read at all, by name: surfaced, never silently dropped. */
     unreadable: string[];
 }
 /** What a cached entry was derived from, so a changed file invalidates exactly that entry. */
@@ -59,7 +60,8 @@ interface BundleFacts {
     runId?: string;
     mode?: string;
     createdAt?: string;
-    lab?: RunLabProvenance;
+    study?: unknown;
+    lab?: unknown;
     persona?: {
         source?: string;
     };
@@ -95,8 +97,8 @@ export interface ReadRunIndexOptions {
     cache?: RunIndexCache;
     /** Injectable clock, so liveness classification is reproducible in tests. */
     nowMs?: number;
-    /** Cap the number of runs returned (newest first). The full directory is still enumerated —
-     *  a cap on reads, not on truth — and the count reflects what was read. */
+    /** Cap the number of runs returned (newest first). The full directory is still enumerated;
+     *  the cap limits reads, and the count reflects what was read. */
     limit?: number;
 }
 /**