humanish 0.106.1 → 0.108.0

package/dist/run/stats.js

@@ -3,14 +3,12 @@
 // counts as unknown and never as zero, and every rate has a denominator next to it.
 import path from "node:path";
 import { readRunIndex } from "./run-index.js";
-import { addStudyCosts, emptyStudyCosts, readStudyCosts, } from "./costs.js";
+import { addCostTotals, emptyCostTotals, readCostTotals, } from "./costs.js";
 import { round6 } from "./pricing.js";
-const STATS_SCHEMA = "humanish.stats.v1";
-const STATS_NOTE = "Every dollar figure is a retained rate-table estimate, never a provider charge. " +
-    "Known spend includes participant/desktop estimates and all distinct recorded analysis attempts; reuse is counted once. " +
-    "Unknown amounts are excluded, not $0. Missing historical attempts cannot be reconstructed. " +
-    "Analysis is attributed to its run's start date, including later reruns. " +
-    "JSON estimatedSpendUsd and medianCostUsd retain their participant/desktop-only meaning; costs includes analysis.";
+import { plural } from "./text.js";
+const STATS_SCHEMA = "humanish.stats.v2";
+// docs/contracts/study-costs.md holds the accounting rules this sentence summarizes.
+const STATS_NOTE = "Dollar figures are estimates from humanish's rate table, never provider charges, and a cost humanish does not know is left out of every total.";
 function median(values) {
     if (values.length === 0)
         return undefined;
@@ -28,15 +26,26 @@ function addParticipants(into, entry) {
     into.reachedGoal += entry.participants.reachedGoal;
     into.reportedFriction += entry.participants.reportedFriction ?? 0;
 }
+/**
+ * A run's participant and desktop estimate: its recorded figure, or $0 for a dry run that records
+ * none, since a dry run makes no model request and creates no desktop. Undefined when the cost is
+ * unknown, including a dry run that records an unknown (null) figure.
+ */
+function runEstimateUsd(entry) {
+    const usd = entry.estimatedCostUsd;
+    if (typeof usd === "number" && Number.isFinite(usd) && usd >= 0)
+        return usd;
+    return usd === undefined && entry.mode === "dry-run" ? 0 : undefined;
+}
 function entryTime(entry) {
     return entry.startedAt ?? entry.completedAt ?? entry.updatedAt;
 }
-function addToLabRow(labs, entry, priced, costs) {
-    const labId = entry.lab?.id ?? "(no lab)";
+function addToLabRow(labs, entry, runUsd, costs) {
+    const labId = entry.study?.id ?? "(no study)";
     let row = labs.get(labId);
     if (row === undefined) {
         row = {
-            lab: labId,
+            study: labId,
             runs: 0,
             live: 0,
             dryRun: 0,
@@ -47,7 +56,7 @@ function addToLabRow(labs, entry, priced, costs) {
             unpricedRuns: 0,
             participants: emptyParticipants(),
             durations: [],
-            costs: emptyStudyCosts(),
+            costs: emptyCostTotals(),
             runCosts: [],
         };
         labs.set(labId, row);
@@ -64,14 +73,14 @@ function addToLabRow(labs, entry, priced, costs) {
     }
     if (entry.mode === "live" && entry.durationMs !== undefined)
         row.durations.push(entry.durationMs);
-    if (priced)
-        row.runCosts.push(entry.estimatedCostUsd);
-    else
+    if (runUsd === undefined)
         row.unpricedRuns += 1;
+    else
+        row.runCosts.push(runUsd);
     addParticipants(row.participants, entry);
-    addStudyCosts(row.costs, costs);
+    addCostTotals(row.costs, costs);
 }
-function addToDayRow(days, entry, priced, costs) {
+function addToDayRow(days, entry, runUsd, costs) {
     const at = entryTime(entry);
     const day = at === undefined ? "(undated)" : at.slice(0, 10);
     let dayRow = days.get(day);
@@ -82,18 +91,18 @@ function addToDayRow(days, entry, priced, costs) {
             live: 0,
             estimatedSpendUsd: 0,
             unpricedRuns: 0,
-            costs: emptyStudyCosts(),
+            costs: emptyCostTotals(),
         };
         days.set(day, dayRow);
     }
     dayRow.runs += 1;
     if (entry.mode === "live")
         dayRow.live += 1;
-    if (priced)
-        dayRow.estimatedSpendUsd += entry.estimatedCostUsd;
-    else
+    if (runUsd === undefined)
         dayRow.unpricedRuns += 1;
-    addStudyCosts(dayRow.costs, costs);
+    else
+        dayRow.estimatedSpendUsd += runUsd;
+    addCostTotals(dayRow.costs, costs);
 }
 export async function computeStats(cwdInput, options = {}) {
     const cwd = path.resolve(cwdInput);
@@ -127,7 +136,7 @@ export async function computeStats(cwdInput, options = {}) {
         })),
     ];
     const selected = entries.filter((entry) => {
-        if (options.lab !== undefined && entry.lab?.id !== options.lab)
+        if (options.lab !== undefined && entry.study?.id !== options.lab)
             return false;
         if (sinceMs !== undefined) {
             const at = entryTime(entry);
@@ -148,15 +157,15 @@ export async function computeStats(cwdInput, options = {}) {
         unpricedRuns: 0,
         participants: emptyParticipants(),
         verdicts: {},
-        costs: emptyStudyCosts(),
+        costs: emptyCostTotals(),
     };
     const labs = new Map();
     const days = new Map();
     const costsByRun = [];
     for (const entry of selected) {
-        const accounting = await readStudyCosts(cwd, entry);
+        const accounting = await readCostTotals(cwd, entry);
         costsByRun.push(accounting);
-        addStudyCosts(totals.costs, accounting.costs);
+        addCostTotals(totals.costs, accounting.costs);
         totals.runs += 1;
         if (entry.mode === "live")
             totals.live += 1;
@@ -164,18 +173,16 @@ export async function computeStats(cwdInput, options = {}) {
             totals.dryRun += 1;
         if (entry.liveness === "running")
             totals.running += 1;
-        const priced = typeof entry.estimatedCostUsd === "number" &&
-            Number.isFinite(entry.estimatedCostUsd) &&
-            entry.estimatedCostUsd >= 0;
-        if (priced)
-            totals.estimatedSpendUsd += entry.estimatedCostUsd;
-        else
+        const runUsd = runEstimateUsd(entry);
+        if (runUsd === undefined)
             totals.unpricedRuns += 1;
+        else
+            totals.estimatedSpendUsd += runUsd;
         addParticipants(totals.participants, entry);
         if (entry.verdict !== undefined)
             totals.verdicts[entry.verdict] = (totals.verdicts[entry.verdict] ?? 0) + 1;
-        addToLabRow(labs, entry, priced, accounting.costs);
-        addToDayRow(days, entry, priced, accounting.costs);
+        addToLabRow(labs, entry, runUsd, accounting.costs);
+        addToDayRow(days, entry, runUsd, accounting.costs);
     }
     const labRows = [...labs.values()]
         .map(({ durations, runCosts, ...row }) => ({
@@ -186,15 +193,15 @@ export async function computeStats(cwdInput, options = {}) {
         ...(runCosts.length === 0 ? {} : { medianCostUsd: round6(median(runCosts)) }),
         costSamples: runCosts.length,
     }))
-        .sort((a, b) => b.runs - a.runs || a.lab.localeCompare(b.lab));
+        .sort((a, b) => b.runs - a.runs || a.study.localeCompare(b.study));
     return {
         schema: STATS_SCHEMA,
         ok: true,
         cwd,
         ...(options.since === undefined ? {} : { since: options.since }),
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        ...(options.lab === undefined ? {} : { study: options.lab }),
         totals: { ...totals, estimatedSpendUsd: round6(totals.estimatedSpendUsd) },
-        labs: labRows,
+        studies: labRows,
         days: [...days.values()]
             .map((row) => ({ ...row, estimatedSpendUsd: round6(row.estimatedSpendUsd) }))
             .sort((a, b) => a.day.localeCompare(b.day)),
@@ -212,47 +219,98 @@ function knownMoney(value) {
 function minutes(ms) {
     return `${(ms / 60_000).toFixed(1)}m`;
 }
+/**
+ * Whether every selected run is a dry run whose accounting is a complete $0: no recorded figure,
+ * no incomplete estimate and no analysis attempt. Only then does the one-line report hold.
+ */
+function onlyFreeDryRuns(t) {
+    return (t.runs > 0 &&
+        t.runs === t.dryRun &&
+        t.costs.estimatedTotalUsd === 0 &&
+        t.costs.incompleteRunEstimates === 0 &&
+        t.costs.analysisAttempts === 0);
+}
+/** The run counts, with dry runs on their own line. */
+function runCountLines(t) {
+    if (t.runs === 0)
+        return ["no runs yet; start one with humanish run first-run"];
+    if (onlyFreeDryRuns(t))
+        return [`${plural(t.dryRun, "dry run")} ($0); no live runs yet`];
+    const running = t.running > 0 ? ` (${t.running} still running)` : "";
+    return [`live runs: ${t.live}${running}`, ...(t.dryRun > 0 ? [`dry runs: ${t.dryRun}`] : [])];
+}
+/** Spend, analysis, participants and verdicts across the selected live runs. */
+function totalsLines(t) {
+    const c = t.costs;
+    const incomplete = c.incompleteRunEstimates > 0
+        ? `; ${plural(c.incompleteRunEstimates, "run")} with incomplete accounting`
+        : "";
+    const unpriced = c.analysisUnpricedAttempts > 0 || c.analysisUnresolvedAttempts > 0
+        ? `; ${c.analysisUnpricedAttempts} unpriced, ${c.analysisUnresolvedAttempts} unresolved`
+        : "";
+    const verdicts = Object.entries(t.verdicts).map(([verdict, count]) => `${verdict} ${count}`);
+    return [
+        `known estimated spend: ${knownMoney(c.estimatedTotalUsd)}`,
+        `participants and desktops: ${knownMoney(c.runEstimatedUsd)}${incomplete}`,
+        c.analysisAttempts === 0
+            ? "analysis: none recorded"
+            : `analysis: ${knownMoney(c.analysisEstimatedUsd)} over ${plural(c.analysisAttempts, "recorded attempt")}${unpriced}`,
+        ...(c.analysisHistoryUncertainRuns > 0
+            ? [
+                `analysis history: ${plural(c.analysisHistoryUncertainRuns, "run")} missing or uncertain; --json lists each run`,
+            ]
+            : []),
+        ...(t.participants.total > 0
+            ? [
+                `participants: ${t.participants.reachedGoal} of ${t.participants.total} reached the goal, ${t.participants.reportedFriction} reported friction`,
+            ]
+            : []),
+        ...(verdicts.length > 0 ? [`verdicts: ${verdicts.join(", ")}`] : []),
+    ];
+}
+function dayLine(row) {
+    return `- ${row.day}: ${plural(row.runs, "run")}, ${row.live} live, known study spend ${knownMoney(row.costs.estimatedTotalUsd)}${unpricedTail(row.unpricedRuns, row.costs.analysisUnpricedAttempts)}`;
+}
+/** "; 2 unpriced runs, 1 unpriced analysis", or nothing when both are zero. */
+function unpricedTail(runs, analyses) {
+    if (runs === 0 && analyses === 0)
+        return "";
+    return `; ${plural(runs, "unpriced run")}, ${plural(analyses, "unpriced analysis", "unpriced analyses")}`;
+}
 export function formatStatsHuman(result) {
     if (!result.ok)
-        return `${result.error.code}: ${result.error.message}\n`;
+        return { error: result.error };
     const t = result.totals;
     const scope = [
-        result.lab === undefined ? undefined : `lab ${result.lab}`,
+        result.study === undefined ? undefined : `lab ${result.study}`,
         result.since === undefined ? undefined : `since ${result.since}`,
     ].filter((part) => part !== undefined);
     const lines = [
         `humanish stats${scope.length === 0 ? "" : ` (${scope.join(", ")})`}`,
-        `runs: ${t.runs} (${t.live} live, ${t.dryRun} dry-run${t.running > 0 ? `, ${t.running} running` : ""})`,
-        `known estimated spend: ${knownMoney(t.costs.estimatedTotalUsd)}`,
-        `participants + desktops: ${knownMoney(t.costs.runEstimatedUsd)}; ${t.costs.incompleteRunEstimates} run(s) with incomplete accounting`,
-        `analysis: ${knownMoney(t.costs.analysisEstimatedUsd)} over ${t.costs.analysisAttempts} recorded attempt(s); ${t.costs.analysisUnpricedAttempts} unpriced, ${t.costs.analysisUnresolvedAttempts} unresolved`,
-        `analysis history: ${t.costs.analysisHistoryUncertainRuns} run(s) missing or uncertain; use --json for per-run accounting`,
-        `participants: ${t.participants.reachedGoal}/${t.participants.total} recorded goal completions, ${t.participants.reportedFriction} reported friction`,
-        `verdicts: ${Object.entries(t.verdicts)
-            .map(([verdict, count]) => `${verdict} ${count}`)
-            .join(", ") || "none recorded"}`,
+        ...runCountLines(t),
     ];
-    if (result.labs.length > 0) {
-        lines.push("", "per lab:");
-        for (const row of result.labs) {
-            const rate = row.passRate === undefined ? "no verdicts" : `${row.passed}/${row.judged} pass`;
-            const duration = row.medianDurationMs === undefined
-                ? "no timed live runs"
-                : `median ${minutes(row.medianDurationMs)} over ${row.durationSamples}`;
-            const cost = row.medianCostUsd === undefined
-                ? "no priced participant/desktop runs"
-                : `participant/desktop median ${money(row.medianCostUsd)} over ${row.costSamples}`;
-            lines.push(`- ${row.lab}: ${row.runs} run(s), ${row.live} live; ${rate}; ${duration}; known study spend ${knownMoney(row.costs.estimatedTotalUsd)}; ${cost}; ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
-        }
-    }
-    if (result.days.length > 0) {
-        lines.push("", "by day:");
-        for (const row of result.days) {
-            lines.push(`- ${row.day}: ${row.runs} run(s), ${row.live} live, known study spend ${knownMoney(row.costs.estimatedTotalUsd)}, ${row.unpricedRuns} unpriced runs, ${row.costs.analysisUnpricedAttempts} unpriced analyses`);
-        }
+    // Free dry runs alone have no spend, outcome or duration to report. Anything else, an unreadable
+    // directory or a dry run that records a cost included, gets the full report.
+    const reportable = t.runs > 0 && !onlyFreeDryRuns(t);
+    if (reportable) {
+        lines.push(...totalsLines(t));
+        if (result.studies.length > 0)
+            lines.push("", "per lab:", ...result.studies.map((row) => {
+                const rate = row.passRate === undefined ? "no verdicts" : `${row.passed} of ${row.judged} passed`;
+                const duration = row.medianDurationMs === undefined
+                    ? "no timed live runs"
+                    : `median ${minutes(row.medianDurationMs)} over ${row.durationSamples}`;
+                const cost = row.medianCostUsd === undefined
+                    ? "no priced participant/desktop runs"
+                    : `participant/desktop median ${money(row.medianCostUsd)} over ${row.costSamples}`;
+                return `- ${row.study}: ${plural(row.runs, "run")}, ${row.live} live; ${rate}; ${duration}; known study spend ${knownMoney(row.costs.estimatedTotalUsd)}; ${cost}${unpricedTail(row.unpricedRuns, row.costs.analysisUnpricedAttempts)}`;
+            }));
+        if (result.days.length > 0)
+            lines.push("", "by day:", ...result.days.map(dayLine));
     }
     if (result.unreadable.length > 0)
         lines.push("", `unreadable run directories: ${result.unreadable.join(", ")}`);
-    lines.push("", result.note);
+    if (reportable)
+        lines.push("", result.note);
     return `${lines.join("\n")}\n`;
 }

package/dist/run/status.d.ts

@@ -1,4 +1,5 @@
 import type { RunBundle } from "./bundle.js";
+import { type RunStudyProvenance } from "./study-provenance.js";
 import { type PreparedOutputRoot } from "./contained-output.js";
 import type { ExecutionOutcome } from "./judge.js";
 export declare const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
@@ -7,21 +8,14 @@ export declare const RUN_STATUS_FILE = "status.json";
 /** How often a live run touches `updatedAt`. */
 export declare const RUN_STATUS_TOUCH_MS = 5000;
 /**
- * A `running` record whose `updatedAt` is older than this is INTERRUPTED, not alive: the process
+ * A `running` record whose `updatedAt` is older than this is interrupted, not alive: the process
  * died without finalizing (a dropped SSH, a killed terminal, a crash). Three touch intervals of
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export declare const RUN_STATUS_STALE_MS: number;
-/** Which manifest a run came from, when it came from one. */
-export interface RunLabProvenance {
-    /** The lab id as declared in its manifest (`config.id`). */
-    id: string;
-    /** Repo-relative manifest path, when the run came from a file on disk. */
-    path?: string;
-    /** `committed` = humanish/labs, `ignored` = a local overlay, `explicit` = a path the operator passed. */
-    origin?: "committed" | "ignored" | "explicit";
-}
-type RunStatusState = "running" | "finished";
+type RunStatusState = "running" | "finished" | "interrupted";
+/** The signals the CLI's run handler records when it stops a run. */
+export type RunInterruptSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 /** The outcome summary a finalized record carries. Derived from the bundle; never authoritative. */
 interface RunStatusOutcome {
     /** `review.verdict` verbatim. */
@@ -47,14 +41,18 @@ export interface RunStatusRecord {
     runId: string;
     state: RunStatusState;
     mode: "dry-run" | "live";
-    /** Absent when the run did not come from a lab manifest (a library caller, a bare `run`). */
-    lab?: RunLabProvenance;
+    /** Absent when the run did not come from a study file (a library caller, a bare `run`). */
+    study?: RunStudyProvenance;
+    /** `study`'s value, written beside it until 0.109. Read either through studyProvenanceOf. */
+    lab?: RunStudyProvenance;
     /** The pid that owns the run, for local liveness checks. */
     pid: number;
     startedAt: string;
     /** Refreshed on a fixed cadence while the run is alive; the staleness signal. */
     updatedAt: string;
     completedAt?: string;
+    /** The signal that stopped the run, on an `interrupted` record. */
+    signal?: RunInterruptSignal;
     outcome?: RunStatusOutcome;
 }
 export interface RunStatusHandle {
@@ -64,7 +62,7 @@ export interface RunStatusHandle {
      *  still has a record to classify. */
     readonly started: Promise<void>;
     /** Finalize: state `finished`, `completedAt`, and the derived outcome. Stops the cadence.
-     *  Idempotent — a second call is a no-op, so a backend with several exit paths is safe. */
+     *  Idempotent: a second call is a no-op, so a route with several exit paths is safe. */
     finish(outcome?: RunStatusOutcome): Promise<void>;
     /** After finish, add the result's ok and execution outcome to the finished record, so status.json
      *  and the result agree. Before finish it does nothing. */
@@ -72,19 +70,25 @@ export interface RunStatusHandle {
         ok: boolean;
         execution: ExecutionOutcome;
     }): Promise<void>;
+    /** The process is being stopped by `signal`: state `interrupted`, `completedAt` and the signal.
+     *  It stops the cadence and makes a later finish or settle a no-op, so the route cannot write
+     *  `running` or `finished` over it. When the run had finished it writes nothing, waits for the
+     *  writes already queued and resolves false. */
+    interrupt(signal: RunInterruptSignal): Promise<boolean>;
 }
 export interface BeginRunStatusOptions {
     runId: string;
     mode: "dry-run" | "live";
-    lab?: RunLabProvenance;
+    lab?: RunStudyProvenance | undefined;
 }
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
  * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d — this file can never be the reason a process stays alive.
+ * `unref`'d, so this file can never be the reason a process stays alive.
  */
 export declare function beginRunStatus(runPaths: PreparedOutputRoot, options: BeginRunStatusOptions): RunStatusHandle;
-/** The three ways a run reads from disk. `interrupted` is a `running` record gone stale. */
+/** The three ways a run reads from disk. `interrupted` is a record its stopped process wrote, or a
+ *  `running` record gone stale. */
 export type RunLiveness = "running" | "interrupted" | "finished";
 /**
  * Classify a status record. Pure, so the TUI, the CLI and tests share one definition of "alive".
@@ -93,19 +97,4 @@ export type RunLiveness = "running" | "interrupted" | "finished";
 export declare function classifyRunStatus(record: Pick<RunStatusRecord, "state" | "updatedAt">, nowMs: number, staleMs?: number): RunLiveness;
 /** Shape guard for a record read off disk. Unknown extra fields are tolerated (additive contract). */
 export declare function isRunStatusRecord(value: unknown): value is RunStatusRecord;
-/**
- * The legacy bridge: infer a lab id for a bundle written BEFORE this contract, where the only
- * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
- * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
- * remainder is not an id. Ids may contain colons (the removed meta-lab wrote `oss:meta`), so
- * only the FIRST segment is stripped. Returns undefined when the bundle carries no such marker.
- */
-export declare function inferLegacyLabId(bundle: {
-    persona?: {
-        source?: string;
-    };
-    scenario?: {
-        source?: string;
-    };
-}): string | undefined;
 export {};

package/dist/run/status.js

@@ -9,6 +9,7 @@
 // Public safety: it holds only the run id, the lab id/path/origin (the strings `humanish lab list`
 // prints), the mode, a local pid and timestamps. It holds no hostname or user/path identity: an
 // operator may share the run directory, so a share-safety gate must have nothing to strip here.
+import { isProvenanceField, studyFields } from "./study-provenance.js";
 import { writeContainedOutputFile } from "./contained-output.js";
 import { redactText } from "../evidence/redaction.js";
 export const RUN_STATUS_SCHEMA = "humanish.run-status.v1";
@@ -17,11 +18,12 @@ export const RUN_STATUS_FILE = "status.json";
 /** How often a live run touches `updatedAt`. */
 export const RUN_STATUS_TOUCH_MS = 5_000;
 /**
- * A `running` record whose `updatedAt` is older than this is INTERRUPTED, not alive: the process
+ * A `running` record whose `updatedAt` is older than this is interrupted, not alive: the process
  * died without finalizing (a dropped SSH, a killed terminal, a crash). Three touch intervals of
  * slack so an ordinary scheduling hiccup or a slow disk never mislabels a healthy run.
  */
 export const RUN_STATUS_STALE_MS = RUN_STATUS_TOUCH_MS * 3;
+const RUN_INTERRUPT_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 /** The outcome a finalized status record carries, read from the bundle that was just written. */
 export function runStatusOutcome(bundle) {
     return {
@@ -45,7 +47,7 @@ export function runStatusOutcome(bundle) {
 /**
  * Start a run's status record and keep it fresh. Fire-and-forget by design: a status write that
  * fails must never fail the run it describes, so every write swallows its error. The interval is
- * `unref`'d — this file can never be the reason a process stays alive.
+ * `unref`'d, so this file can never be the reason a process stays alive.
  */
 export function beginRunStatus(runPaths, options) {
     const iso = () => new Date().toISOString();
@@ -55,7 +57,7 @@ export function beginRunStatus(runPaths, options) {
         runId: options.runId,
         state: "running",
         mode: options.mode,
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
+        ...studyFields(options.lab),
         pid: process.pid,
         startedAt,
         updatedAt: startedAt,
@@ -102,12 +104,16 @@ export function beginRunStatus(runPaths, options) {
                 return;
             // The record is public-safe by construction, so each message passes the shape redaction
             // again even though the routes scrubbed it.
+            const redacted = (failure) => ({
+                kind: failure.kind,
+                message: redactText(failure.message),
+            });
             const execution = {
                 succeeded: result.execution.succeeded,
-                failures: result.execution.failures.map((failure) => ({
-                    kind: failure.kind,
-                    message: redactText(failure.message),
-                })),
+                failures: result.execution.failures.map(redacted),
+                ...(result.execution.warnings === undefined
+                    ? {}
+                    : { warnings: result.execution.warnings.map(redacted) }),
             };
             finishedRecord = {
                 ...finishedRecord,
@@ -115,6 +121,19 @@ export function beginRunStatus(runPaths, options) {
             };
             await write(finishedRecord);
         },
+        async interrupt(signal) {
+            // A finish that has not landed yet is in the chain: wait for it so the process does not
+            // exit with `running` on disk.
+            if (finished) {
+                await writing;
+                return false;
+            }
+            finished = true;
+            clearInterval(timer);
+            const completedAt = iso();
+            await write({ ...base, state: "interrupted", updatedAt: completedAt, completedAt, signal });
+            return true;
+        },
     };
     return handle;
 }
@@ -125,6 +144,8 @@ export function beginRunStatus(runPaths, options) {
 export function classifyRunStatus(record, nowMs, staleMs = RUN_STATUS_STALE_MS) {
     if (record.state === "finished")
         return "finished";
+    if (record.state === "interrupted")
+        return "interrupted";
     const updated = Date.parse(record.updatedAt);
     if (!Number.isFinite(updated))
         return "interrupted";
@@ -139,7 +160,10 @@ export function isRunStatusRecord(value) {
         return false;
     if (typeof record.runId !== "string" || record.runId === "")
         return false;
-    if (record.state !== "running" && record.state !== "finished")
+    if (record.state !== "running" && record.state !== "finished" && record.state !== "interrupted")
+        return false;
+    if (record.signal !== undefined &&
+        (typeof record.signal !== "string" || !RUN_INTERRUPT_SIGNALS.includes(record.signal)))
         return false;
     if (record.mode !== "dry-run" && record.mode !== "live")
         return false;
@@ -147,30 +171,7 @@ export function isRunStatusRecord(value) {
         return false;
     if (typeof record.startedAt !== "string" || typeof record.updatedAt !== "string")
         return false;
-    if (record.lab !== undefined) {
-        if (record.lab === null || typeof record.lab !== "object")
-            return false;
-        if (typeof record.lab.id !== "string")
-            return false;
-    }
+    if (!isProvenanceField(record.study) || !isProvenanceField(record.lab))
+        return false;
     return true;
 }
-/**
- * The legacy bridge: infer a lab id for a bundle written BEFORE this contract, where the only
- * attribution was the `lab:<id>` convention on persona/scenario source strings. Deliberately
- * conservative — it reads the convention and nothing else, and a `lab:` prefix with an empty
- * remainder is not an id. Ids may contain colons (the removed meta-lab wrote `oss:meta`), so
- * only the FIRST segment is stripped. Returns undefined when the bundle carries no such marker.
- */
-export function inferLegacyLabId(bundle) {
-    for (const source of [bundle.persona?.source, bundle.scenario?.source]) {
-        if (typeof source !== "string")
-            continue;
-        if (!source.startsWith("lab:"))
-            continue;
-        const id = source.slice("lab:".length).trim();
-        if (id !== "")
-            return id;
-    }
-    return undefined;
-}

package/dist/run/stored-runs.js

@@ -1,4 +1,5 @@
 import { lstat, readdir } from "node:fs/promises";
+import { runNotFoundMessage } from "./run-not-found.js";
 import path from "node:path";
 import { redactText } from "../evidence/redaction.js";
 import { bindExistingRunArtifactPaths, RUNS_RELATIVE_ROOT, isSafeRunIdSegment, resolveRunsRoot, validatePreparedRunArtifactPaths, } from "./paths.js";
@@ -66,7 +67,7 @@ export async function cleanupRun(cwdInput, runInput, hooks = {}) {
     if (!resolved) {
         return cleanupRefusal(cwd, runInput, checkedAt, {
             code: "HUMANISH_RUN_NOT_FOUND",
-            message: `Run not found: ${runInput}`,
+            message: await runNotFoundMessage(cwd, runInput),
         });
     }
     const runPaths = resolved;

package/dist/run/stream-shape.js

@@ -140,7 +140,7 @@ export function isRunSimulationStatus(value) {
         value === "running" ||
         value === "passed" ||
         // Participant outcomes (docs/principles/three-roles.md). This runtime allowlist is the actual
-        // gate — the TS union alone does not validate a bundle read back from disk.
+        // gate; the TS union alone does not validate a bundle read back from disk.
         value === "abandoned" ||
         value === "incomplete" ||
         value === "complete" ||