humanish 0.107.0 → 0.108.0

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.
+ * 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
@@ -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, written beside it until 0.109. */
+    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 lab 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,8 +526,8 @@ 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 lab?: RunStudyProvenance | undefined;
 }
 /**
  * The fields every run bundle starts with, in the saved order. The run supplies its id, mode,
@@ -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" | "lab" | "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";
@@ -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.lab),
         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.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);

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) {

package/dist/run/dry-run-inputs.js

@@ -12,7 +12,7 @@ const builtinPersona = {
 const builtinScenario = {
     id: "builtin-first-run-smoke",
     title: "Built-in First-Run Smoke",
-    goal: "Create a public-safe dry-run contract bundle from built-in defaults.",
+    goal: "Write a public-safe dry-run bundle from built-in defaults.",
     source: "builtin:first-run-smoke",
     sourceDigest: "builtin",
 };

package/dist/run/dry-run.js

@@ -9,7 +9,7 @@ import {} from "./streams.js";
 import { participantEvent, participantIdsOf, participantRecord, participantStream, } from "./participant-records.js";
 import { implicitProjectDirectoryExists, readPackageName, validateCwd } from "./project.js";
 import { loadDryRunInputs } from "./dry-run-inputs.js";
-import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk } from "./judge.js";
+import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk, verdictText, } from "./judge.js";
 /**
  * The preview route's run. The run scope closes the run it started on every exit, including
  * the fail-closed ones. It renders an Observer only when `options.observer` asks for one.
@@ -33,10 +33,10 @@ async function runDryRunInScope(options, scope) {
     const warnings = [];
     if (cwdError)
         return refused(requestedCwd, warnings, cwdError);
-    const participants = normalizeParticipantCount(options.simCount);
+    const participants = normalizeParticipantCount(options.participantCount);
     if (participants === null) {
         return refused(requestedCwd, warnings, {
-            code: "HUMANISH_INVALID_SIM_COUNT",
+            code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
             message: "--count must be a positive integer.",
         });
     }
@@ -48,7 +48,7 @@ async function runDryRunInScope(options, scope) {
     if (!options.dryRun) {
         return refused(requestedCwd, warnings, {
             code: "HUMANISH_LIVE_RUN_UNIMPLEMENTED",
-            message: "Only run --dry-run is implemented here. Run a lab for a live study.",
+            message: "humanish run needs a study. List studies with humanish study list, or run humanish run --dry-run for a sample bundle.",
         });
     }
     const createdAt = new Date().toISOString();
@@ -94,7 +94,7 @@ async function runDryRunInScope(options, scope) {
             {
                 at: createdAt,
                 event: "run.created",
-                message: `Synthetic dry-run contract bundle created with ${participants} simulated participant${participants === 1 ? "" : "s"}.`,
+                message: `Synthetic dry-run bundle created with ${participants} simulated participant${participants === 1 ? "" : "s"}.`,
             },
             {
                 at: createdAt,
@@ -117,7 +117,7 @@ async function runDryRunInScope(options, scope) {
         events: observerFixtures.events,
         redaction: {
             status: "passed",
-            notes: "Dry-run bundle contains synthetic contract proof only.",
+            notes: "Dry-run bundle: synthetic data only, nothing from a product.",
         },
         artifacts: bundleArtifacts(),
         review: createReviewSummary(judgment.verdict),
@@ -150,14 +150,14 @@ async function runDryRunInScope(options, scope) {
     };
 }
 /**
- * The preview's review, with the verdict judgePreview gave it. It claims artifact plumbing only,
- * never product behavior.
+ * The preview's review, with the verdict judgePreview gave it. It claims only that the run's
+ * files were written, never product behavior.
  */
 function createReviewSummary(verdict) {
     return {
         schema: REVIEW_SCHEMA,
         verdict,
-        summary: "Synthetic dry-run bundle was generated. This proves humanish artifact plumbing, not product behavior.",
+        summary: "Dry run: humanish wrote a synthetic run bundle. No product behavior was tested.",
         gaps: [
             "No browser was launched.",
             "No product state was verified.",
@@ -173,7 +173,7 @@ Run: ${bundle.runId}
 
 Mode: ${bundle.mode}
 
-Verdict: ${bundle.review.verdict}
+Verdict: ${verdictText(bundle.review.verdict, bundle.mode)}
 
 ${bundle.review.summary}
 
@@ -210,7 +210,7 @@ const SYNTHETIC_STREAM_TEMPLATES = [
         kind: "ui",
         mode: "browser-sim",
         label: "UI journey",
-        currentStep: "Route and viewport contract captured",
+        currentStep: "Route and viewport recorded",
         summary: "Simulated browser participant reserved for VNC playback, screenshots, route state, and interaction trace.",
         tail: "open target app\nresolve first-run route\ncapture viewport state\nrecord interaction trace",
         viewport: { width: 1440, height: 960, deviceScaleFactor: 1 },
@@ -219,19 +219,19 @@ const SYNTHETIC_STREAM_TEMPLATES = [
         kind: "terminal",
         mode: "cli-sim",
         label: "CLI actor",
-        currentStep: "Command transcript contract captured",
+        currentStep: "Command transcript recorded",
         summary: "Simulated CLI participant reserved for command-by-command persona runs with stdout/stderr and artifact links.",
         // Every command in a shipped sample tail must be one the CLI actually accepts: participants
         // read and run them. tests/surface/shipped-command-strings.test.ts checks this against the
         // command table.
-        tail: "$ humanish doctor\nok target cwd\nok humanish source\n$ humanish run first-run\ncontract proof emitted",
+        tail: "$ humanish doctor\nok target cwd\nok humanish source\n$ humanish run first-run\nhumanish run dry-run",
         viewport: undefined,
     },
     {
         kind: "tui",
         mode: "tui-sim",
         label: "TUI actor",
-        currentStep: "Terminal UI frame contract captured",
+        currentStep: "Terminal UI frame recorded",
         summary: "Simulated TUI participant reserved for PTY bytes, ANSI rendering, focus replay, and optional assisted attach.",
         tail: "\u001b[2mhumanish TUI frame\u001b[0m\n> persona: skeptical-power-user\n> scenario: onboarding-regression\nstatus: awaiting live PTY transport",
         viewport: undefined,
@@ -240,9 +240,9 @@ const SYNTHETIC_STREAM_TEMPLATES = [
         kind: "codex-ui",
         mode: "codex-app-sim",
         label: "Codex UI",
-        currentStep: "App-server embed contract captured",
+        currentStep: "App-server embed recorded",
         summary: "Simulated Codex UI participant reserved for app-server sessions that can be watched beside terminal evidence.",
-        tail: "codex-app-server session contract\nstate: not_connected\nembed: pending provider URL\nreceipts: planned",
+        tail: "codex-app-server session (dry run)\nstate: not_connected\nembed: pending provider URL\nreceipts: planned",
         viewport: { width: 1280, height: 900, deviceScaleFactor: 1 },
     },
 ];
@@ -255,7 +255,7 @@ function buildSyntheticObserverFixtures(args) {
             at: args.createdAt,
             level: "info",
             type: "observer.contract.created",
-            message: "Created public-safe observer stream contract.",
+            message: "Created the public-safe Observer streams.",
         },
     ];
     for (let index = 0; index < args.count; index += 1) {
@@ -324,7 +324,7 @@ function buildSyntheticObserverFixtures(args) {
             at: args.createdAt,
             level: "info",
             type: "sim.contract.ready",
-            message: `${template.label} stream contract ready.`,
+            message: `${template.label} stream ready.`,
         }), participantEvent(ids, {
             id: `event-${String(index + 1).padStart(3, "0")}-b`,
             at: args.createdAt,