@crvouga/atlas 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 0.14.0 (2026-10-28)
+
+### Features
+
+- identify local demo executions separately from branch and commit ([543bf9f](https://github.com/crvouga/atlas/commit/543bf9f00bacb3deb5d32d78c3b61437e04497df))
+
 ## 0.13.0 (2026-10-28)
 
 ### Features

package/dist/playwright-reporter/src/index.d.ts

@@ -35,6 +35,17 @@ export type AtlasPlaywrightReporterOptions = {
     readonly branch?: string;
     /** Where to read the CI run. Default the GitHub Actions run (or the CI's own run URL variable). */
     readonly runUrl?: string;
+    /**
+     * Names this execution, for a local or manual run with no CI run URL: every shard and project that gets the same `id`
+     * is one run, and the next invocation gets another. Default: `ATLAS_RUN_ID` (and `ATLAS_RUN_TITLE`) when set. Only
+     * groups and labels runs; it never changes what a check is or which result wins.
+     */
+    readonly run?: {
+        readonly id: string;
+        readonly title?: string;
+        readonly startedAtMs?: number;
+        readonly endedAtMs?: number;
+    };
     /** The spec a test belongs to, relative to the repository. Default: the `.feature` of a playwright-bdd test, else the test file. */
     readonly specPath?: (test: TestCase) => string | undefined;
     /** Paths are relative to this directory. Default the git root above Playwright's `rootDir`, else `rootDir`. */

package/dist/playwright-reporter/src/index.js

@@ -123,15 +123,16 @@ export default class AtlasPlaywrightReporter {
         }
         if (!this.store)
             return;
+        const run = options.run ?? (env.ATLAS_RUN_ID ? { id: env.ATLAS_RUN_ID, ...(env.ATLAS_RUN_TITLE ? { title: env.ATLAS_RUN_TITLE } : {}) } : undefined);
         try {
             const explicitSha = options.sha ?? env.ATLAS_SHA;
             const origin = detectOrigin(env);
             const sha = explicitSha ?? origin.sha;
             const freshness = detectFreshness({ sha, ci: origin.ci && !explicitSha });
-            this.identity = { sha, branch: options.branch ?? env.ATLAS_BRANCH ?? origin.branch, runUrl: options.runUrl ?? origin.runUrl, ...(freshness ? { freshness } : {}) };
+            this.identity = { sha, branch: options.branch ?? env.ATLAS_BRANCH ?? origin.branch, runUrl: options.runUrl ?? origin.runUrl, ...(run ? { run } : {}), ...(freshness ? { freshness } : {}) };
         }
         catch {
-            this.identity = { sha: options.sha ?? env.ATLAS_SHA ?? null, branch: options.branch ?? env.ATLAS_BRANCH ?? null, runUrl: options.runUrl ?? null, freshness: 'unknown' };
+            this.identity = { sha: options.sha ?? env.ATLAS_SHA ?? null, branch: options.branch ?? env.ATLAS_BRANCH ?? null, runUrl: options.runUrl ?? null, ...(run ? { run } : {}), freshness: 'unknown' };
         }
     }
     specPathOf(test) {
@@ -195,6 +196,7 @@ export default class AtlasPlaywrightReporter {
                     sha: this.identity.sha,
                     branch: this.identity.branch,
                     runUrl: this.identity.runUrl,
+                    ...(this.identity.run ? { run: this.identity.run } : {}),
                     ...(this.identity.freshness ? { freshness: this.identity.freshness } : {}),
                     environment,
                     parameters: { ...parameters },

package/dist/reports/src/evidence-types.d.ts

@@ -9,6 +9,7 @@
  * @see docs/report-contract.md
  */
 import type { EvidenceMeasurement, EvidenceStatus } from './explorer-types.js';
+import type { LayerRun } from '../../schema/src/layer.js';
 import type { LayerParameters } from './layer-types.js';
 /** Where a recorded test's timeline and captured files are read from. */
 export type RecordingAddress = {
@@ -77,6 +78,8 @@ export type LayerHeader = {
     readonly parameters: LayerParameters;
     /** `modified`: recorded from a checkout with uncommitted changes; `unknown`: origin not captured; absent: clean. Advisory; never changes a status. */
     readonly freshness?: 'unknown' | 'modified';
+    /** The execution the producer named for it (one local or manual invocation), or absent. Grouping and display only; never part of the slot. */
+    readonly run?: LayerRun;
     /** Where this layer's recorded timelines and captured files are read from, or null when it has none. */
     readonly recording: RecordingAddress | null;
     /** From a spec run that has not been collected into a layer yet. */

package/dist/reports/src/layer-merge.d.ts

@@ -129,7 +129,7 @@ export declare function distinctEvidence(layers: readonly LayerEvidence[]): Laye
 /** Drops each mutable layer whose execution is already archived as an immutable one, and keeps one summary per id. */
 export declare function distinctLayers(layers: readonly LayerSummary[]): LayerSummary[];
 /**
- * A string equal for the mutable and the archived address of one execution: its producer, sha, time and parts.
+ * A string equal for the mutable and the archived address of one execution: its producer, sha, time, parts and, when the producer named one, its execution id.
  * Object key order is ignored at every depth, including check evidence and extensions; array order is preserved.
  * This is an advisory execution identity, not the content digest that addresses an immutable layer in storage.
  */

package/dist/reports/src/layer-merge.js

@@ -97,6 +97,7 @@ export function layerEvidence(summary, backend) {
     const layerSummaryEvidence = summarizeEvidence(summary, ...summary.parts);
     const layer = {
         ...(summary.freshness ? { freshness: summary.freshness } : {}),
+        ...(summary.run ? { run: summary.run } : {}),
         id: summary.id,
         backend,
         producer: summary.producer,
@@ -270,12 +271,12 @@ export function distinctLayers(layers) {
     return [...new Map(layers.filter(layer => archived(layer.id) || !kept.has(layerExecutionKey(layer))).map(layer => [layer.id, layer])).values()];
 }
 /**
- * A string equal for the mutable and the archived address of one execution: its producer, sha, time and parts.
+ * A string equal for the mutable and the archived address of one execution: its producer, sha, time, parts and, when the producer named one, its execution id.
  * Object key order is ignored at every depth, including check evidence and extensions; array order is preserved.
  * This is an advisory execution identity, not the content digest that addresses an immutable layer in storage.
  */
 export function layerExecutionKey(layer) {
-    return JSON.stringify([layer.producer, layer.sha, layer.recordedAtMs, orderedValue(layer.parts)]);
+    return JSON.stringify([layer.producer, layer.sha, layer.recordedAtMs, orderedValue(layer.parts), ...(layer.run ? [layer.run.id] : [])]);
 }
 /** Sort JSON objects recursively without changing array order or interpreting extension keys as prototypes. */
 function orderedValue(value) {

package/dist/reports/src/layer-types.d.ts

@@ -8,6 +8,7 @@
  *
  * @see docs/report-contract.md#the-layer-document
  */
+import type { LayerRun } from '../../schema/src/layer.js';
 import type { BundleIndex } from './bundle.js';
 import type { ReportPart, SpecEntry } from './explorer-types.js';
 import type { SourceRecord } from './protocol.js';
@@ -33,6 +34,8 @@ export type LayerSummary = LayerExtras & {
     readonly environment?: string | null;
     /** Provenance: the CI run that produced the layer, or `null`. Never part of the slot. */
     readonly runUrl: string | null;
+    /** The execution (one invocation of a local or manual run) the layer belongs to, when the producer named one. Grouping and display only; never part of the slot. Absent: the run is told by `runUrl`, else `branch@sha`. */
+    readonly run?: LayerRun;
     /** Free choices that make a result its own slot. The `environment` parameter is read as the environment (see `layerPlace`). */
     readonly parameters: LayerParameters;
     /** The specs the layer was recorded against, with fingerprints of their text. */

package/dist/reports/src/publish-checks.js

@@ -103,6 +103,7 @@ export async function publishChecks(store, input, options = {}) {
         sha: args.sha,
         branch: args.branch,
         runUrl: args.runUrl,
+        ...(args.run ? { run: args.run } : {}),
         ...(environment ? { environment } : {}),
         parameters: Object.fromEntries(Object.entries(parameters).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
         specs: args.specs,

package/dist/reports/src/report-cli.d.ts

@@ -13,7 +13,7 @@
  * @see docs/agents.md
  */
 /** The text `atlas report --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of the command reference in `docs/reference/cli.md`. */
-export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
+export declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--run-id <id>] [--run-title <t>] [--run-started-at <iso|ms>] [--run-ended-at <iso|ms>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--run-id <id>] [--run-title <t>]\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). Select a project on an Atlas node with --project <slug> or ATLAS_PROJECT. This scopes specs, reports and recordings together.\n  When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --run-id <id>   name this execution (a local or manual run with no CI run URL; also ATLAS_RUN_ID).\n                            Layers that share an id are one run, however many shards or batches uploaded them;\n                            another invocation at the same commit gets another id. Never part of what a check is\n            --run-title <t> a human name for the run (also ATLAS_RUN_TITLE); --run-started-at and --run-ended-at\n                            record when it ran. Without --run-id a run is its CI run URL, else branch@sha\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
 type Env = Readonly<Record<string, string | undefined>>;
 type Git = (args: readonly string[]) => string | null;
 /** What `reportMain` is given besides arguments: where output goes (`out`), and, for tests and embedding, the environment, working directory, git, clock and standard input (`stdin`, where `stream` reads checks from). Defaults are the real ones. */

package/dist/reports/src/report-cli.js

@@ -38,12 +38,14 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
   atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]
                        ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )
                        [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]
+                       [--run-id <id>] [--run-title <t>] [--run-started-at <iso|ms>] [--run-ended-at <iso|ms>]
                        [--spec <path> | --specs <dir>] [--upload-run]
                        [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]
                        [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...
                        [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]
   atlas report stream  [--store <dir|s3://…|https://atlas.example.com>] --producer <name> [--environment <name>]
                        [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...
+                       [--run-id <id>] [--run-title <t>]
                        [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)
   atlas report status  [--store <dir|s3://…|id=url>]... [--backends <module>]
                        [--specs <dir>] [--format text|json|markdown]
@@ -64,6 +66,11 @@ export const REPORT_USAGE = `atlas report — layered evidence for any kind of s
             --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or
                             file name the report gives; also publishes the specs themselves, so the
                             node can show them without a checkout
+            --run-id <id>   name this execution (a local or manual run with no CI run URL; also ATLAS_RUN_ID).
+                            Layers that share an id are one run, however many shards or batches uploaded them;
+                            another invocation at the same commit gets another id. Never part of what a check is
+            --run-title <t> a human name for the run (also ATLAS_RUN_TITLE); --run-started-at and --run-ended-at
+                            record when it ran. Without --run-id a run is its CI run URL, else branch@sha
             --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer
             --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive
                               (screenshots, videos and traces of a single test go in its CTRF or checks file)
@@ -151,15 +158,32 @@ function linkSpec(spec) {
     const named = /^([^=/:]+)=(.+)$/.exec(spec);
     return named ? { name: named[1], url: named[2] } : { url: spec };
 }
-function parseTime(text) {
+function parseTime(text, flag = '--recorded-at') {
     if (text === undefined)
         return null;
     const numeric = Number(text);
     const parsed = Number.isFinite(numeric) ? numeric : Date.parse(text);
     if (!Number.isFinite(parsed) || parsed < 0)
-        throw new Error(`--recorded-at takes an ISO date or epoch milliseconds (got "${text}")`);
+        throw new Error(`${flag} takes an ISO date or epoch milliseconds (got "${text}")`);
     return parsed;
 }
+/**
+ * The execution the producer named, from `--run-id`, `--run-title`, `--run-started-at`, `--run-ended-at` and then
+ * `ATLAS_RUN_ID` / `ATLAS_RUN_TITLE`, laid over a `run` the checks file gave. `undefined` when nothing names one, so the
+ * documented grouping (CI run URL, else branch@sha) applies. A title or time without an id is refused: it would have nothing to belong to.
+ */
+function executionOf(rest, env, given) {
+    const file = typeof given === 'object' && given !== null && !Array.isArray(given) ? given : {};
+    const id = value(rest, 'run-id') ?? env.ATLAS_RUN_ID ?? (typeof file.id === 'string' ? file.id : undefined);
+    const title = value(rest, 'run-title') ?? env.ATLAS_RUN_TITLE;
+    const startedAtMs = parseTime(value(rest, 'run-started-at'), '--run-started-at');
+    const endedAtMs = parseTime(value(rest, 'run-ended-at'), '--run-ended-at');
+    if (id === undefined && (title !== undefined || startedAtMs !== null || endedAtMs !== null))
+        throw new Error('--run-title, --run-started-at and --run-ended-at go with --run-id <id> (or ATLAS_RUN_ID): a run needs an identity first');
+    if (id === undefined)
+        return undefined;
+    return { ...file, id, ...(title !== undefined ? { title } : {}), ...(startedAtMs !== null ? { startedAtMs } : {}), ...(endedAtMs !== null ? { endedAtMs } : {}) };
+}
 function ingest(argv, base) {
     const read = (file) => readFileSync(path.resolve(base, file), 'utf8');
     const sources = ['ctrf', 'junit', 'manifest', 'checks'].filter(name => value(argv, name) !== undefined);
@@ -258,6 +282,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
         }
         const labels = { ...(ingested.labels ?? {}), ...(extra.labels ?? {}), ...Object.fromEntries(values(rest, 'label').map(pair => keyValue(pair, '--label'))) };
         const links = [...(extra.links ?? []), ...values(rest, 'link').map(linkSpec)];
+        const execution = executionOf(rest, env, extra.run);
         const layer = await publishChecks(target.store, {
             ...extra,
             producer,
@@ -272,6 +297,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
             ...(value(rest, 'title') ?? extra.title ? { title: (value(rest, 'title') ?? extra.title) } : {}),
             sha, branch,
             runUrl: value(rest, 'run-url') ?? extra.runUrl ?? origin.runUrl,
+            ...(execution ? { run: execution } : {}),
             ...(freshness ? { freshness } : {}),
             ...(value(rest, 'environment') ?? extra.environment ? { environment: (value(rest, 'environment') ?? extra.environment) } : {}),
             parameters: { ...(extra.parameters ?? {}), ...parameters }
@@ -329,6 +355,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
         const branch = value(rest, 'branch') ?? origin.branch;
         const freshness = detectFreshness({ sha, ci: origin.ci && !value(rest, 'sha') }, io.git);
         const environment = value(rest, 'environment');
+        const execution = executionOf(rest, env);
         const warnings = [];
         const reporter = createReporter({
             producer,
@@ -336,6 +363,7 @@ export async function reportMain(argv, io = { out: text => process.stdout.write(
             ...(value(rest, 'title') ? { title: value(rest, 'title') } : {}),
             sha, branch,
             runUrl: value(rest, 'run-url') ?? origin.runUrl,
+            ...(execution ? { run: execution } : {}),
             ...(freshness ? { freshness } : {}),
             ...(environment ? { environment } : {}),
             parameters: Object.fromEntries(values(rest, 'param').map(pair => keyValue(pair, '--param')))

package/dist/reports/src/reporter.d.ts

@@ -13,7 +13,7 @@ import { type PublishChecksInput } from '../../schema/src/layer.js';
 import type { ObjectStore } from './object-store.js';
 type Check = PublishChecksInput['checks'][number];
 /** What every layer of one stream shares: who is reporting, from where. Whatever `publishChecks` takes, except the checks and the time. */
-export type ReporterIdentity = Pick<PublishChecksInput, 'producer' | 'kind' | 'title' | 'sha' | 'branch' | 'runUrl' | 'environment' | 'parameters' | 'freshness' | 'specs' | 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>;
+export type ReporterIdentity = Pick<PublishChecksInput, 'producer' | 'kind' | 'title' | 'sha' | 'branch' | 'runUrl' | 'run' | 'environment' | 'parameters' | 'freshness' | 'specs' | 'tags' | 'labels' | 'links' | 'attachments' | 'annotations' | 'extensions'>;
 /** How a reporter sends: the `store` (a folder, S3, or `httpStore` for a server), how often (`flushMs`, `batchSize`), how hard it tries (`attempts`, `backoffMs`), what it tells (`onError`, `onPublished`), and the clock and sleep for tests. */
 export type ReporterOptions = {
     /** Where layers go: a directory, S3, or `httpStore` for an Atlas server. */

package/dist/reports/src/test-catalog.d.ts

@@ -234,10 +234,19 @@ export type TestHistoryDocument = {
     readonly test: TestSummary;
     readonly history: readonly TestResultEntry[];
 };
-/** A CI run (or any group of layers sharing a run URL, else a branch and commit): when, where, and how its tests went. */
+/**
+ * A run: the layers that name the same execution (`run.id`), else share a CI run URL, else a branch and commit. When,
+ * where, and how its tests went.
+ */
 export type RunSummary = {
-    /** Stable key: the run URL, or `branch@sha`. */
+    /** Stable key: `run:<id>` for an execution a producer named, else the run URL, else `branch@sha`. */
     readonly key: string;
+    /** The execution id a producer named for it, when it did. Layers that share it are one run, however many uploads they took; another invocation at the same commit has another. */
+    readonly runId?: string;
+    /** The human title the producer gave the execution (the newest layer's). Presentation only: the key, the commit and `freshness` are unaffected. */
+    readonly title?: string;
+    /** `modified` when any of its layers was recorded from a checkout with uncommitted changes, else `unknown` when any origin was not captured; absent when every layer is from a clean commit. Advisory; never changes a status. */
+    readonly freshness?: 'unknown' | 'modified';
     readonly runUrl: string | null;
     readonly branch: string | null;
     readonly sha: string | null;
@@ -290,8 +299,15 @@ export type RunDetail = {
     readonly run: RunSummary;
     readonly results: readonly RunResult[];
 };
-/** The run a layer belongs to: its run URL, else `branch@sha`, else `local`. Layers with the same key are one run. */
-export declare function runKey(layer: Pick<LayerHeader, 'runUrl' | 'branch' | 'sha'>): string;
+/**
+ * The run a layer belongs to: the execution its producer named (`run:<id>`), else its run URL, else `branch@sha`, else
+ * `local`. Layers with the same key are one run. Only grouping: it is never part of the slot a result fills.
+ */
+export declare function runKey(layer: Pick<LayerHeader, 'runUrl' | 'branch' | 'sha'> & {
+    readonly run?: {
+        readonly id: string;
+    };
+}): string;
 /**
  * Every recorded result of every test (the newest `HISTORY_PER_TEST` per test, leaving out `running` progress) and the
  * runs they came from. A run's results are read from that history, so memory follows the number of tests and not the age

package/dist/reports/src/test-catalog.js

@@ -8,8 +8,13 @@ export const HISTORY_PER_TEST = 100;
 const FAILURE_RANK = { passed: 0, 'not-run': 1, running: 2, failed: 3 };
 /** How tests are ordered. */
 export const TEST_SORTS = ['spec', 'title', 'recent', 'slowest', 'failures', 'flaky', 'runs'];
-/** The run a layer belongs to: its run URL, else `branch@sha`, else `local`. Layers with the same key are one run. */
+/**
+ * The run a layer belongs to: the execution its producer named (`run:<id>`), else its run URL, else `branch@sha`, else
+ * `local`. Layers with the same key are one run. Only grouping: it is never part of the slot a result fills.
+ */
 export function runKey(layer) {
+    if (layer.run?.id)
+        return `run:${layer.run.id}`;
     if (layer.runUrl)
         return layer.runUrl;
     if (layer.branch || layer.sha)
@@ -98,17 +103,29 @@ export class TestHistory {
         const key = runKey(layer);
         let run = this.#runs.get(key);
         if (!run) {
-            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0 };
+            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, firstAt: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0, runId: layer.run?.id, title: undefined, titledAt: 0, titledBy: '', freshness: undefined };
             this.#runs.set(key, run);
         }
         // A run is told by its first layer (by time, then id), whatever order its layers arrive in.
-        if (layer.recordedAtMs < run.start || (layer.recordedAtMs === run.start && layer.id < run.first)) {
-            run.start = layer.recordedAtMs;
+        if (layer.recordedAtMs < run.firstAt || (layer.recordedAtMs === run.firstAt && layer.id < run.first)) {
+            run.firstAt = layer.recordedAtMs;
             run.first = layer.id;
             run.branch = layer.branch;
             run.sha = layer.sha;
+            run.runUrl = layer.runUrl;
         }
-        run.end = Math.max(run.end, layer.recordedAtMs);
+        run.start = Math.min(run.start, layer.recordedAtMs, layer.run?.startedAtMs ?? Infinity);
+        run.end = Math.max(run.end, layer.recordedAtMs, layer.run?.endedAtMs ?? -Infinity);
+        // The newest title wins, so a person can rename a run by sending its id again with another title.
+        const title = layer.run?.title;
+        if (title && (layer.recordedAtMs > run.titledAt || (layer.recordedAtMs === run.titledAt && layer.id > run.titledBy))) {
+            run.title = title;
+            run.titledAt = layer.recordedAtMs;
+            run.titledBy = layer.id;
+        }
+        // Local changes are never lost to a clean sibling: the run is as modified as its most modified layer.
+        if (layer.freshness === 'modified' || (layer.freshness === 'unknown' && run.freshness !== 'modified'))
+            run.freshness = layer.freshness;
         run.producers.add(layer.producer);
         if (layer.environment)
             run.environments.add(layer.environment);
@@ -227,7 +244,8 @@ function runSummary(run, cells) {
     failed.sort((a, b) => compareText(a.i.slot, b.i.slot) || compareText(a.r.o.place, b.r.o.place) || compareText(a.r.k, b.r.k));
     const failing = failed.slice(0, 20).map(cell => ({ key: cell.i.slot, title: cell.i.title, environment: cell.r.o.environment, detail: (cell.r.t.split('\n')[0] ?? '').slice(0, 500) }));
     return {
-        key: run.key, runUrl: run.runUrl, branch: run.branch, sha: run.sha,
+        key: run.key, ...(run.runId ? { runId: run.runId } : {}), ...(run.title ? { title: run.title } : {}), ...(run.freshness ? { freshness: run.freshness } : {}),
+        runUrl: run.runUrl, branch: run.branch, sha: run.sha,
         startedAtMs: run.start, endedAtMs: run.end, spanMs: run.end - run.start,
         producers: [...run.producers].sort(), environments: [...run.environments].sort(),
         layers: run.layers, tests: tests.size, counts, totalDurationMs: measured ? total : null, failing,
@@ -631,6 +649,10 @@ export function historyMarkdown(document) {
         ...document.history.map(e => `| ${iso(e.at)} | ${e.environment ?? '—'} | ${e.status} | ${formatMs(e.durationMs)} | ${cell(e.branch ?? '—')} | ${e.sha?.slice(0, 10) ?? '—'} | ${cell(e.detail.split('\n')[0] ?? '')} |`),
     ].join('\n')}\n`;
 }
+/** What to say beside a commit that was not recorded from a clean checkout: nothing, ` (modified)` or ` (origin unknown)`. */
+function freshnessNote(freshness) {
+    return freshness === 'modified' ? ' (modified: local changes)' : freshness === 'unknown' ? ' (origin unknown)' : '';
+}
 /** The run list as Markdown. */
 export function runsMarkdown(list) {
     return `${[
@@ -638,7 +660,7 @@ export function runsMarkdown(list) {
         '',
         '| Ended | Branch | Commit | Environments | Tests | Passed | Failed | Not run | Span | Run |',
         '|---|---|---|---|---:|---:|---:|---:|---:|---|',
-        ...list.runs.map(r => `| ${iso(r.endedAtMs)} | ${cell(r.branch ?? '—')} | ${r.sha?.slice(0, 10) ?? '—'} | ${r.environments.join(', ') || '—'} | ${r.tests} | ${r.counts.passed} | ${r.counts.failed} | ${r.counts['not-run']} | ${formatMs(r.spanMs)} | ${cell(r.key)} |`),
+        ...list.runs.map(r => `| ${iso(r.endedAtMs)} | ${cell(r.branch ?? '—')} | ${r.sha?.slice(0, 10) ?? '—'}${freshnessNote(r.freshness)} | ${r.environments.join(', ') || '—'} | ${r.tests} | ${r.counts.passed} | ${r.counts.failed} | ${r.counts['not-run']} | ${formatMs(r.spanMs)} | ${cell(r.title ? `${r.title} (${r.key})` : r.key)} |`),
     ].join('\n')}\n`;
 }
 /** One run as Markdown. */
@@ -647,7 +669,8 @@ export function runMarkdown(detail) {
     return `${[
         `# Run ${run.key}`,
         '',
-        `- Branch ${run.branch ?? '—'}, commit ${run.sha ?? '—'}`,
+        ...(run.title ? [`- Title: ${run.title}`] : []),
+        `- Branch ${run.branch ?? '—'}, commit ${run.sha ?? '—'}${freshnessNote(run.freshness)}`,
         `- ${iso(run.startedAtMs)} to ${iso(run.endedAtMs)} (${formatMs(run.spanMs)}); ${run.layers} layers from ${run.producers.join(', ')}`,
         `- Environments: ${run.environments.join(', ') || '—'}`,
         `- ${run.tests} tests: ${counted(run.counts)}${run.totalDurationMs === null ? '' : `; ${formatMs(run.totalDurationMs)} of test time`}`,

package/dist/schema/src/api.d.ts

@@ -107,6 +107,12 @@ export declare const LayerHeaderSchema: z.ZodObject<{
         unknown: "unknown";
         modified: "modified";
     }>>;
+    run: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        startedAtMs: z.ZodOptional<z.ZodNumber>;
+        endedAtMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
     recording: z.ZodNullable<z.ZodUnknown>;
     live: z.ZodBoolean;
     counts: z.ZodRecord<z.ZodEnum<{
@@ -248,6 +254,12 @@ export declare const LayerEvidenceSchema: z.ZodObject<{
             unknown: "unknown";
             modified: "modified";
         }>>;
+        run: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            startedAtMs: z.ZodOptional<z.ZodNumber>;
+            endedAtMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
         recording: z.ZodNullable<z.ZodUnknown>;
         live: z.ZodBoolean;
         counts: z.ZodRecord<z.ZodEnum<{
@@ -326,6 +338,12 @@ export declare const EffectiveEvidenceSchema: z.ZodObject<{
                 unknown: "unknown";
                 modified: "modified";
             }>>;
+            run: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                startedAtMs: z.ZodOptional<z.ZodNumber>;
+                endedAtMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
             recording: z.ZodNullable<z.ZodUnknown>;
             live: z.ZodBoolean;
             counts: z.ZodRecord<z.ZodEnum<{
@@ -425,6 +443,12 @@ export declare const EffectiveDeltaSchema: z.ZodObject<{
                 unknown: "unknown";
                 modified: "modified";
             }>>;
+            run: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                startedAtMs: z.ZodOptional<z.ZodNumber>;
+                endedAtMs: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
             recording: z.ZodNullable<z.ZodUnknown>;
             live: z.ZodBoolean;
             counts: z.ZodRecord<z.ZodEnum<{
@@ -485,6 +509,12 @@ export declare const EvidencePageSchema: z.ZodObject<{
             unknown: "unknown";
             modified: "modified";
         }>>;
+        run: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            startedAtMs: z.ZodOptional<z.ZodNumber>;
+            endedAtMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
         recording: z.ZodNullable<z.ZodUnknown>;
         live: z.ZodBoolean;
         counts: z.ZodRecord<z.ZodEnum<{
@@ -1354,9 +1384,15 @@ export declare const TestHistorySchema: z.ZodObject<{
         }, z.core.$loose>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
-/** A run: the layers that share a run URL (else a branch and commit), with what they recorded. */
+/** A run: the layers that name the same execution (else share a run URL, else a branch and commit), with what they recorded. */
 export declare const ReportRunSchema: z.ZodObject<{
     key: z.ZodString;
+    runId: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    freshness: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        modified: "modified";
+    }>>;
     runUrl: z.ZodNullable<z.ZodString>;
     branch: z.ZodNullable<z.ZodString>;
     sha: z.ZodNullable<z.ZodString>;
@@ -1388,6 +1424,12 @@ export declare const RunListSchema: z.ZodObject<{
     total: z.ZodNumber;
     runs: z.ZodArray<z.ZodObject<{
         key: z.ZodString;
+        runId: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        freshness: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            modified: "modified";
+        }>>;
         runUrl: z.ZodNullable<z.ZodString>;
         branch: z.ZodNullable<z.ZodString>;
         sha: z.ZodNullable<z.ZodString>;
@@ -1419,6 +1461,12 @@ export declare const RunDetailSchema: z.ZodObject<{
     version: z.ZodString;
     run: z.ZodObject<{
         key: z.ZodString;
+        runId: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        freshness: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            modified: "modified";
+        }>>;
         runUrl: z.ZodNullable<z.ZodString>;
         branch: z.ZodNullable<z.ZodString>;
         sha: z.ZodNullable<z.ZodString>;

package/dist/schema/src/api.js

@@ -14,7 +14,7 @@
  * @see docs/server.md
  */
 import { z } from 'zod/v4';
-import { CheckSchema } from './layer.js';
+import { CheckSchema, LayerRunSchema } from './layer.js';
 /** One of the statuses a check has in a report: `passed`, `failed`, `running` (not finished) or `not-run`. Closed. */
 export const EvidenceStatusSchema = z.enum(['passed', 'failed', 'running', 'not-run']);
 /**
@@ -86,6 +86,7 @@ export const LayerHeaderSchema = z.looseObject({
     runUrl: z.string().nullable(),
     parameters: z.record(z.string(), z.string()).describe('Other choices that make a result its own slot'),
     freshness: z.enum(['unknown', 'modified']).optional().describe('`modified`: recorded from a checkout with uncommitted changes. `unknown`: origin not captured. Absent: clean'),
+    run: LayerRunSchema.optional().describe('The execution the producer named for it (one local or manual invocation). Grouping and display only; never part of the slot'),
     recording: z.unknown().nullable().describe('Where recorded timelines are read from, or null'),
     live: z.boolean(),
     counts: z.record(EvidenceStatusSchema, z.number().int().nonnegative()),
@@ -332,9 +333,12 @@ export const TestHistorySchema = z.looseObject({
     test: TestSummarySchema,
     history: z.array(TestResultEntrySchema)
 });
-/** A run: the layers that share a run URL (else a branch and commit), with what they recorded. */
+/** A run: the layers that name the same execution (else share a run URL, else a branch and commit), with what they recorded. */
 export const ReportRunSchema = z.looseObject({
-    key: z.string().describe('The run URL, or `branch@sha`. Pass it to `/api/reports/runs/detail?key=` or `/api/reports/tests?run=`'),
+    key: z.string().describe('`run:<id>` for an execution a producer named, else the run URL, else `branch@sha`. Pass it to `/api/reports/runs/detail?key=` or `/api/reports/tests?run=`'),
+    runId: z.string().optional().describe('The execution id the producer named, when it did. Layers that share it are one run however many uploads they took'),
+    title: z.string().optional().describe('The human title of the execution (the newest layer\'s). Presentation only: the key, commit and `freshness` are unaffected'),
+    freshness: z.enum(['unknown', 'modified']).optional().describe('`modified` when any layer of the run was recorded from a checkout with uncommitted changes; `unknown` when an origin was not captured; absent when all are clean. Shown beside the commit, never replaced by the title'),
     runUrl: z.string().nullable(), branch: z.string().nullable(), sha: z.string().nullable(),
     startedAtMs: z.number(), endedAtMs: z.number(), spanMs: z.number(),
     producers: z.array(z.string()), environments: z.array(z.string()),

package/dist/schema/src/layer.d.ts

@@ -60,6 +60,20 @@ export type CheckStatus = z.infer<typeof CheckStatusSchema>;
  * changes only with a new `schemaVersion`.
  */
 export declare const FRESHNESS: readonly ["unknown", "modified"];
+/**
+ * The execution a layer belongs to, named by the producer: one invocation of a local or manual run, which several
+ * layers (shards, batches, producers) may share. Presentation and history grouping only: it never takes part in the
+ * slot a result fills, in which result wins, or in a status. Absent, a run is told by its CI run URL, else `branch@sha`.
+ * Within one project, layers that carry the same `id` are one run; a later invocation gets another `id`.
+ */
+export declare const LayerRunSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    startedAtMs: z.ZodOptional<z.ZodNumber>;
+    endedAtMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+/** The execution of a layer, parsed from `LayerRunSchema`. */
+export type LayerRun = z.output<typeof LayerRunSchema>;
 /**
  * A number a check measured, such as a latency or a size, with its unit and an optional allowance. A measurement over
  * its `limit` is reported and never changes the check's status.
@@ -1211,6 +1225,12 @@ export declare const LayerDocumentSchema: z.ZodObject<{
         unknown: "unknown";
         modified: "modified";
     }>>;
+    run: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        startedAtMs: z.ZodOptional<z.ZodNumber>;
+        endedAtMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
     specs: z.ZodDefault<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         domain: z.ZodString;
@@ -2109,6 +2129,12 @@ export declare const PublishChecksSchema: z.ZodObject<{
         unknown: "unknown";
         modified: "modified";
     }>>;
+    run: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        startedAtMs: z.ZodOptional<z.ZodNumber>;
+        endedAtMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
     specs: z.ZodDefault<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         domain: z.ZodString;