humanish 0.106.1 → 0.108.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,17 +35,17 @@ 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;
 }
 /**
- * Derive what to expect from a lab's own history. Only FINISHED runs count: an interrupted run's
+ * Derive what to expect from a lab's own history. Only finished runs count: an interrupted run's
  * duration is the length of an accident, not of a study, and including it would quietly bias the
  * estimate the operator uses to decide whether to press Start.
  *
- * MODE MATTERS, and mixing modes is a lie rather than an imprecision. 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 —
+ * 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,
  * 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,15 +53,15 @@ 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;
 /**
  * The one line a lab may say about itself, wherever it is shown.
  *
- * Prefers LIVE figures: cost and duration are what someone reads before spending, and a median
+ * 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: {
@@ -104,15 +104,15 @@ export declare function livenessLabel(entry: Pick<RunIndexEntry, "liveness" | "v
 /** A lab as the labs list shows it: what is declared, joined to what actually happened. */
 export interface LabRow {
     /**
-     * Stable identity for THIS ROW. A manifest's path when it has one, else the lab id — because two
+     * Stable identity for this row. A manifest's path when it has one, else the lab id, because two
      * manifests can declare the same id, and keying rows by id makes them collapse into a pair of
      * indistinguishable duplicates.
      */
     key: string;
-    /** The declared id. Run history attributes to this, so it is NOT unique across manifests. */
+    /** The declared id. Run history attributes to this, so it is not unique across manifests. */
     labId: string;
     /**
-     * The handle an operator would actually type. Lab resolution is by FILENAME, so the manifest
+     * The handle an operator would actually type. Lab resolution is by filename, so the manifest
      * `\`.humanish/labs/persona-contrast-live.yaml\`` is reached as `persona-contrast-live` even when
      * the id inside it says something else.
      */
@@ -120,26 +120,26 @@ export interface LabRow {
     /** The manifest's own title, when it has one. */
     title?: string;
     /**
-     * The shortest label that is UNIQUE among the rows it is listed with: the title when no other
+     * 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
-     * this repo carry the same title AND the same declared id, differing only by filename.
+     * 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;
-    /** The manifest's own words, for the list to say what this study IS. */
+    /** The manifest's own words, for the list to say what this study is. */
     description?: string;
     /** Repo-relative manifest path, absent for a lab known only from run history. */
     path?: string;
     origin?: "committed" | "ignored" | "explicit";
     /**
-     * False for a lab that has runs but NO manifest here — renamed, deleted, or run from a path that
+     * False for a lab that has runs but no manifest here: renamed, deleted, or run from a path that
      * is gone. Its runs are still evidence and must stay reachable, so it is listed and marked rather
      * than dropped.
      */
     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
+     * 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. 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,19 +163,19 @@ 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
+ * 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 WHAT IS DISPLAYED, so the order on screen is the
+ * labs that have never run (alphabetically by the displayed label, so the order on screen is the
  * order a reader can predict), then labs known only from history.
  */
 export declare function labRows(declared: readonly DeclaredLab[], entries: readonly RunIndexEntry[]): {

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:
-//   - a statistic ALWAYS carries its denominator, and says when it has none;
+// 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;
@@ -58,12 +58,12 @@ function recencyOf(entry) {
     return 0;
 }
 /**
- * Derive what to expect from a lab's own history. Only FINISHED runs count: an interrupted run's
+ * Derive what to expect from a lab's own history. Only finished runs count: an interrupted run's
  * duration is the length of an accident, not of a study, and including it would quietly bias the
  * estimate the operator uses to decide whether to press Start.
  *
- * MODE MATTERS, and mixing modes is a lie rather than an imprecision. 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 —
+ * 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,
  * 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.
  */
@@ -78,8 +78,8 @@ export function expectationFor(entries, mode) {
         .map((entry) => entry.estimatedCostUsd)
         .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
+    // 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
     // 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)
@@ -134,9 +134,9 @@ export function expectationLine(expectation) {
 /**
  * The one line a lab may say about itself, wherever it is shown.
  *
- * Prefers LIVE figures: cost and duration are what someone reads before spending, and a median
+ * 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,19 +247,19 @@ 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
+ * 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 WHAT IS DISPLAYED, so the order on screen is the
+ * labs that have never run (alphabetically by the displayed label, so the order on screen is the
  * order a reader can predict), then labs known only from history.
  */
 export function labRows(declared, entries) {
@@ -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);
@@ -310,7 +310,7 @@ export function labRows(declared, entries) {
             .filter((lab) => !declaredIds.has(lab.labId))
             .map((lab) => build(lab.labId, undefined, false)),
     ];
-    // Resolve each row's label BEFORE sorting, so the list is ordered by what a reader actually sees.
+    // Resolve each row's label before sorting, so the list is ordered by what a reader actually sees.
     assignLabels(rows);
     const label = (row) => row.label;
     rows.sort((left, right) => {
@@ -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.d.ts

@@ -1,4 +1,5 @@
 import { type E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { type PreparedRunArtifactPaths } from "./paths.js";
 declare const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
 export declare const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
 interface ReclaimOutcome {
@@ -31,6 +32,11 @@ export interface ReclaimHooks {
     requestTimeoutMs?: number;
 }
 export declare function reclaimRunSandboxes(cwd: string, runInput: string, hooks?: ReclaimHooks): Promise<ReclaimResult>;
+/**
+ * Reclaim the run whose directory the caller already holds. Nothing is resolved, so an id that is
+ * also an alias (a run named `latest`) cannot reach another run's receipts.
+ */
+export declare function reclaimPinnedRunSandboxes(cwd: string, runPaths: PreparedRunArtifactPaths, hooks?: ReclaimHooks): Promise<ReclaimResult>;
 /**
  * Kill the sandboxes left by interrupted `humanish lab preflight` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left

package/dist/run/reclaim.js

@@ -1,4 +1,4 @@
-// `humanish reclaim`: kill an interrupted run's sandboxes by the EXACT ids the run journaled at
+// `humanish reclaim`: kill an interrupted run's sandboxes by the exact ids the run journaled at
 // create time (sandbox-receipts.ndjson), and report what happened to each. It reads one file inside
 // the managed run dir, kills by id, and never lists the account: an account-wide operation once
 // destroyed unrelated infrastructure. Without it, orphaned sandboxes run until the server-side
@@ -13,7 +13,17 @@ import { redactText, toErrorMessage } from "../evidence/redaction.js";
 import { runIdOf } from "./paths.js";
 const RECLAIM_RESULT_SCHEMA = "humanish.reclaim-result.v1";
 export const RECLAIM_RECEIPT_ARTIFACT = "reclaim-receipt.json";
-export async function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
+export function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
+    return reclaimRun(cwd, runInput, () => resolveRunPath(cwd, runInput), hooks);
+}
+/**
+ * Reclaim the run whose directory the caller already holds. Nothing is resolved, so an id that is
+ * also an alias (a run named `latest`) cannot reach another run's receipts.
+ */
+export function reclaimPinnedRunSandboxes(cwd, runPaths, hooks = {}) {
+    return reclaimRun(cwd, runIdOf(runPaths), () => Promise.resolve(runPaths), hooks);
+}
+async function reclaimRun(cwd, runInput, locate, hooks) {
     const warnings = [];
     const base = {
         schema: RECLAIM_RESULT_SCHEMA,
@@ -25,7 +35,7 @@ export async function reclaimRunSandboxes(cwd, runInput, hooks = {}) {
     };
     if (e2bDebugMode())
         return { ...base, ok: false, error: E2B_DEBUG_REFUSAL };
-    const runPaths = await resolveRunPath(cwd, runInput);
+    const runPaths = await locate();
     if (!runPaths) {
         return {
             ...base,
@@ -39,8 +49,8 @@ export async function reclaimRunSandboxes(cwd, runInput, 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_CONFLICT" | "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;
@@ -7,12 +8,12 @@ export interface RunIndexEntry {
     liveness: RunLiveness;
     mode?: "dry-run" | "live";
     /**
-     * The pid that owns a run, when it recorded one. This is how a surface identifies the run IT just
+     * The pid that owns a run, when it recorded one. This is how a surface identifies the run it just
      * started without minting an id or guessing at a new directory: it spawned a process, and exactly
      * 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;
 }
 /**

package/dist/run/run-index.js

@@ -1,21 +1,22 @@
-// The run index (#455 PR 2): list and classify every run in a project WITHOUT parsing bundles.
+// The run index: list and classify every run in a project without parsing bundles.
 //
-// The existing `listRuns` walks each run tree — screenshots included — validating symlinks and
+// The existing `listRuns` walks each run tree, screenshots included, validating symlinks and
 // then parses each `run.json`: measured 197ms cold / 152ms warm at 25 runs. That is fine for a
 // command that prints once and exits, and much too hot for a surface that refreshes on a cadence
 // over SSH. This module reads the small `status.json` record each run now writes (586 bytes beside
 // a 92KB bundle) and caches per-run entries keyed on the stat of the file each was derived from.
 //
-// HONESTY RULES, unchanged from the record itself:
+// Rules, unchanged from the record itself:
 //   - `run.json` is the evidence-of-record. Every field here is a projection for listing and
 //     classification; nothing here is a claim about what a participant did.
-//   - A run with no status record is NOT assumed finished. It is classified from what is on disk:
-//     a bundle means finished, receipts without a bundle mean interrupted. That is the honest
-//     reading of a run whose process died — and, before this contract existed, of every run.
+//   - A run with no status record is not assumed finished. It is classified from what is on disk:
+//     a bundle means finished, receipts without a bundle mean interrupted. That is the
+//     reading of a run whose process died (and, before this contract existed, of every run).
 //   - One unreadable run directory degrades that run, never the listing.
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { RUN_STATUS_FILE, classifyRunStatus, inferLegacyLabId, isRunStatusRecord, } from "./status.js";
+import { RUN_STATUS_FILE, classifyRunStatus, isRunStatusRecord, } from "./status.js";
+import { studyProvenanceOf } from "./study-provenance.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 const RUN_INDEX_SCHEMA = "humanish.run-index.v1";
 /**
@@ -78,7 +79,7 @@ function entryFromStatus(record, nowMs) {
         liveness: classifyRunStatus(record, nowMs),
         mode: record.mode,
         ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
-        ...(record.lab === undefined ? {} : { lab: record.lab }),
+        ...studyEntry(studyProvenanceOf(record)),
         startedAt: record.startedAt,
         updatedAt: record.updatedAt,
         ...(record.completedAt === undefined ? {} : { completedAt: record.completedAt }),
@@ -97,10 +98,10 @@ function usableStatusRecord(raw, runId) {
     return isRunStatusRecord(raw) && raw.runId === runId;
 }
 /**
- * The bundle-only reading, for a run with no usable status record. A bundle on disk USUALLY means
- * the run reached its final write. But a live run now flushes an IN-PROGRESS bundle as it goes (so
+ * The bundle-only reading, for a run with no usable status record. A bundle on disk usually means
+ * the run reached its final write. But a live run now flushes an in-progress bundle as it goes (so
  * anything asking what a participant is doing has something to read), and that bundle marks its
- * simulations `running`. With no status record there is no freshness to judge, and the honest
+ * simulations `running`. With no status record there is no freshness to judge, and the
  * reading of "it started, and nothing here says it finished" is interrupted, not finished.
  */
 function bundleLiveness(bundle) {
@@ -117,18 +118,16 @@ export function runLiveness(runId, status, bundle, nowMs) {
         ? { liveness: classifyRunStatus(status, nowMs), record: status }
         : { liveness: bundleLiveness(bundle) };
 }
+function studyEntry(study) {
+    return study === undefined ? {} : { study };
+}
 function entryFromBundle(runId, bundle) {
-    const legacyLabId = bundle.lab === undefined ? inferLegacyLabId(bundle) : undefined;
     return {
         runId,
         derivedFrom: "bundle",
         liveness: bundleLiveness(bundle),
         ...(bundle.mode === "dry-run" || bundle.mode === "live" ? { mode: bundle.mode } : {}),
-        ...(bundle.lab !== undefined
-            ? { lab: bundle.lab }
-            : legacyLabId === undefined
-                ? {}
-                : { lab: { id: legacyLabId } }),
+        ...studyEntry(studyProvenanceOf(bundle)),
         ...(bundle.createdAt === undefined ? {} : { startedAt: bundle.createdAt }),
         ...(bundle.review?.verdict === undefined ? {} : { verdict: bundle.review.verdict }),
         ...(bundle.review?.participants === undefined
@@ -169,15 +168,15 @@ export async function readRunIndex(cwdInput, options = {}) {
         if (statusKey !== null) {
             const cached = cache?.get(runId, statusKey);
             if (cached !== undefined) {
-                // Liveness is time-dependent, so it is recomputed even on a cache hit — a record that has
-                // not changed can still have gone stale since the last read.
-                runs.push(cached.derivedFrom === "status" && cached.updatedAt !== undefined
+                // A running record's liveness is time-dependent, so it is recomputed even on a cache hit:
+                // an unchanged record can still have gone stale. An ended record (finished or
+                // interrupted, both with completedAt) keeps the liveness it was cached with.
+                runs.push(cached.derivedFrom === "status" &&
+                    cached.updatedAt !== undefined &&
+                    cached.completedAt === undefined
                     ? {
                         ...cached,
-                        liveness: classifyRunStatus({
-                            state: cached.completedAt === undefined ? "running" : "finished",
-                            updatedAt: cached.updatedAt,
-                        }, nowMs),
+                        liveness: classifyRunStatus({ state: "running", updatedAt: cached.updatedAt }, nowMs),
                     }
                     : cached);
                 continue;
@@ -210,7 +209,7 @@ export async function readRunIndex(cwdInput, options = {}) {
             continue;
         }
         // Neither record nor bundle: receipts without an outcome. That is precisely an interrupted
-        // run — the shape a dropped connection leaves — and saying so is more useful than hiding it.
+        // run (the shape a dropped connection leaves), and saying so is more useful than hiding it.
         runs.push({ runId, derivedFrom: "directory", liveness: "interrupted" });
     }
     cache?.retain(runIds);

package/dist/run/run-not-found.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The message for a run that is not there: how to start one when the project has no runs, or how
+ * to list them when it has. Only the runs directory's entry names are read.
+ */
+export declare function runNotFoundMessage(cwdInput: string, runInput: string): Promise<string>;

package/dist/run/run-not-found.js

@@ -0,0 +1,15 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveRunsRoot } from "./paths.js";
+/**
+ * The message for a run that is not there: how to start one when the project has no runs, or how
+ * to list them when it has. Only the runs directory's entry names are read.
+ */
+export async function runNotFoundMessage(cwdInput, runInput) {
+    const cwd = path.resolve(cwdInput);
+    const entries = await readdir(resolveRunsRoot(cwd)).catch(() => []);
+    const hasRun = entries.some((name) => !name.startsWith(".") && !name.endsWith(".json"));
+    return hasRun
+        ? `No run ${runInput}; humanish runs lists them.`
+        : `No runs in ${cwd} yet; start one with humanish run first-run.`;
+}

package/dist/run/run.d.ts

@@ -2,7 +2,8 @@ import { renderObserver, type ObserverResult } from "../observer/render.js";
 import { type RunBundle } from "./bundle.js";
 import type { ExecutionOutcome } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
-import { type RunLabProvenance, type RunStatusHandle } from "./status.js";
+import { type RunStatusHandle } from "./status.js";
+import type { RunStudyProvenance } from "./study-provenance.js";
 interface StartRunOptions {
     /** Project directory, in the form the route resolved it. */
     cwd: string;
@@ -10,10 +11,10 @@ interface StartRunOptions {
     runId?: string | undefined;
     mintRunId: () => string;
     mode: "dry-run" | "live";
-    lab?: RunLabProvenance | undefined;
+    lab?: RunStudyProvenance | undefined;
     /** review.md for the published bundle. */
     renderReview: (bundle: RunBundle) => string;
-    /** Used by `FinishedRun.renderObserver`; `render` is the routes' `renderObserverFn` seam. */
+    /** Used by `FinishedRun.renderObserver`; `render` is the `LabDeps.renderObserver` seam. */
     observer?: {
         open: boolean;
         render?: typeof renderObserver | undefined;
@@ -25,7 +26,9 @@ interface Run {
     readonly runId: string;
     readonly createdAt: string;
     readonly mode: "dry-run" | "live";
-    /** Routes write their evidence files through these and hand them to lanes. */
+    /** The manifest the run came from; bundleHead copies it into the bundle. */
+    readonly lab?: RunStudyProvenance;
+    /** Routes write their evidence files through these and hand them to participants. */
     readonly paths: PreparedRunArtifactPaths;
     /**
      * Publish an in-progress bundle: run.json, review.json, review.md, events.ndjson and