@crvouga/atlas 0.13.0 → 0.15.0

package/dist/reports/src/reports-explorer-route.d.ts

@@ -82,6 +82,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                         height?: number | undefined;
                         durationMs?: number | undefined;
                         description?: string | undefined;
+                        tags?: string[] | undefined;
                         at?: {
                             [x: string]: import("hono/utils/types").JSONValue;
                             step?: string | undefined;
@@ -125,6 +126,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -181,6 +183,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -247,6 +250,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -352,6 +356,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -395,6 +400,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                     height?: number | undefined;
                                     durationMs?: number | undefined;
                                     description?: string | undefined;
+                                    tags?: string[] | undefined;
                                     at?: {
                                         [x: string]: import("hono/utils/types").JSONValue;
                                         step?: string | undefined;
@@ -451,6 +457,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -517,6 +524,7 @@ export declare function createReportsExplorerApp(deps: ReportsExplorerDeps): imp
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;

package/dist/reports/src/reports-route.d.ts

@@ -120,6 +120,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                         height?: number | undefined;
                         durationMs?: number | undefined;
                         description?: string | undefined;
+                        tags?: string[] | undefined;
                         at?: {
                             [x: string]: import("hono/utils/types").JSONValue;
                             step?: string | undefined;
@@ -163,6 +164,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -219,6 +221,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -285,6 +288,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -390,6 +394,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                             height?: number | undefined;
                             durationMs?: number | undefined;
                             description?: string | undefined;
+                            tags?: string[] | undefined;
                             at?: {
                                 [x: string]: import("hono/utils/types").JSONValue;
                                 step?: string | undefined;
@@ -433,6 +438,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                     height?: number | undefined;
                                     durationMs?: number | undefined;
                                     description?: string | undefined;
+                                    tags?: string[] | undefined;
                                     at?: {
                                         [x: string]: import("hono/utils/types").JSONValue;
                                         step?: string | undefined;
@@ -489,6 +495,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;
@@ -555,6 +562,7 @@ export declare function createReportsApp(deps: ReportsAppDeps): import("hono/hon
                                 height?: number | undefined;
                                 durationMs?: number | undefined;
                                 description?: string | undefined;
+                                tags?: string[] | undefined;
                                 at?: {
                                     [x: string]: import("hono/utils/types").JSONValue;
                                     step?: string | undefined;

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

@@ -1,25 +1,3 @@
-/**
- * @module Test catalog, history and runs
- *
- * What a person or an agent asks of a report once it holds more than a handful of checks: every test with where it ran,
- * how it went over time and how long it takes; the specs, domains, environments and producers they fall under; the CI
- * runs that produced them and which tests each one ran.
- *
- * - `TestHistory` keeps every recorded result of every test (bounded per test) and every run's results, folded in one
- *   layer at a time, in any order, with the same outcome. It never decides a status: the current status of a test is
- *   always the report's winner (`combineEvidence`), and history only describes how it got there.
- * - `testCatalog` turns the report's winners (plus a history, when there is one) into a `TestCatalog`: a summary with
- *   insights (slowest, flaky, failing), facets to filter by, and the tests that match a `TestQuery`.
- * - `testHistory`, `runList` and `runDetail` answer for one test, every run, and one run.
- * - `catalogMarkdown`, `historyMarkdown`, `runsMarkdown` and `runMarkdown` say the same in Markdown, for an agent or a
- *   terminal.
- *
- * A test is a check identity (its spec path and id) regardless of producer, environment and parameters; each of those
- * combinations is one of its results. A result that is not `passed` is never counted as a pass, and a test with no
- * completed result has no pass rate.
- *
- * @see docs/server.md#reading-the-report-as-an-agent
- */
 import type { EvidenceStatus, SpecEntry } from './explorer-types.js';
 import type { EvidenceSummary, LayerEvidence, LayerHeader, LayerRow, StatusCounts } from './evidence-types.js';
 import { RecordedSpecs } from './recorded-specs.js';
@@ -116,6 +94,10 @@ export type TestSummary = {
     readonly outcomes: readonly TestOutcome[];
     readonly stats: TestStats;
     readonly tags: readonly string[];
+    /** The normalized tags of the attachments of its current results (`demo`, shown as `#demo`). Never inherited from a check or run; the `tags` above are. Absent in documents of older servers. */
+    readonly artifactTags?: readonly string[];
+    /** The normalized tags its attachments inherit from their check and run (those of the results that have attachments), apart from `artifactTags`. What an inherited artifact query also matches. */
+    readonly inheritedArtifactTags?: readonly string[];
     readonly labels: Readonly<Record<string, string>>;
     /** What its current results carry: attachments, steps, retries, and the kinds of attachment. */
     readonly evidence: {
@@ -187,6 +169,8 @@ export type CatalogFacets = {
         readonly counts: StatusCounts;
     })[];
     readonly tags: readonly FacetValue[];
+    /** The tags of attachments, normalized. Absent in documents of older servers. */
+    readonly artifactTags?: readonly FacetValue[];
     readonly branches: readonly FacetValue[];
     readonly labels: Readonly<Record<string, readonly FacetValue[]>>;
 };
@@ -206,6 +190,10 @@ export type TestQuery = {
     /** Spec paths (`specs/...`). */
     readonly spec?: readonly string[];
     readonly tag?: readonly string[];
+    /** Only tests with an attachment carrying this tag (`demo` and `#demo` are the same), not counting tags inherited from a check or run: the exact artifact query. `tag` is the inherited one. */
+    readonly artifactTag?: readonly string[];
+    /** With `artifactTag`: also match the tags an attachment inherits from its check and run (a recording without a tag of its own under a run tagged `demo`). Default false: the exact query. */
+    readonly inherited?: boolean;
     /** Only tests recorded in this run (a key from `runList`). */
     readonly run?: string;
     readonly sort?: TestSort;
@@ -234,10 +222,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 +287,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
@@ -380,7 +384,7 @@ export declare function testHistory(model: CatalogModel, key: string): TestHisto
 export declare function runList(history: TestHistory, version: string, limit?: number): RunList;
 /** One run with every result it recorded, or null when no run has that key. */
 export declare function runDetail(history: TestHistory, version: string, key: string): RunDetail | null;
-/** Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`. */
+/** Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`, `artifactTag`, and `inherited=1`. */
 export declare function parseTestQuery(params: URLSearchParams): TestQuery;
 /** A duration for a person: `850 ms`, `12.3 s`, `4m 05s`. */
 export declare function formatMs(ms: number | null | undefined): string;

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

@@ -1,3 +1,26 @@
+/**
+ * @module Test catalog, history and runs
+ *
+ * What a person or an agent asks of a report once it holds more than a handful of checks: every test with where it ran,
+ * how it went over time and how long it takes; the specs, domains, environments and producers they fall under; the CI
+ * runs that produced them and which tests each one ran.
+ *
+ * - `TestHistory` keeps every recorded result of every test (bounded per test) and every run's results, folded in one
+ *   layer at a time, in any order, with the same outcome. It never decides a status: the current status of a test is
+ *   always the report's winner (`combineEvidence`), and history only describes how it got there.
+ * - `testCatalog` turns the report's winners (plus a history, when there is one) into a `TestCatalog`: a summary with
+ *   insights (slowest, flaky, failing), facets to filter by, and the tests that match a `TestQuery`.
+ * - `testHistory`, `runList` and `runDetail` answer for one test, every run, and one run.
+ * - `catalogMarkdown`, `historyMarkdown`, `runsMarkdown` and `runMarkdown` say the same in Markdown, for an agent or a
+ *   terminal.
+ *
+ * A test is a check identity (its spec path and id) regardless of producer, environment and parameters; each of those
+ * combinations is one of its results. A result that is not `passed` is never counted as a pass, and a test with no
+ * completed result has no pass rate.
+ *
+ * @see docs/server.md#reading-the-report-as-an-agent
+ */
+import { displayTag, normalizeTag, normalizeTags } from './artifact-tags.js';
 import { checkSlots } from './evidence-view.js';
 import { combineEvidence, emptyCounts, slotKey, specPath as normalSpecPath } from './layer-merge.js';
 import { RecordedSpecs } from './recorded-specs.js';
@@ -8,8 +31,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 +126,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.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;
         }
-        run.end = Math.max(run.end, layer.recordedAtMs);
+        // 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 +267,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,
@@ -319,15 +360,22 @@ function outcomeOf(result) {
 function summaryOf(slot, history, known) {
     const outcomes = slot.outcomes.map(outcomeOf);
     const tags = new Set();
+    const artifactTags = new Set();
+    const inheritedTags = new Set();
     const labels = {};
     let attachments = 0, steps = 0, attempts = 0;
     const roles = new Set();
-    for (const outcome of outcomes) {
+    for (const [at, outcome] of outcomes.entries()) {
         const evidence = outcome.evidence;
         if (!evidence)
             continue;
+        if (evidence.attachments > 0)
+            for (const tag of normalizeTags([...evidence.tags, ...(slot.outcomes[at]?.layer.evidence?.tags ?? [])]))
+                inheritedTags.add(tag);
         for (const tag of evidence.tags)
             tags.add(tag);
+        for (const tag of evidence.artifactTags ?? [])
+            artifactTags.add(tag);
         Object.assign(labels, evidence.labels);
         attachments += evidence.attachments;
         steps += evidence.steps;
@@ -348,6 +396,8 @@ function summaryOf(slot, history, known) {
         outcomes,
         stats: statsOf(history?.of(slot.key) ?? [], outcomes, tagList, labels),
         tags: tagList,
+        ...(artifactTags.size ? { artifactTags: [...artifactTags].sort() } : {}),
+        ...([...inheritedTags].some(tag => !artifactTags.has(tag)) ? { inheritedArtifactTags: [...inheritedTags].filter(tag => !artifactTags.has(tag)).sort() } : {}),
         labels,
         evidence: { attachments, steps, attempts, roles: [...roles].sort() },
         lastRecordedAtMs: slot.latestAtMs,
@@ -357,7 +407,7 @@ function summaryOf(slot, history, known) {
 /** The lowercase text a search matches a test against: title, id, spec, domain, tags, labels, environments and producers. */
 export function haystackOf(test) {
     return [
-        test.title, test.id, test.specPath ?? '', test.spec?.title ?? '', test.spec?.domain ?? '', ...test.tags,
+        test.title, test.id, test.specPath ?? '', test.spec?.title ?? '', test.spec?.domain ?? '', ...test.tags, ...(test.artifactTags ?? []).map(displayTag),
         ...Object.entries(test.labels).flatMap(([key, value]) => [key, value]), ...test.environments, ...test.producers,
     ].join('\n').toLowerCase();
 }
@@ -463,6 +513,7 @@ export function catalogModel(layers, sources = {}) {
         domains: facet(tests, test => [test.spec?.domain || '(no spec)']),
         specs: [...specGroups].map(([, list]) => { const g = group(list[0].spec.path, list); return { ...list[0].spec, tests: g.tests, counts: g.counts }; }).sort((a, b) => compareText(a.domain, b.domain) || compareText(a.title, b.title)),
         tags: facet(tests, test => test.tags),
+        artifactTags: facet(tests, test => test.artifactTags ?? []),
         branches: facet(tests, test => test.stats.branches),
         labels: Object.fromEntries([...labelKeys].sort().map(key => [key, facet(tests, test => (test.labels[key] === undefined ? [] : [test.labels[key]]))])),
     };
@@ -497,6 +548,8 @@ export function matchesQuery(model, test, query, inRun) {
         return false;
     if (query.tag?.length && !query.tag.some(tag => test.tags.includes(tag)))
         return false;
+    if (query.artifactTag?.length && !query.artifactTag.some(tag => { const wanted = normalizeTag(tag); return wanted !== null && ((test.artifactTags?.includes(wanted) ?? false) || (query.inherited === true && (test.inheritedArtifactTags?.includes(wanted) ?? false))); }))
+        return false;
     if (inRun && !inRun.has(test.key))
         return false;
     return true;
@@ -528,7 +581,7 @@ export function runDetail(history, version, key) {
     const found = history.run(key);
     return found ? { schemaVersion: TEST_CATALOG_VERSION, version, ...found } : null;
 }
-/** Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`. */
+/** Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`, `artifactTag`, and `inherited=1`. */
 export function parseTestQuery(params) {
     const many = (name) => params.getAll(name).flatMap(value => value.split(',')).map(value => value.trim()).filter(Boolean);
     const number = (name) => { const value = params.get(name); return value !== null && /^\d+$/.test(value) ? Number(value) : undefined; };
@@ -537,11 +590,13 @@ export function parseTestQuery(params) {
     const q = params.get('q');
     if (q)
         query.q = q;
-    for (const name of ['status', 'environment', 'producer', 'domain', 'spec', 'tag']) {
+    for (const name of ['status', 'environment', 'producer', 'domain', 'spec', 'tag', 'artifactTag']) {
         const values = many(name);
         if (values.length)
             query[name] = values;
     }
+    if (['1', 'true'].includes(params.get('inherited') ?? ''))
+        query.inherited = true;
     const run = params.get('run');
     if (run)
         query.run = run;
@@ -615,6 +670,7 @@ export function historyMarkdown(document) {
         `- Results: ${test.stats.results} recorded, ${test.stats.passed} passed, ${test.stats.failed} failed${test.stats.passRate === null ? '' : `, pass rate ${Math.round(test.stats.passRate * 100)}%`}, in ${test.stats.runs} runs`,
         `- Duration: ${d ? `avg ${formatMs(d.avgMs)}, p50 ${formatMs(d.p50Ms)}, p95 ${formatMs(d.p95Ms)}, min ${formatMs(d.minMs)}, max ${formatMs(d.maxMs)}, last ${formatMs(d.lastMs)}` : 'not measured'}`,
         ...(test.tags.length ? [`- Tags: ${test.tags.join(', ')}`] : []),
+        ...(test.artifactTags?.length ? [`- Artifact tags: ${test.artifactTags.map(displayTag).join(', ')}`] : []),
         ...(Object.keys(test.labels).length ? [`- Labels: ${Object.entries(test.labels).map(([k, v]) => `${k}=${v}`).join(', ')}`] : []),
         `- Evidence: ${test.evidence.attachments} attachments${test.evidence.roles.length ? ` (${test.evidence.roles.join(', ')})` : ''}, ${test.evidence.steps} steps`,
         '',
@@ -631,6 +687,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 +698,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 +707,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`}`,