@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/src/parse-args-errors.d.ts

@@ -0,0 +1,2 @@
+/** The option `parseArgs` refused as unknown (`--watch`), or undefined when `error` is not its ERR_PARSE_ARGS_UNKNOWN_OPTION. */
+export declare function unknownOption(error: unknown): string | undefined;

package/entrypoints/cli/src/parse-args-errors.js

@@ -0,0 +1,7 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function unknownOption(error) {
+    if (!(error instanceof Error) || error.code !== "ERR_PARSE_ARGS_UNKNOWN_OPTION")
+        return undefined;
+    return /option '([^']+)'/.exec(error.message)?.[1] ?? "that option";
+}

package/entrypoints/cli/src/plain-output.d.ts

@@ -0,0 +1,98 @@
+import type { ExplainedFailure, FeatureRunRecord, SuiteRunRecord, WorkersRunRecord } from "@parity/product-lab/ports/driving";
+import type { RecordingSummary } from "@parity/product-lab/domain/recordings";
+/** The run's output as the plain output shows it: its own lines; the lab's own lines counted and kept for the end. */
+export declare class PlainOutputFilter {
+    private readonly out;
+    /** How a line of the run's own is shown (`undefined`: not at all); as it is by default. */
+    private readonly shape;
+    /**
+     * B1 (d): a run in the lab window's process streams only its formatter's lines, unmarked (in-process runs write no
+     * mark): each is the run's own, except the lab's `[product-lab] …` lines.
+     */
+    private readonly unmarked;
+    private partial;
+    private readonly last;
+    /** The lab's own lines the output left out (they are in the run's log). */
+    hidden: number;
+    constructor(out: (text: string) => void, 
+    /** How a line of the run's own is shown (`undefined`: not at all); as it is by default. */
+    shape?: (line: string) => string | undefined, 
+    /**
+     * B1 (d): a run in the lab window's process streams only its formatter's lines, unmarked (in-process runs write no
+     * mark): each is the run's own, except the lab's `[product-lab] …` lines.
+     */
+    unmarked?: boolean);
+    readonly write: (chunk: string) => void;
+    /** The lab's last lines the output left out, oldest first (the end of a run that failed outside its steps shows them). */
+    lastHidden(): readonly string[];
+    private line;
+}
+/** "1 scenario passed · 3 steps passed", "1 scenario: 0 passed, 1 failed · 3 steps: 2 passed, 1 failed". */
+export declare function resultWords(record: FeatureRunRecord): string;
+/** The host check of each scenario that recorded one, in the lab window's words (backlog 148): one line when all agree. */
+export declare function hostCheckLines(record: FeatureRunRecord): string[];
+/** Where the run failed and the lab's own answer (`ExplainFailure`), in a few lines; none when nothing failed. */
+export declare function answerLines(record: FeatureRunRecord, explained: ExplainedFailure | undefined): string[];
+/** Backlog 192: the host logs a recording kept, as absolute paths in the store at `location`. */
+export declare function recordingHostLogs(summary: RecordingSummary | undefined, location: string | undefined): string[];
+/** Backlog 192's words on the last line: "the host's log: <path>", "the hosts' logs: <a>, <b>"; none without logs. */
+export declare const hostLogsWords: (hostLogs: readonly string[]) => string[];
+/**
+ * Backlog 192 for a run of several runs (suite rows, workers, race runs): the host logs the recordings of its failed
+ * runs kept, each once. `runs` are the failed runs' records (their scenario's recording, as for one run), or for a run
+ * without one (a worker) its time window, where a failed feature recording that started counts.
+ */
+export declare function failedRunsHostLogs(listed: {
+    recordings: readonly RecordingSummary[];
+    location?: string;
+}, runs: readonly (FeatureRunRecord | {
+    startedAt: number;
+    finishedAt: number;
+})[]): string[];
+/** The recording of the scenario that failed (else of the first), when the run saved one: its id. */
+export declare function runRecording(record: FeatureRunRecord, recordings: readonly RecordingSummary[]): string | undefined;
+export interface PlainEnding {
+    record: FeatureRunRecord;
+    explained?: ExplainedFailure;
+    recording?: string;
+    /** Backlog 192: the hosts' logs the failed run's recording kept (absolute paths). */
+    hostLogs?: readonly string[];
+    reports?: {
+        junit: string;
+        html: string;
+    };
+    filter: PlainOutputFilter;
+    /** Whether the run failed outside its steps (startup, a hook, no report): the lab's last lines then say why. */
+    outsideSteps: boolean;
+}
+/** The result, the answer, the host check and what to look at, after the run's own lines. */
+export declare function plainEnding({ record, explained, recording, hostLogs, reports, filter, outsideSteps }: PlainEnding): {
+    result: string[];
+    lookAt: string;
+};
+/**
+ * A worker's lines in the plain output of `--workers` (backlog 186): after its number, as the command always printed
+ * them. Workers run at once, so their lines interleave: GitHub's groups (one open at a time) are left out, a group's
+ * title kept as the worker's line ("Start", "Scenario: …"), and an annotation stays at the start of its line, where
+ * GitHub reads it.
+ */
+export declare function workerLine(index: number): (line: string) => string | undefined;
+/** The end of a `--workers` run in the plain output: the result, one line per worker, and what to look at. */
+export declare function workersEnding(record: WorkersRunRecord, filters: ReadonlyMap<number, PlainOutputFilter>, hostLogs?: readonly string[]): {
+    result: string[];
+    lookAt: string;
+};
+/** The end of a `--suite` run in the plain output: the result, one line per row, and what to look at. */
+export declare function suiteEnding(record: SuiteRunRecord, written: {
+    junit: string;
+    html: string;
+    summary?: string;
+}, filter: PlainOutputFilter, hostLogs?: readonly string[]): {
+    result: string[];
+    lookAt: string;
+};
+/** One run of `--race` in the plain output: its result and, when it failed, where and the lab's answer. */
+export declare function raceRunLines(record: FeatureRunRecord, explained: ExplainedFailure | undefined, reports?: {
+    junit: string;
+    html: string;
+}): string[];

package/entrypoints/cli/src/plain-output.js

@@ -0,0 +1,179 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PLAIN_MARK, plainDuration, shortIds } from "@parity/product-lab/domain/features";
+import { hostBypassAudit } from "@parity/product-lab/shell/host-bypass-words";
+const LAST_LINES = 12;
+export class PlainOutputFilter {
+    out;
+    shape;
+    unmarked;
+    partial = "";
+    last = [];
+    hidden = 0;
+    constructor(out, 
+    shape = (line) => line, 
+    unmarked = false) {
+        this.out = out;
+        this.shape = shape;
+        this.unmarked = unmarked;
+    }
+    write = (chunk) => {
+        const lines = (this.partial + chunk).split("\n");
+        this.partial = lines.pop() ?? "";
+        for (const line of lines)
+            this.line(line);
+    };
+    lastHidden() {
+        if (this.partial) {
+            this.line(this.partial);
+            this.partial = "";
+        }
+        return this.last;
+    }
+    line(line) {
+        if (this.unmarked && !line.includes(PLAIN_MARK) && !line.startsWith("[product-lab]")) {
+            const shown = this.shape(line);
+            if (shown !== undefined)
+                this.out(`${shown}\n`);
+            return;
+        }
+        const at = line.indexOf(PLAIN_MARK);
+        const own = at < 0 ? line : line.slice(0, at);
+        if (own.trim()) {
+            this.hidden++;
+            this.last.push(own);
+            if (this.last.length > LAST_LINES)
+                this.last.shift();
+        }
+        const shown = at >= 0 ? this.shape(line.slice(at + 1)) : undefined;
+        if (shown !== undefined)
+            this.out(`${shown}\n`);
+    }
+}
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+export function resultWords(record) {
+    const counts = (statuses) => {
+        const by = new Map();
+        for (const status of statuses)
+            by.set(status, (by.get(status) ?? 0) + 1);
+        return by;
+    };
+    const say = (word, statuses) => {
+        const by = counts(statuses);
+        if (!by.size)
+            return plural(0, word);
+        if (by.size === 1)
+            return `${plural(statuses.length, word)} ${[...by.keys()][0]}`;
+        return `${plural(statuses.length, word)}: ${[...by].map(([status, count]) => `${count} ${status}`).join(", ")}`;
+    };
+    const steps = record.scenarios.flatMap((scenario) => scenario.steps.filter((step) => !step.hidden).map((step) => step.status));
+    return `${say("scenario", record.scenarios.map((scenario) => scenario.status))} · ${say("step", steps)}`;
+}
+export function hostCheckLines(record) {
+    const said = record.scenarios.flatMap((scenario) => (scenario.hostBypass ? [{ name: scenario.name, headline: hostBypassAudit(scenario.hostBypass, { name: (id) => id }).headline }] : []));
+    if (!said.length)
+        return [];
+    if (said.every((item) => item.headline === said[0].headline))
+        return [`Host check: ${said[0].headline}`];
+    return said.map((item) => `Host check, "${item.name}": ${item.headline}`);
+}
+const SAW_REASONS = 3;
+function sawLines(error) {
+    const [first = "", ...rest] = error.split("\n");
+    const lines = [`What the lab saw: ${shortIds(first.replace(/^\w*Error: /, ""))}`];
+    if (!first.trimEnd().endsWith(":"))
+        return lines;
+    const reasons = rest.map((line) => line.trim()).filter((line) => line.startsWith("- "));
+    lines.push(...reasons.slice(0, SAW_REASONS).map((reason) => `  ${shortIds(reason)}`));
+    if (reasons.length > SAW_REASONS)
+        lines.push(`  and ${reasons.length - SAW_REASONS} more`);
+    return lines;
+}
+export function answerLines(record, explained) {
+    if (!explained || explained.verdict === "no-failure")
+        return [];
+    const lines = [];
+    const scenario = record.scenarios.find((item) => item.status === "failed");
+    const steps = scenario?.steps.filter((step) => !step.hidden) ?? [];
+    const at = steps.findIndex((step) => step.status === "failed");
+    if (scenario && at >= 0)
+        lines.push(`Failed at: "${scenario.name}", step ${at + 1}: ${steps[at].keyword.trim()} ${steps[at].name}`);
+    else if (explained.step)
+        lines.push(`Failed at: ${explained.step.title}`);
+    if (explained.error && !(scenario && at >= 0))
+        lines.push(...sawLines(explained.error));
+    lines.push(`The lab's answer${explained.layer ? ` (${explained.layer})` : ""}: ${shortIds(explained.hint)}`);
+    return lines;
+}
+export function recordingHostLogs(summary, location) {
+    return location && summary?.hostLogs ? summary.hostLogs.map((file) => join(location, summary.id, file)) : [];
+}
+export const hostLogsWords = (hostLogs) => (hostLogs.length ? [`the ${hostLogs.length === 1 ? "host's log" : "hosts' logs"}: ${hostLogs.join(", ")}`] : []);
+export function failedRunsHostLogs(listed, runs) {
+    const ids = runs.flatMap((run) => ("scenarios" in run ? [runRecording(run, listed.recordings)] : listed.recordings.filter((item) => item.kind === "feature" && item.status === "failed" && item.startedAt >= run.startedAt && item.startedAt <= run.finishedAt).map((item) => item.id)));
+    return [...new Set(ids.filter((id) => id !== undefined).flatMap((id) => recordingHostLogs(listed.recordings.find((item) => item.id === id), listed.location)))];
+}
+export function runRecording(record, recordings) {
+    const mine = recordings.filter((item) => item.kind === "feature" && item.startedAt >= record.startedAt && (record.finishedAt === undefined || item.startedAt <= record.finishedAt));
+    const scenario = record.scenarios.find((item) => item.status === "failed") ?? record.scenarios[0];
+    return (mine.find((item) => item.title === scenario?.name) ?? mine[0])?.id;
+}
+export function plainEnding({ record, explained, recording, hostLogs = [], reports, filter, outsideSteps }) {
+    const took = record.finishedAt !== undefined ? ` in ${plainDuration(record.finishedAt - record.startedAt)}` : "";
+    const result = [`Result: ${record.status}${took} · ${resultWords(record)}`];
+    for (const line of [...answerLines(record, explained), ...hostCheckLines(record)])
+        result.push(`  ${line}`);
+    if (reports)
+        result.push(`  Reports: ${reports.html}, ${reports.junit}`);
+    const log = join(record.directory, "cucumber.log");
+    const last = filter.lastHidden();
+    if (outsideSteps && last.length)
+        result.push(`  The lab's last lines (of ${filter.hidden}${existsSync(log) ? ` in ${log}` : ""}):`, ...last.map((line) => `    ${shortIds(line)}`));
+    const look = [
+        reports ? reports.html : record.report,
+        ...(recording ? [`the recording: product-lab recordings ${recording}`] : []),
+        ...hostLogsWords(hostLogs),
+    ];
+    if (filter.hidden && existsSync(log))
+        look.push(`the lab's own ${plural(filter.hidden, "line")}: ${log} (--verbose prints them)`);
+    return { result, lookAt: `Look at: ${look.join(" · ")}` };
+}
+export function workerLine(index) {
+    return (line) => {
+        if (line.startsWith("::endgroup::"))
+            return undefined;
+        const title = /^::group::(.*)$/.exec(line)?.[1];
+        if (title !== undefined)
+            return `[worker ${index}] ${title}`;
+        return line.startsWith("::") ? line : `[worker ${index}] ${line}`;
+    };
+}
+export function workersEnding(record, filters, hostLogs = []) {
+    const failed = record.workers.filter((worker) => worker.status === "failed");
+    const result = [`Result: ${record.status} · ${plural(record.workers.length, "worker")} at once for ${plainDuration(record.overlapMs)} · ${failed.length ? `${failed.length} failed` : "all passed"}`];
+    for (const worker of record.workers)
+        result.push(`  worker ${worker.index}: ${worker.status} in ${plainDuration(worker.durationMs)} · ${worker.features.join(", ")} · ${Object.values(worker.endpoints).join(", ") || "no endpoints recorded"}`);
+    for (const shared of record.sharedEndpoints)
+        result.push(`  not isolated: workers ${shared.workers.join(" and ")} reached ${shared.address}`);
+    const look = [record.report, ...failed.flatMap((worker) => (worker.run ? [`worker ${worker.index}'s run: ${worker.run.directory}`] : [])), ...hostLogsWords(hostLogs)];
+    const hidden = [...filters.values()].reduce((sum, filter) => sum + filter.hidden, 0);
+    if (hidden)
+        look.push(`the lab's own ${plural(hidden, "line")}: each worker's cucumber.log (--verbose prints them)`);
+    return { result, lookAt: `Look at: ${look.join(" · ")}` };
+}
+export function suiteEnding(record, written, filter, hostLogs = []) {
+    const took = record.finishedAt !== undefined ? ` in ${plainDuration(record.finishedAt - record.startedAt)}` : "";
+    const result = [`Result: ${record.status}${took} · ${plural(record.rows.length, "row")}: ${record.rows.map((row) => `${row.id} ${row.status}`).join(", ")}`];
+    for (const row of record.rows)
+        result.push(`  ${row.id}: ${row.status}${row.reason ? ` (${shortIds(row.reason)})` : ""}${row.durationMs !== undefined ? ` in ${plainDuration(row.durationMs)}` : ""}`);
+    const look = [written.html, ...(written.summary ? [`summary: ${written.summary}`] : []), ...hostLogsWords(hostLogs)];
+    if (filter.hidden)
+        look.push(`the lab's own ${plural(filter.hidden, "line")}: each row's cucumber.log (--verbose prints them)`);
+    return { result, lookAt: `Look at: ${look.join(" · ")}` };
+}
+export function raceRunLines(record, explained, reports) {
+    const took = record.finishedAt !== undefined ? ` in ${plainDuration(record.finishedAt - record.startedAt)}` : "";
+    return [`Result: ${record.status}${took} · ${resultWords(record)}`, ...answerLines(record, explained).map((line) => `  ${line}`), ...(reports ? [`  Reports: ${reports.html}, ${reports.junit}`] : [])];
+}

package/entrypoints/cli/src/recordings-command.d.ts

@@ -0,0 +1,15 @@
+import type { LabRuntime, RecordingListing, RecordingView } from "@parity/product-lab/ports/driving";
+import { type StepSpeedReport } from "@parity/product-lab/domain/recordings";
+export declare const RECORDINGS_USAGE = "Usage: product-lab recordings [<id>] [--step <n> | --timings] [--config lab.config.ts] [--json]\n\nThe lab's recorded runs, newest first, or one recording: its steps across identities, the frames before and after\neach step, chain observations and transactions. Read-only: nothing starts or runs; the environment may be stopped.\nOpen a recording visually in the lab panel (Runs, Recordings).\n  <id>                  a recording id from the list\n  --step <n>            with <id>: one step (1-based), with its frames for every identity\n  --timings             with <id>: each step's duration against the same step in earlier passed runs of the scenario\n                        (same lab and environment): slower when over twice its median and at least 2 s more, from at\n                        least 3 earlier runs (--factor <x>, --min-gap-ms <ms>, --min-samples <n> change the limits)\n  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)\n  --json                print JSON\nWhere recordings go and how long they are kept: PRODUCT_LAB_RECORDINGS (frames, steps, off; default frames),\nPRODUCT_LAB_RECORDINGS_DIR (default <lab>/.product-lab/recordings), PRODUCT_LAB_RECORDINGS_KEEP (default 50),\nPRODUCT_LAB_RECORDINGS_MAX_AGE_DAYS (default 30), PRODUCT_LAB_RECORDINGS_MAX_MB (default 500).";
+export declare function renderStepSpeed(report: StepSpeedReport): string;
+/** What a step changed on the chains (backlog 22): one line per chain, and with `detail` its events and accounts. */
+export declare function chainChangeLines(recording: RecordingView["recording"], index: number, detail: boolean, name: (id: string) => string): string[];
+/** Backlog 23: what the step's identity's app printed; the messages themselves under `--step`. */
+export declare function consoleLines(recording: RecordingView["recording"], index: number, detail: boolean): string[];
+/** Backlog 41: what the step's identity's apps asked their hosts for, as each host words it, and what is unknown. */
+export declare function hostRequestLines(recording: RecordingView["recording"], index: number): string[];
+/** Backlog 25: what was unhealthy during the step; the machine and chain numbers under `--step`. */
+export declare function healthLines(recording: RecordingView["recording"], index: number, detail: boolean): string[];
+export declare function renderListing(listing: RecordingListing): string;
+export declare function renderRecording(view: RecordingView, step?: number): string;
+export declare function runRecordingsCommand(runtime: LabRuntime, argv: string[], out?: (text: string) => void): Promise<number>;

package/entrypoints/cli/src/recordings-command.js

@@ -0,0 +1,232 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { hostBypassLines } from "./reports/host-bypass.js";
+import { parseArgs } from "node:util";
+import { RecordingHealth, describeStepMachine, stepHealthSummary } from "@parity/product-lab/domain/recordings";
+export const RECORDINGS_USAGE = `Usage: product-lab recordings [<id>] [--step <n> | --timings] [--config lab.config.ts] [--json]
+
+The lab's recorded runs, newest first, or one recording: its steps across identities, the frames before and after
+each step, chain observations and transactions. Read-only: nothing starts or runs; the environment may be stopped.
+Open a recording visually in the lab panel (Runs, Recordings).
+  <id>                  a recording id from the list
+  --step <n>            with <id>: one step (1-based), with its frames for every identity
+  --timings             with <id>: each step's duration against the same step in earlier passed runs of the scenario
+                        (same lab and environment): slower when over twice its median and at least 2 s more, from at
+                        least 3 earlier runs (--factor <x>, --min-gap-ms <ms>, --min-samples <n> change the limits)
+  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)
+  --json                print JSON
+Where recordings go and how long they are kept: PRODUCT_LAB_RECORDINGS (frames, steps, off; default frames),
+PRODUCT_LAB_RECORDINGS_DIR (default <lab>/.product-lab/recordings), PRODUCT_LAB_RECORDINGS_KEEP (default 50),
+PRODUCT_LAB_RECORDINGS_MAX_AGE_DAYS (default 30), PRODUCT_LAB_RECORDINGS_MAX_MB (default 500).`;
+const time = (ms) => new Date(ms).toISOString().replace("T", " ").replace(/\.\d+Z$/, "Z");
+const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+export function renderStepSpeed(report) {
+    const verdict = { within: "within", slower: "SLOWER", "no-history": "no history", "not-timed": "not timed" };
+    const lines = [
+        `Step timings of ${report.recording} against ${report.compared.length} earlier passed run(s)${report.compared.length ? "" : " (none: run the scenario again to build a history)"}`,
+        ...report.steps.map((step) => {
+            const took = step.durationMs === undefined ? "-" : seconds(step.durationMs);
+            const usual = step.history ? `median ${seconds(step.history.medianMs)} of ${step.history.samples}` : "no earlier run";
+            const limit = step.limitMs === undefined ? "" : `, limit ${seconds(step.limitMs)}`;
+            return `${String(step.index + 1).padStart(3)}. ${verdict[step.verdict].padEnd(10)} ${took.padStart(7)}  (${usual}${limit})  ${step.title}${step.role ? ` [${step.role}]` : ""}`;
+        }),
+        `${report.slower} step(s) slower than usual`,
+        ...(report.unreadable ?? []).map((item) => `not read as history: ${item.id}: ${item.error}`),
+    ];
+    return lines.join("\n") + "\n";
+}
+export function chainChangeLines(recording, index, detail, name) {
+    const changes = recording.chainChanges;
+    if (!changes)
+        return [];
+    const lines = [];
+    for (const window of changes.windows.filter((item) => item.step === index)) {
+        const blocks = changes.blocks.filter((block) => block.chain === window.chain && block.number >= window.from && block.number <= window.to);
+        const events = blocks.flatMap((block) => block.events.map((event) => ({ block: block.number, ...event })));
+        const range = window.to < window.from ? "no block produced" : `#${window.from}-#${window.to} (${window.head})`;
+        const shared = window.overlapping.length ? `, shared with step(s) ${window.overlapping.map((step) => step + 1).join(", ")}` : "";
+        lines.push(`       chain ${window.chain}: ${range}, ${events.length} event(s)${shared}`);
+        if (detail)
+            for (const event of events)
+                lines.push(`         #${event.block} extrinsic ${event.extrinsic}: ${event.pallet}.${event.name}${event.accounts.length ? ` (mentions ${event.accounts.map((account) => recording.actors.find((actor) => actor.account === account)?.name ?? account).join(", ")})` : ""}`);
+        for (const account of changes.accounts.filter((item) => item.step === index && item.chain === window.chain))
+            if (account.before && account.after)
+                lines.push(`       ${name(account.actor)} on ${window.chain}: nonce ${account.before.nonce} -> ${account.after.nonce}, free ${account.before.free} -> ${account.after.free}`);
+    }
+    for (const gap of changes.gaps.filter((item) => item.step === index || (item.step === undefined && detail)))
+        lines.push(`       chain ${gap.chain}${gap.block !== undefined ? ` #${gap.block}` : ""} not read: ${gap.reason}`);
+    return lines;
+}
+export function consoleLines(recording, index, detail) {
+    const printed = recording.console?.steps.find((item) => item.step === index);
+    if (!printed)
+        return [];
+    const unexpected = new Set(printed.unexpected);
+    const lines = [`       console: ${printed.errors.length} error(s)${unexpected.size ? ` (${printed.unexpected.length} unexpected)` : ""}, ${printed.warnings.length} warning(s)`];
+    if (detail)
+        lines.push(...printed.errors.map((text) => `         error${unexpected.has(text) ? " (unexpected)" : ""}: ${text.split("\n")[0]}`), ...printed.warnings.map((text) => `         warning: ${text.split("\n")[0]}`));
+    return lines;
+}
+export function hostRequestLines(recording, index) {
+    const asked = recording.hostRequests;
+    if (!asked)
+        return [];
+    return [
+        ...asked.steps.filter((item) => item.step === index).map((item) => `       asked its host (${item.app}): ${item.requests.join("; ")}`),
+        ...asked.gaps.filter((item) => item.step === index).map((item) => `       host requests${item.app ? ` (${item.app})` : ""} unknown: ${item.reason}`),
+    ];
+}
+export function healthLines(recording, index, detail) {
+    if (!recording.health)
+        return [];
+    const step = recording.steps.find((item) => item.index === index);
+    const [health] = step ? RecordingHealth.DEFAULT.steps([step], recording.health) : [];
+    if (!health)
+        return [];
+    const lines = health.findings.map((finding) => `       health: ${finding}`);
+    if (detail) {
+        if (health.machine)
+            lines.push(`       machine: ${describeStepMachine(health.machine)}`);
+        for (const chain of health.chains)
+            lines.push(`       ${chain.id}: ${chain.blocks} block(s)${chain.blocksPerMinute !== undefined ? `, ${chain.blocksPerMinute}/min` : ""}${chain.maxFinalityLag !== undefined ? `, finality ${chain.maxFinalityLag} behind` : ""}, longest without a block ${(chain.longestStallMs / 1000).toFixed(1)} s`);
+    }
+    return lines;
+}
+function healthHeader(recording) {
+    const health = recording.health;
+    if (!health)
+        return [];
+    const { machine, lab } = stepHealthSummary(RecordingHealth.DEFAULT.steps(recording.steps, health));
+    return [
+        `Health: ${health.samples.length} sample(s), every ${health.intervalMs / 1000} s${health.dropped ? `, ${health.dropped} past the limit not kept` : ""}`,
+        ...(machine.length ? [`  the machine was the limit in step(s) ${machine.join(", ")}`] : []),
+        ...(lab.length ? [`  the lab's own loop was the limit in step(s) ${lab.join(", ")}`] : []),
+        ...health.gaps.map((gap) => `  health not sampled: ${gap}`),
+    ];
+}
+function consoleHeader(recording, name) {
+    const printed = recording.console;
+    if (!printed)
+        return [];
+    return [
+        ...printed.unwatched.map((item) => `Console not watched${item.actor ? ` for ${name(item.actor)}${item.app ? ` (${item.app})` : ""}` : ""}: ${item.reason}`),
+        ...(printed.dropped ? [`Console: ${printed.dropped} error(s) and warning(s) past the recording's limit were not kept`] : []),
+    ];
+}
+export function renderListing(listing) {
+    const lines = [
+        `Recordings: ${listing.location ?? `none (${listing.disabled})`} · mode ${listing.mode} · keeps ${listing.retention}`,
+        ...listing.recordings.map((item) => `${item.id}  ${item.status.padEnd(10)} ${time(item.startedAt)}  ${seconds(item.finishedAt - item.startedAt).padStart(7)}  ${item.title} · ${item.actors.join(", ") || "no identity"} · ${item.steps} step(s) · frames ${item.frames.captured} captured, ${item.frames.unavailable} unavailable, ${item.frames.failed} failed${item.media === "synthetic" || item.media === "mixed" ? ` · media ${item.media}` : ""}`),
+        ...(listing.recordings.length ? [] : ["No recorded runs yet."]),
+        ...listing.unreadable.map((item) => `unreadable ${item.id}: ${item.error}`),
+        ...(listing.lastFailure ? [`last write failed at ${time(listing.lastFailure.at)}: ${listing.lastFailure.error}`] : []),
+    ];
+    return lines.join("\n") + "\n";
+}
+export function renderRecording(view, step) {
+    const { recording } = view;
+    const name = (id) => recording.actors.find((actor) => actor.id === id)?.name ?? id;
+    const lines = [
+        `Replay (read-only) · ${recording.title} · ${recording.status} · ${recording.environment.label} · recorded ${time(recording.recordedAt)}`,
+        `Identities: ${recording.actors.map((actor) => `${actor.name}${actor.role ? ` (${actor.role})` : ""}`).join(", ") || "none"}`,
+        `Capture: ${recording.capture.mode}${recording.capture.sources.length ? ` from ${recording.capture.sources.join(", ")}` : ""}, media ${recording.capture.media}`,
+        ...recording.capture.notes.map((note) => `  note: ${note}`),
+        ...hostBypassLines(recording.hostBypass),
+        ...consoleHeader(recording, name),
+        ...healthHeader(recording),
+    ];
+    for (const item of recording.steps) {
+        if (step !== undefined && item.index !== step)
+            continue;
+        const took = item.startedAt !== undefined && item.finishedAt !== undefined ? ` ${seconds(item.finishedAt - item.startedAt)}` : "";
+        lines.push(`${String(item.index + 1).padStart(3)}. ${item.status.padEnd(8)} ${item.actor ? name(item.actor) : "no identity"}: ${item.title}${took}${item.error ? ` · ${item.error.split("\n")[0]}` : ""}`);
+        lines.push(...hostBypassLines(item.hostBypass).map((line) => `       ${line}`));
+        const pairs = view.frames[item.index]?.actors ?? {};
+        for (const [actor, pair] of Object.entries(pairs)) {
+            if (step === undefined && actor !== item.actor)
+                continue;
+            for (const [side, choice] of [["before", pair.before], ["after", pair.after]])
+                lines.push(`       ${name(actor)} ${side}: ${choice.frame && choice.status === "captured" ? `frame ${choice.frame.id}` : choice.status} · ${choice.note}`);
+        }
+        for (const tx of recording.transactions.filter((entry) => entry.step === item.index))
+            lines.push(`       tx ${tx.label} on ${tx.chain}: ${tx.status}${tx.block ? ` in #${tx.block.number}` : ""}${tx.hash ? ` ${tx.hash}` : ""}`);
+        for (const observation of recording.observations.filter((entry) => entry.step === item.index && (step !== undefined || entry.at === "end")))
+            for (const chain of observation.chains)
+                lines.push(`       observed at step ${observation.at}: ${chain.label} best #${chain.best?.number ?? "?"} finalized #${chain.finalized?.number ?? "?"}${chain.error ? ` (error: ${chain.error})` : ""}`);
+        lines.push(...chainChangeLines(recording, item.index, step !== undefined, name));
+        lines.push(...consoleLines(recording, item.index, step !== undefined));
+        lines.push(...hostRequestLines(recording, item.index));
+        lines.push(...healthLines(recording, item.index, step !== undefined));
+    }
+    return lines.join("\n") + "\n";
+}
+export async function runRecordingsCommand(runtime, argv, out = (text) => process.stdout.write(text)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            config: { type: "string" },
+            json: { type: "boolean" },
+            step: { type: "string" },
+            timings: { type: "boolean" },
+            factor: { type: "string" },
+            "min-gap-ms": { type: "string" },
+            "min-samples": { type: "string" },
+        },
+    });
+    if (values.help) {
+        out(RECORDINGS_USAGE + "\n");
+        return 0;
+    }
+    if (positionals.length > 1 || (values.step !== undefined && !positionals.length)) {
+        out(`${positionals.length > 1 ? `Unexpected arguments: ${positionals.slice(1).join(" ")}` : "--step needs a recording id"}\n${RECORDINGS_USAGE}\n`);
+        return 2;
+    }
+    const limitFlags = values.factor !== undefined || values["min-gap-ms"] !== undefined || values["min-samples"] !== undefined;
+    if ((values.timings || limitFlags) && (!positionals.length || values.step !== undefined || (limitFlags && !values.timings))) {
+        out(`${!positionals.length ? "--timings needs a recording id" : values.step !== undefined ? "--timings and --step are separate views" : "--factor, --min-gap-ms and --min-samples go with --timings"}\n${RECORDINGS_USAGE}\n`);
+        return 2;
+    }
+    const step = values.step === undefined ? undefined : Number(values.step);
+    if (step !== undefined && (!Number.isInteger(step) || step < 1)) {
+        out(`--step must be a step number from 1, not ${values.step}\n`);
+        return 2;
+    }
+    await runtime.load();
+    const id = positionals[0];
+    if (!id) {
+        const listing = await runtime.recordings();
+        out(values.json ? JSON.stringify(listing, null, 2) + "\n" : renderListing(listing));
+        return 0;
+    }
+    if (values.timings) {
+        const number = (flag, value) => {
+            if (value === undefined)
+                return undefined;
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed))
+                throw new Error(`${flag} must be a number, not ${value}`);
+            return parsed;
+        };
+        const factor = number("--factor", values.factor);
+        const minimumGapMs = number("--min-gap-ms", values["min-gap-ms"]);
+        const minimumSamples = number("--min-samples", values["min-samples"]);
+        const report = await runtime.recordingSpeed({
+            id,
+            ...(factor !== undefined ? { factor } : {}),
+            ...(minimumGapMs !== undefined ? { minimumGapMs } : {}),
+            ...(minimumSamples !== undefined ? { minimumSamples } : {}),
+        });
+        out(values.json ? JSON.stringify(report, null, 2) + "\n" : renderStepSpeed(report));
+        return 0;
+    }
+    const view = await runtime.recording(id);
+    if (step !== undefined && step > view.recording.steps.length) {
+        out(`Recording ${id} has steps 1-${view.recording.steps.length}\n`);
+        return 2;
+    }
+    out(values.json ? JSON.stringify(step === undefined ? view : { ...view, frames: [view.frames[step - 1]] }, null, 2) + "\n" : renderRecording(view, step === undefined ? undefined : step - 1));
+    return 0;
+}

package/entrypoints/cli/src/release/notices.d.ts

@@ -0,0 +1,87 @@
+import type { EnvironmentVariables } from "@parity/product-lab/ports/system";
+import { type ReleaseNotice } from "@parity/product-lab/domain/releases";
+/** The published package; the workspace's own packages (and the eval stand-in) never check or announce. */
+export declare const PUBLISHED_PACKAGE = "@parity/product-lab";
+/** Either variable, set to anything but `0` or `false`, turns the registry check off (what is new still shows). */
+export declare const UPDATE_CHECK_OPT_OUT: readonly ["PRODUCT_LAB_NO_UPDATE_CHECK", "NO_UPDATE_NOTIFIER"];
+export declare const UPGRADE_FIX = "npx --no-install product-lab upgrade";
+/** Set to anything but `0` or `false`, runs a version below the published minimum anyway (an emergency, not a habit). */
+export declare const BELOW_MINIMUM_OVERRIDE = "PRODUCT_LAB_ALLOW_BELOW_MINIMUM";
+export declare const CHECK_INTERVAL_MS: number;
+export declare const REGISTRY_TIMEOUT_MS = 3000;
+export interface OwnPackage {
+    readonly name: string;
+    readonly version: string;
+    /** The directory of its package.json, where CHANGELOG.md ships. */
+    readonly root: string;
+}
+/** The package this CLI ships in: the nearest package.json above this file. */
+export declare function ownPackage(from?: string): OwnPackage | undefined;
+export interface ReleaseNoticesOptions {
+    env: EnvironmentVariables;
+    /** Where the command runs; its repository (the nearest directory with `.git`) keys the version last used. */
+    cwd: string;
+    /** Default: the package this file ships in. */
+    own?: OwnPackage;
+    /** Default: `release-check.json` in the shared cache (PRODUCT_LAB_CACHE_DIR, XDG_CACHE_HOME, ~/.cache/product-lab). */
+    stateFile?: string;
+    now?: () => number;
+    fetcher?: typeof fetch;
+    /** The bound on each registry request. Default REGISTRY_TIMEOUT_MS. */
+    registryTimeoutMs?: number;
+}
+/**
+ * Whether this runs in CI, by the variables CI services set: `CI` or `CONTINUOUS_INTEGRATION` (anything but `0` or
+ * `false`), `BUILD_NUMBER` or `RUN_ID` (any value; Jenkins, TeamCity and others set no `CI`). An explicit `CI=false` or
+ * `CI=0` means not CI, whatever else is set.
+ */
+export declare function inCi(env: EnvironmentVariables): boolean;
+/** The repository `cwd` belongs to: the nearest directory with `.git`, else `cwd` itself. */
+export declare function repositoryRoot(cwd: string): string;
+/** One command's view of product-lab's versions. */
+export declare class ReleaseNotices {
+    private readonly options;
+    private readonly own;
+    private readonly stateFile;
+    private readonly repository;
+    private readonly now;
+    /** Aborted by stop(): a registry check in flight is abandoned. */
+    private readonly stopping;
+    constructor(options: ReleaseNoticesOptions);
+    /** Off in CI (nobody reads it, and a run must not depend on the registry) and outside the published package. */
+    get enabled(): boolean;
+    /** The registry check runs unless a variable turns it off. */
+    get checks(): boolean;
+    /**
+     * What to say now, or undefined when there is nothing. `person`: only a newer version not announced in the last
+     * day (a terminal line); without it, every newer version (the MCP server and the lab window show it quietly).
+     */
+    notice(options?: {
+        person?: boolean;
+    }): ReleaseNotice | undefined;
+    /**
+     * The published minimum when this version is below it (and the override is not set), else undefined. Known only
+     * from a registry check, so never in CI or with the check turned off.
+     */
+    belowMinimum(): {
+        minimum: string;
+        message: string;
+    } | undefined;
+    /** Record that this repository used this version (what is new was shown, or there was nothing to show). */
+    markSeen(): void;
+    /** Record that a person was told about `version`: not again for a day. */
+    markAnnounced(version: string): void;
+    /**
+     * Abandon a registry check in flight: the command has finished, and a slow or silent registry must not keep the
+     * process alive (a request holds its socket until it ends). The check's claim is given back, so the next
+     * long-running command asks again.
+     */
+    stop(): void;
+    /**
+     * Ask the registry for the dist-tags when the last check is a day old. Bounded by REGISTRY_TIMEOUT_MS and by stop();
+     * a 404 (not published), an error or no network says nothing and waits for the next day.
+     */
+    refresh(): Promise<void>;
+    private read;
+    private write;
+}