diff --git a/.github/workflows/test-smokes-built.yml b/.github/workflows/test-smokes-built.yml
index c1b037ed137..dbf32e10668 100644
--- a/.github/workflows/test-smokes-built.yml
+++ b/.github/workflows/test-smokes-built.yml
@@ -105,14 +105,10 @@ jobs:
         shell: bash
         run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
 
-      - name: Compute version marker
+      - name: Compute build version
         id: version
         shell: bash
-        # BUILD METADATA version marker (+test.<date>): semver-valid and
-        # range-transparent for every 'quarto-required' gate, while still
-        # distinguishable from the dev sentinel 99.9.9. NEVER use a '-suffix'
-        # (prereleases fail plain ranges) or a 4th dot component (not semver).
-        run: echo "version=$(cat version.txt)+test.$(date +%Y%m%d)" >> "$GITHUB_OUTPUT"
+        run: echo "version=$(cat version.txt)" >> "$GITHUB_OUTPUT"
 
       - name: Build dist tarball
         uses: ./.github/actions/build-dist-tarball
diff --git a/.github/workflows/test-smokes.yml b/.github/workflows/test-smokes.yml
index 227a51966af..8dc61d8a1c6 100644
--- a/.github/workflows/test-smokes.yml
+++ b/.github/workflows/test-smokes.yml
@@ -476,6 +476,9 @@ jobs:
         env:
           # Useful as TinyTeX latest release is checked in run-test.sh
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # This loop owns the per-file ::group:: and ::error:: markers, so the
+          # test harness must not also emit annotations for this step.
+          QUARTO_TESTS_GHA_ORCHESTRATED: "1"
         run: |
           haserror=0
           failed_tests=()
@@ -514,6 +517,9 @@ jobs:
         env:
           # Useful as TinyTeX latest release is checked in run-test.sh
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # This loop owns the per-file ::group:: and ::error:: markers, so the
+          # test harness must not also emit annotations for this step.
+          QUARTO_TESTS_GHA_ORCHESTRATED: "1"
         run: |
           $haserror=$false
           $failed_tests=@()
diff --git a/dev-docs/ci-test-log-grouping-design.md b/dev-docs/ci-test-log-grouping-design.md
new file mode 100644
index 00000000000..37637ed2d7c
--- /dev/null
+++ b/dev-docs/ci-test-log-grouping-design.md
@@ -0,0 +1,475 @@
+# Design: GitHub Actions log grouping and failure surfacing for the full (non-bucketed) test run
+
+Status: **Phases 1–2 implemented** on this branch (Phase 1: annotations +
+step summary, `tests/test.ts` + `src/tools/github.ts`; Phase 2: per-file
+grouping, `tests/gha-grouping.ts` + the `tests/tools/check-gha-log.ts`
+checker; Phase 2.2: navigable, clustered step summaries + trimmed
+annotations). Phase 3 remains optional/unscheduled. The fork `workflow_dispatch`
+trial matrix (verification item 3) has been run (Linux + Windows, seeded
+failures, including the >10-failing-file case) and caught two real bugs, both
+fixed on this branch.
+
+Base: written on top of `test/smoke-tests-built-version` (the built-version
+testing branch — see `llm-docs/built-version-testing-architecture.md`). The
+non-bucketed full run this design targets is the smoke leg of
+`test-smokes-built.yml`, which calls `test-smokes.yml` with `buckets` empty
+(binary-mode default `smoke/`), landing in the flat-log path described below.
+The playwright and ff-matrix legs pass a non-empty `buckets`, so they take the
+per-file bucket loop instead — already grouped by #13787/#13807, orchestrated,
+and the harness stays silent there by design. The design is mode-agnostic: in both dev
+and binary mode the harness runs in the same `deno test` process, so marker
+emission points are identical.
+
+## Problem
+
+PR [#13787](https://github.com/quarto-dev/quarto-cli/pull/13787) and
+[#13807](https://github.com/quarto-dev/quarto-cli/pull/13807) made bucketed CI
+runs navigable by wrapping each test file in a `::group::` at the **workflow
+level** (`.github/workflows/test-smokes.yml`, the "Run Smoke Tests as a
+bucket on Linux/Windows" per-file loops). That works because the YAML loop
+runs `run-tests.sh <one file>` at a time, so group markers stay contiguous.
+
+The **default path** — `buckets == ''`, the "Run all Smoke Tests
+Linux/Windows" steps in `test-smokes.yml` — runs one giant `deno test` over
+every discovered test file (in binary mode, `run-tests.sh` defaults this to
+`smoke/`). No code on that path emits a single workflow command, so the log is
+thousands of flat lines and finding a failure means scrolling or text search.
+The smoke leg of `test-smokes-built.yml` reaches this path (empty `buckets`);
+the playwright and ff-matrix legs pass non-empty buckets and take the
+already-grouped bucket loop instead.
+
+Additional gaps that apply to *both* paths:
+
+- No `::error` annotations per failed test → failures are not visible on the
+  run summary page or PR checks tab (only the playwright integration test
+  emits one today, in `tests/integration/playwright-tests.test.ts`).
+- Nothing writes `GITHUB_STEP_SUMMARY` → no at-a-glance failure table.
+- `src/tools/github.ts` already contains a complete, correctly-escaping
+  workflow-command toolkit (`startGroup`/`endGroup`, `error`/`warning`/`notice`
+  with `escapeData`/`escapeProperty`, `isGitHubActions()` gating) that is dead
+  code for tests.
+
+## Hard constraints (GitHub Actions runner behavior)
+
+These drive the whole design; sources at the end.
+
+1. **Groups cannot nest.** A second `::group::` acts as an implicit
+   `::endgroup::` for the first; content after the inner group ends up
+   *outside any group*. Still unfixed
+   ([actions/toolkit#1001](https://github.com/actions/toolkit/issues/1001),
+   [actions/runner#802](https://github.com/actions/runner/issues/802)).
+   Consequence: **exactly one owner of grouping per code path**.
+2. A stray `::endgroup::` with no open group is harmless — safe to emit
+   defensively. (Shell caveat: `echo "::endgroup::"` clobbers `$?`; capture
+   exit codes first. Not an issue in TypeScript.)
+3. **Groups cannot be force-expanded** in the UI
+   ([actions/runner#1036](https://github.com/actions/runner/issues/1036)).
+   Failure detail must therefore land *outside* groups.
+4. **Annotation caps**: 10 `::error` + 10 `::warning` per **step**, 50 total
+   per **job**; excess silently dropped. Emit at most ~9 per-test error
+   annotations per step, then one aggregate.
+5. **`GITHUB_STEP_SUMMARY`**: 1 MiB per step, max 20 step summaries shown per
+   job. Content just under the limit can be *silently* dropped
+   ([actions/runner#4337](https://github.com/actions/runner/issues/4337)) —
+   self-truncate around ~512 KiB.
+6. Annotation messages do **not** render ANSI escapes — strip color codes
+   before putting captured output into `::error` text or the step summary.
+   ANSI *inside* group bodies is fine (the log viewer renders it).
+7. Parsing is line-based on stdout: commands work from any child process, but
+   must start at column 0 with a trailing newline. Multi-line messages use
+   `%0A` escaping (`escapeData` in `src/tools/github.ts` already does this).
+8. **Interleaved parallel output corrupts grouping** (process B's `::group::`
+   implicitly closes process A's). Today this is a non-issue: `run-tests.sh`
+   invokes `deno test` **without `--parallel`** (the generic-case invocation),
+   so test files run serially in one process. If `--parallel` is ever added, grouping must move
+   to buffer-and-flush emission (see Non-goals).
+
+## Spike results (verified with the pinned Deno v2.7.14)
+
+A standalone experiment (two test files, markers emitted from inside
+`Deno.test` bodies, one seeded failure) confirmed:
+
+- Marker lines printed from a test body are replayed **verbatim at column 0**
+  inside Deno's `------- output -------` / `------- post-test output -------`
+  framing, so the runner parses them.
+- Opening a group inside the *first test of a file* yields this net structure
+  (as the runner parses it):
+
+  ```text
+  running N tests from ./smoke/foo.test.ts     <- visible (outside groups)
+  [smoke] > first test name ...                <- visible
+  ::group::./smoke/foo.test.ts                 <- group opens
+     ...all per-test output and "... ok" lines of the file...
+  ::endgroup::                                 <- emitted by THIS file's unload
+  running M tests from ./smoke/bar.test.ts     <- visible
+  ```
+
+  i.e. per-file grouping collapses exactly the noise (per-test output blocks
+  and `ok` lines) while keeping Deno's own file headers visible as structure.
+  (Phase 2.1 later moved the group open earlier, to registration time, so the
+  `running N tests from` header and the first-test announcement now land
+  *inside* the group rather than above it — see "Phase 2.1" below.)
+- **Per-file module instances (correction, found via review #1986).** Deno
+  instantiates each test file's module graph separately: module state resets
+  between files, and each file gets its own `unload` event, flushed before
+  the next file's header. The original spike misread the inter-file
+  `::endgroup::` as the next file's first test closing the previous group
+  via shared state — it is actually the previous file's own unload. The
+  observable grouping output is identical either way (which is why the
+  probes looked right), but it means module-level state is per-FILE: any
+  genuinely per-step value (the annotation budget) must be coordinated
+  through the filesystem, and the grouping state machine's cross-file
+  transition close is in practice a no-op safety net (each instance only
+  ever sees its own file).
+- **On failure**, emitting `::endgroup::` from the failure path *before*
+  throwing puts the `FAILED` result line **outside** any group (visible in the
+  collapsed view), with the `::error` annotation adjacent. The next passing
+  test simply re-opens a group with the same file title (flat sequential
+  groups — allowed).
+- Each file's `unload` `::endgroup::` flushes **before** the next file's
+  header and before Deno's terminal `ERRORS` / `FAILURES` / summary
+  sections, so file groups never bleed into the next file and the end-of-run
+  failure details are never swallowed by the last group.
+
+Caveat: the exact attribution of output to Deno's `output` vs `post-test
+output` blocks is reporter behavior that may shift across Deno upgrades. It
+does not affect correctness of the net grouping shown above, but the
+verification checker (below) should run again on any Deno bump.
+
+## Design
+
+Three phases, each independently shippable and independently revertable.
+
+### Phase 1 — failure surfacing (no grouping; zero nesting risk)
+
+All changes in `tests/test.ts`, in the existing failure path that builds the
+`━━━ TEST FAILURE:` block (around line 327), reusing `src/tools/github.ts`
+helpers (gated on `isGitHubActions()`, so local runs are byte-identical):
+
+1. **`::error` annotation per failed test**:
+   `error(message, { file, title })` with
+   - `file`: repo-relative path of the test file (or the smoke-all `.qmd`
+     document when the failing test is a smoke-all doc — that is the file a
+     developer needs to open);
+   - `title`: the test name (`[smoke] > ...`);
+   - message: the repro command (`./run-tests.sh <path>`) plus the first ~20
+     lines of ANSI-stripped captured output, `%0A`-escaped.
+   - **Cap and ownership**: GitHub's 10-errors cap is per *workflow step*,
+     but bucket mode runs many `run-tests.sh` processes inside one step — a
+     per-process counter cannot implement a per-step budget there, and the
+     YAML bucket loop already emits its own `::error` per failed file.
+     Resolution: **the harness emits annotations only when it owns the step**
+     (`QUARTO_TESTS_GHA_ORCHESTRATED` unset — the default path). One
+     `deno test` process is the whole step there, BUT a module-level counter
+     is still NOT a step budget: Deno instantiates each test file's module
+     graph separately (verified on the pinned 2.7.14 — module state resets
+     per file and `unload` fires once per file), so the count is coordinated
+     through a sidecar counter file derived from `GITHUB_STEP_SUMMARY`
+     (unique per step, runner-writable; no locking needed — files run
+     sequentially without `--parallel`). Stop at 9; the failure that crosses
+     the cap emits the single aggregate `::error` inline as the step's 10th
+     and last annotation (no cross-file end-of-run hook exists to emit it
+     later).
+     In bucket mode the YAML loop keeps its per-file `::error` as today.
+     Known, accepted: if more than 10 bucket files fail, GitHub silently
+     drops the excess YAML annotations too — the step summary (below) is the
+     complete record in all modes; annotations are best-effort navigation.
+2. **Step summary row per failed test**: append to the file at
+   `$GITHUB_STEP_SUMMARY` (plain `Deno.writeTextFileSync(..., { append: true })`;
+   add a small `stepSummary()` helper to `src/tools/github.ts`):
+   - a table header once per test FILE (module state is per file — see the
+     spike correction above), then one row per failure: test file / test
+     name / duration. Per-failure `<details><summary>output</summary>`
+     blocks (ANSI-stripped excerpt + repro command) are **buffered and
+     flushed after that file's table at its per-file `unload` event** — GFM
+     ends a table at the first non-row line, so detail blocks cannot
+     interleave between rows. Each failing file therefore contributes its
+     own small table followed by its detail blocks. Accepted consequence:
+     on a hard process death (panic/OOM) pending unloads never fire and
+     buffered details are lost — but every row was already appended at
+     failure time, so the summary tables remain the complete record;
+   - the size budget must also be per *step*, not per process (bucket mode:
+     many processes append to the same summary file): before each append,
+     `stat` the summary file and degrade to name-only rows once it exceeds
+     ~512 KiB — the file size itself is the cross-process coordination, and
+     staying at ~half the 1 MiB limit dodges the silent-drop bug.
+
+Summary rows are emitted in **all** modes (cap-free, cross-process safe);
+annotations follow the ownership rule above. Each bucket *job* still gets its
+own summary page and annotation set.
+
+### Phase 2 — per-file grouping for the default path (env-gated harness emission)
+
+Owner rule: **the harness owns groups and annotations only when nothing else
+does.**
+
+- One env switch, `QUARTO_TESTS_GHA_ORCHESTRATED=1`, set by the two YAML
+  bucket loops in `test-smokes.yml` alongside their existing
+  `::group::Testing ${file}` — meaning "an outer orchestrator owns workflow
+  commands for this step": the harness emits **no groups and no
+  annotations** (step-summary rows are always emitted; they are cap-free and
+  size-coordinate via the summary file, see Phase 1). The #13807 bucket log
+  format does not change at all. Anyone else wrapping `run-tests.sh` in their
+  own group can use the same switch.
+- In `tests/test.ts`, a small module (or an extension of the existing
+  `src/tools/github.ts` import) tracks the current test-file origin:
+  - at the start of each test's `execute`, resolve the declaring file (the
+    harness already knows it — resolved from Deno's per-test `context.origin`
+    (`testFileFromOrigin`, `tests/test.ts`));
+  - on file change: `endGroup()` (defensive, harmless if none open) then
+    `startGroup(relativePath)`. NOTE (spike correction): since each test
+    file gets a fresh module instance, an instance in practice only ever
+    sees its own file — the transition close is a safety net for a future
+    Deno that shares module state again, not the working mechanism;
+  - on the failure path (before `fail()` throws): `endGroup()` and clear the
+    "open" flag, so the `FAILED` line and annotation land outside groups
+    (verified by the spike). Any failure that escapes the harness's
+    execute/verify path (init, prereq, setup, teardown — review #1991) must
+    also close the group before propagating to Deno: an outer catch around
+    the whole test body closes-and-rethrows, idempotently;
+  - `globalThis.addEventListener("unload", ...)`: fires once per test FILE
+    and closes that file's group — this is what actually ends a passing
+    file's group before the next file's header, and keeps the terminal
+    `ERRORS`/summary sections ungrouped (verified);
+  - every emission gated on
+    `isGitHubActions() && !Deno.env.get("QUARTO_TESTS_GHA_ORCHESTRATED")`.
+- **Closure policy: per-file closure at the file's own `unload`** (plus the
+  failure-path close). A pleasant consequence of per-file module instances:
+  a direct `Deno.test` file (no harness registration) running between two
+  harness files executes AFTER the previous file's unload closed its group —
+  foreign tests' output and `FAILED` lines land ungrouped, visible. The
+  stale-group swallowing originally accepted under "lazy closure" does not
+  occur in practice; invariant 3 stays scoped to harness-registered tests
+  only as a guard against Deno changing its module-instantiation model
+  (which the checker script would catch).
+- Granularity is **per test file**, matching Deno's own "running N tests
+  from ..." structure. Per-test granularity is the documented fallback if real
+  logs show files whose single collapsed group is still too coarse (e.g.
+  `smoke-all.test.ts` runs many documents as separate tests — if needed, treat
+  each smoke-all *document* as the boundary instead; the harness knows the
+  document path).
+
+#### Phase 2.1 — open the group at registration time
+
+Phase 2 opens a file's group inside the *body of its first test*, which
+leaves Deno's `running N tests from ...` header and that first test's
+announcement line above the group (the spike snippet above). Phase 2.1 moves
+the open earlier — to **registration (module-eval) time**, when the file's
+first `test(...)` call runs — so those reporter lines land inside the group.
+
+- At registration there is no `context.origin` yet, so the declaring file is
+  recovered from the call stack: `testFileUrlFromStack()`
+  (`tests/gha-grouping.ts`, kept pure so it is unit-testable with synthetic
+  stacks) returns the first `.test.ts` frame's `file://` URL, and
+  `testFileFromStack()` (`tests/test.ts`) turns it into the tests-relative
+  group title via the existing `testFileFromOrigin`.
+- Once per file, via a module-level `registrationGroupAttempted` flag —
+  per-file module instances (the correction above) make this once-per-file for
+  free, mirroring `summaryHeaderEmitted` — and gated on `harnessOwnsStep()`, so
+  local and orchestrated (bucket) runs do no stack resolution and stay
+  unchanged.
+- The body-time `enterTestFileGroup(origin)` from Phase 2 stays as a
+  self-correcting fallback: a wrong stack guess transitions to the correct
+  group when the first test runs, and a stack-parse failure is identical to
+  Phase 2 behavior (the group just opens at body time). Registration-time
+  opening can therefore only improve placement, never break it.
+- This relies on test files registering serially in one process — the same
+  no-`--parallel` assumption Phase 2 already carries (see the interleaved
+  parallel-output hard constraint and the `deno test --parallel` non-goal). If
+  `--parallel` is ever adopted, this moves with the rest of the grouping.
+
+#### Phase 2.2 — navigable, clustered step summaries + trimmed annotations
+
+Phases 1–2 emit one step-summary row and one `<details>` block per failure
+plus a per-failure `::error`. On a real 36-failures-per-job run
+(cderv/quarto-cli run 29841891595) three problems showed: (a) the table had
+no navigation to its detail blocks; (b) 28 of 36 failures shared ONE identical
+error yet produced 28 duplicate blocks, wasting the 512 KiB budget and the
+reader's time; (c) annotations duplicated the full repro+excerpt already on the
+same page. Phase 2.2 addresses all three, in one commit, touching only
+`src/tools/github.ts` + `tests/test.ts` (+ unit tests). No workflow or checker
+changes; all Phase 1–2 invariants still hold.
+
+- **Step-wide failure ordinal.** `AnnotationBudget.recordFailure()` already
+  counts failures once per step via its sidecar file; it now also returns that
+  count as `ordinal`. In `tests/test.ts` the call moves OUT of the
+  `harnessOwnsStep()` gate (but stays under `isGitHubActions()`), so every CI
+  failure — including orchestrated bucket-leg rows — gets an ordinal; the
+  `emitAnnotation`/`emitAggregate` decisions are still consumed only inside the
+  gate, and the counter write is a file (not stdout), so orchestrated stdout
+  stays byte-identical.
+- **Failure labels.** Pure `failureLabel(ordinal, runnerOs)` → `L-F7` / `W-F7`
+  / `M-F7` (Linux/Windows/macOS; unknown → `X`). `RUNNER_OS` is read once in
+  the gated failure path and passed in; the helper reads no env. The OS prefix
+  is required because the run summary page concatenates every job's summary —
+  an unprefixed label would collide across Linux/Windows sections. The label
+  leads the summary table's new `#` column and precedes each detail block as a
+  label-only `#### L-F7` heading.
+- **No link syntax — plain-text labels (VERIFY-FIRST outcome).** The original
+  design linked table rows to detail blocks via `[L-F7](#l-f7)` fragment links
+  against the `#### L-F7` headings. A verification probe settled that this does
+  NOT work: **fork run 29923715216** (two jobs, prefixed + unprefixed label
+  probes; authenticated-browser DOM inspection) found step-summary headings
+  render as bare `<h4>` with **empty `id`**, no `id`s anywhere in the rendered
+  `markdown-body`, and every fragment link dead — GitHub's step-summary
+  renderer omits the heading-slug/anchor post-processing that README/issue
+  rendering applies. So labels are emitted as **plain text** in every row and
+  heading (no `[…](#…)`); Ctrl+F on a label gives exact two-hit navigation (row
+  ↔ heading). The OS prefix stays — it keeps that Ctrl+F hit unambiguous across
+  the concatenated per-job summaries. (This also constrains the future
+  `ci-run` helper's `verdict`: in-summary deep links are impossible, so
+  navigation there must be API-based.)
+- **Cluster identical errors.** The per-file `pendingSummaryDetails: string[]`
+  buffer becomes a `Map<signature, FailureCluster>`, keyed by
+  `excerptSignature()` = the first THREE non-empty ANSI-stripped excerpt lines
+  (one line is too generic — many failures share the "Error or Warnings During
+  Execution" banner — and would over-cluster). Cluster identity is decided at
+  failure time; the first member's label anchors the cluster and every member's
+  table row still streams immediately (crash-safety unchanged). At `unload`,
+  one block per cluster is flushed: `#### <label>` then a `<details>` whose
+  summary carries the first member's file/test name and, when N>1, a
+  `(N tests)` count and a member list (`- <label> · <file> (<repro>)`), then a
+  single shared `<pre>` excerpt (the first member's). Single-member clusters
+  render as the Phase-1 block plus its heading. Each member's table row keeps
+  its OWN unique label (which also matches its annotation title); only the
+  first member's label becomes a `#### L-Fn` heading, so a non-first member's
+  second Ctrl+F hit is its entry in the cluster's member list (which
+  find-in-page auto-expands in modern browsers), not a second heading. On run
+  29841891595 this collapses ~36 blocks to ~4, making the over-budget degrade
+  path an edge case rather than the norm.
+- **Trimmed annotations.** `annotationBody(repro, excerpt, label, maxLines=5)`
+  builds the `::error` message as: repro, blank line, first 5 non-empty excerpt
+  lines, `…`, then `Full output: step summary → <label>`. The title becomes
+  `<label> · <testName>` so an annotation cross-references its summary entry.
+  The aggregate annotation is unchanged. The full repro+excerpt lives in the
+  summary on the same page, so the annotation only needs enough to identify the
+  failure and point at the record.
+
+All seven invariants below still hold: summary rows stream per failure (the
+complete record survives a mid-file crash); orchestrated legs see no stdout
+change (the ordinal is a counter-file write); everything no-ops off CI; labels
+are ASCII by construction while file/test names keep going through
+`htmlEscape`/`escapeProperty`; the checker is untouched.
+
+### Phase 3 (optional follow-ups)
+
+- Run-level footer in the step summary: pass/fail/skip counts and total
+  duration (from an `unload` hook), so a green run also leaves a one-line
+  receipt.
+- Group the setup portions of the default-path steps in YAML (precedent: the
+  R-setup steps already do this, the "Restore R packages" step in
+  `test-smokes.yml`).
+- Add the final marker-emission conventions to `llm-docs/testing-patterns.md`
+  so future automated changes preserve the invariants below.
+
+## Invariants (must hold after any change)
+
+1. At most one group open at any time per job step; every `::group::` is
+   closed before the next one opens (defensive `endGroup()` first).
+2. No `::group::`/`::endgroup::` and no harness `::error` emitted while an
+   outer orchestrator owns the step (`QUARTO_TESTS_GHA_ORCHESTRATED`
+   contract).
+3. For **harness-registered** tests: `FAILED` result lines, the
+   `ERRORS`/`FAILURES` sections, and the run summary are never inside a
+   group. (Direct `Deno.test` files are formally exempt, though in practice
+   per-file unload closure keeps them ungrouped too — see the closure policy
+   in Phase 2 and "Coverage limitation".)
+4. Per-test `::error` annotations only when the harness owns the step, and
+   then ≤ 9 + 1 aggregate per step — enforced across per-file module
+   instances via the sidecar counter file, NOT module state; ≤ 50
+   annotations total per job including the YAML bucket loop's own. The step
+   summary is the complete failure record in every mode.
+5. Everything is a no-op unless `GITHUB_ACTIONS == "true"`: local output is
+   byte-identical.
+6. No change to which tests run, their order, or exit codes.
+7. All interpolated text goes through `escapeData`/`escapeProperty`; ANSI is
+   stripped from annotation messages and step-summary content.
+
+## Verification plan
+
+1. **Marker checker script** (`tests/tools/check-gha-log.ts` or similar,
+   dev-only): reads a captured log and asserts invariants 1–3 mechanically
+   (balanced groups, no nesting, markers at column 0, `FAILED`/`ERRORS` lines
+   outside groups). Run it locally on
+   `GITHUB_ACTIONS=true ./run-tests.sh <subset> | tee log.txt`. Re-run on every
+   Deno version bump (reporter framing is version-sensitive).
+   Windows capture gotcha: use `pwsh -File run-tests.ps1 <files>` with the
+   redirect at the shell level — `pwsh -Command '... run-tests.ps1 <files>
+   *> log'` feeds the `*>` into the script's own arg parsing, blanking the
+   file arguments and silently running the full suite.
+2. **Unit tests** for the new pure logic: annotation cap counter, the
+   orchestrated-mode gate (no annotations/groups when
+   `QUARTO_TESTS_GHA_ORCHESTRATED` is set), ANSI stripping, the stat-based
+   summary size budget (including the degrade-to-name-only path), escaping.
+3. **Trial CI runs** on a fork via `workflow_dispatch`, with one deliberately
+   failing test committed temporarily, covering all four cells:
+   {bucketed, default} × {Linux, Windows} — plus one bucket run with **more
+   than 10 failing files**, to observe GitHub's silent annotation dropping
+   and confirm the step summary still lists every failure. Check in the real
+   UI:
+   - groups collapse and titles read well; bucket-mode logs unchanged;
+   - annotations appear on the run summary (and PR checks view when opened as
+     a PR), pointing at the right file;
+   - step summary table renders; truncation path exercised once by seeding
+     many failures;
+   - job still fails with the same exit semantics as before.
+4. **Rollback safety**: Phase 1 and Phase 2 are separate commits; each is
+   revertable without touching the other. `QUARTO_TESTS_GHA_ORCHESTRATED=1`
+   in the environment is a global kill switch for harness grouping and
+   annotations without a revert (summary rows remain).
+
+## Coverage limitation: tests that bypass `tests/test.ts`
+
+Phases 1–2 hook the harness (`testQuartoCmd`/`unitTest`/`test`), so they only
+cover tests registered through it. Tests that call `Deno.test` directly get
+neither groups nor failure annotations. Today that is chiefly the
+extension-subtree tests copied into the tree by
+`.github/actions/merge-extension-tests` (`smoke/julia-engine/*.test.ts` from
+the `PumasAI/quarto-julia-engine` subtree — self-contained, `jsr:` imports
+only, raw `Deno.Command("quarto")` spawns). Those spawns also leak the
+harness dev env into the built quarto, so the merge action currently skips
+them in binary mode entirely; the un-gating plan (upstream env
+sanitization) is `dev-docs/ci-julia-engine-binary-mode-followup.md` — in
+dev shards they still run, ungrouped.
+
+Group placement for such files (updated after the per-file-instance
+correction): each harness file's group is closed by that file's own `unload`
+before the next file starts, so a non-harness file runs with NO group open —
+its output and inline `FAILED` lines land ungrouped and visible. The
+stale-group swallowing this section originally accepted does not occur under
+the current Deno model; invariant 3's harness-only scoping remains as a
+guard in case a future Deno shares module state across files again (the
+checker script would flag it). Richer coverage (own groups + annotations)
+requires adopting the markers upstream in the subtree repo — subtree files
+must not be edited in quarto-cli; see `.claude/rules/extension-subtrees.md`.
+
+## Non-goals / explicitly deferred
+
+- **Nested visual hierarchy** (file ▸ test ▸ render step): impossible on the
+  runner; fake it with title prefixes only if ever needed.
+- **`deno test --parallel`**: out of scope; if adopted, grouping must switch
+  to buffer-and-flush (capture each test's output, emit
+  group+body+endgroup atomically) or move to matrix sharding.
+- **`::stop-commands::` armoring** of rendered-document output: our tests
+  render repo-controlled documents, so command injection via test output is
+  not a current threat; revisit if tests ever render untrusted input (note it
+  would also disable our own markers while active).
+- **JUnit/structured reporters**: `deno test --reporter=junit` could feed a
+  richer summary later, but Phase 1 gets equivalent value from data the
+  harness already has, without changing the reporter everyone reads today.
+- **Local parallel runs** (`run-parallel-tests.ts` local mode) interleave
+  freely today; grouping there is meaningless (`GITHUB_ACTIONS` unset) and
+  stays untouched.
+
+## References
+
+- Workflow commands: <https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands>
+- Nesting: actions/toolkit#1001, actions/runner#802, actions/runner#1477
+- Annotation limits: github/community discussions #26680, #68471
+- Step summary limits: GitHub docs + actions/runner#4337
+- Escaping rules: `@actions/core` `command.ts` (mirrored by
+  `src/tools/github.ts` `escapeData`/`escapeProperty`)
+- Prior art in this repo: PR #13787, PR #13807, `test-smokes.yml` bucket
+  loops, R-setup grouping (`test-smokes.yml`, "Restore R packages" step)
+- Built-version testing context: `llm-docs/built-version-testing-architecture.md`
+  (the CI legs whose logs this design targets)
diff --git a/llm-docs/built-version-testing-architecture.md b/llm-docs/built-version-testing-architecture.md
index 49d8f1e821a..673c4352ea3 100644
--- a/llm-docs/built-version-testing-architecture.md
+++ b/llm-docs/built-version-testing-architecture.md
@@ -1,6 +1,6 @@
 ---
 main_commit: 2e6695811
-analyzed_date: 2026-07-20
+analyzed_date: 2026-07-23
 key_files:
   - tests/quarto-cmd.ts
   - tests/test.ts
@@ -202,14 +202,21 @@ OS leg is gated on its artifact actually existing in the resolved run.
 one atomic nightly build-and-test signal — then the inversion is the
 principled consolidation, done as a deliberate follow-up.
 
-### D2. Version marker: semver *build metadata* (`X.Y.Z+test.YYYYMMDD`)
-
-Built test dists are stamped `$(cat version.txt)+test.$(date +%Y%m%d)`.
-Never a `-suffix` (prerelease versions fail every plain `>=X.Y`
+### D2. Version stamp: the plain three-component version (`X.Y.Z`)
+
+Built test dists are stamped `$(cat version.txt)` — a plain `X.Y.Z`. An
+earlier `+test.YYYYMMDD` build-metadata marker was dropped: though valid
+semver and range-transparent, build metadata is NOT parseable by pandoc's
+`Version` type (used by the `version` shortcode), so `quarto.version` fell
+back to a raw string and version-dependent smoke docs (issue-12006, 13913,
+which assert a three-component version) failed. A plain version is
+byte-representative of a real release, still range-transparent for every
+`quarto-required` gate, and still distinguishable from the `99.9.9` dev
+sentinel. Never a `-suffix` (prerelease versions fail every plain `>=X.Y`
 `quarto-required` range — the vendored semver has no `includePrerelease`
 anywhere) and never a 4th dot component (not semver; the vendored
-`deno.land/x/semver@1.4.0` throws). Build metadata is range-transparent for
-every gate while still distinguishable from the `99.9.9` dev sentinel.
+`deno.land/x/semver@1.4.0` throws). Trial builds are identified by run
+context (workflow + ref + sha), not the version string.
 
 ### D3. Dist outside the checkout + `99.9.9` sentinel refusal
 
diff --git a/src/resources/extensions/quarto/version/version.lua b/src/resources/extensions/quarto/version/version.lua
index d957070c79d..4f6d8d6890a 100644
--- a/src/resources/extensions/quarto/version/version.lua
+++ b/src/resources/extensions/quarto/version/version.lua
@@ -1,5 +1,5 @@
 return {
   ['version'] = function(args, kwargs, meta)
-    return table.concat(quarto.version, '.')
+    return tostring(quarto.version)
   end
 }
diff --git a/src/tools/github.ts b/src/tools/github.ts
index 947bbdc8cd2..9521e1d5423 100644
--- a/src/tools/github.ts
+++ b/src/tools/github.ts
@@ -141,6 +141,285 @@ export async function group<T>(
   return await withGroupAsync(title, fn);
 }
 
+// GitHub Actions failure reporting (used by the test harness — see
+// dev-docs/ci-test-log-grouping-design.md). All of these are pure helpers or
+// gate on GITHUB_ACTIONS so callers stay byte-identical off CI.
+
+// Strip ANSI escape sequences. Annotation messages and step-summary content
+// do NOT render ANSI (only group bodies in the log viewer do), so color codes
+// must be removed before embedding captured output in either.
+// deno-lint-ignore no-control-regex
+const kAnsiPattern = /\x1b\[[0-9;?]*[A-Za-z]/g;
+export function stripAnsi(s: string): string {
+  return s.replace(kAnsiPattern, "");
+}
+
+// The harness emits per-test ::error annotations only when it owns the
+// workflow step: on CI and when no outer orchestrator has claimed the step
+// via QUARTO_TESTS_GHA_ORCHESTRATED (the bucket-loop YAML sets it and emits
+// its own per-file ::error). Arguments default to the live environment;
+// unit tests pass them explicitly to avoid mutating process-global env.
+// `orchestrated` semantics: omitted → read QUARTO_TESTS_GHA_ORCHESTRATED
+// from the live environment; `null` → treat as unset. Tests must pass `null`
+// (never an explicit `undefined`, which triggers the default parameter and
+// reads the real env — inside a CI bucket step that variable IS set, so the
+// test would flip depending on where it runs).
+export function harnessOwnsStep(
+  githubActions: boolean = isGitHubActions(),
+  orchestrated?: string | null,
+): boolean {
+  const o = orchestrated === undefined
+    ? Deno.env.get("QUARTO_TESTS_GHA_ORCHESTRATED")
+    : orchestrated;
+  return githubActions && !o;
+}
+
+// GitHub caps annotations at 10 ::error per workflow STEP; excess is silently
+// dropped. One `deno test` process is the step in the harness-owned path, BUT
+// Deno instantiates each test file's module graph separately (verified on the
+// pinned 2.7.14: module state does not carry across test files, and `unload`
+// fires once per file), so a module-level counter would be a per-FILE budget.
+// The count is therefore coordinated through a sidecar counter file derived
+// from GITHUB_STEP_SUMMARY — unique per step and in a runner-writable
+// directory. No locking: without `deno test --parallel`, test files run
+// strictly sequentially. With no counter path (not on CI), state falls back
+// to instance-local, which unit tests also use via injection.
+export function defaultAnnotationCounterPath(): string | undefined {
+  const summary = Deno.env.get("GITHUB_STEP_SUMMARY");
+  return summary ? `${summary}.qt-annotation-count` : undefined;
+}
+
+export interface AnnotationDecision {
+  // step-wide 1-based count of this failure (every CI failure gets one, used
+  // to build its navigation label; see failureLabel)
+  ordinal: number;
+  // emit the per-test ::error for this failure
+  emitAnnotation: boolean;
+  // this failure is the first one past the cap: emit the single aggregate
+  // ::error (the 10th and last annotation for the step) instead
+  emitAggregate: boolean;
+}
+
+// `counterPath` semantics: omitted → the env-derived per-step sidecar file;
+// `null` → instance-local state, guaranteed to touch no file. The null
+// sentinel exists because passing `undefined` explicitly triggers the
+// default parameter (JS semantics) — in CI that silently pointed unit tests
+// at the REAL step counter, found by trial run cderv/quarto-cli#29767179626.
+export class AnnotationBudget {
+  private localCount = 0;
+  private readonly counterPath: string | null;
+  constructor(
+    private readonly max = 9,
+    counterPath?: string | null,
+  ) {
+    this.counterPath = counterPath === undefined
+      ? defaultAnnotationCounterPath() ?? null
+      : counterPath;
+  }
+
+  private readCount(): number {
+    if (this.counterPath === null) return this.localCount;
+    try {
+      return parseInt(Deno.readTextFileSync(this.counterPath), 10) || 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  private writeCount(n: number): void {
+    if (this.counterPath === null) {
+      this.localCount = n;
+      return;
+    }
+    Deno.writeTextFileSync(this.counterPath, String(n));
+  }
+
+  // Record one failure and decide what to emit for it. Returns the step-wide
+  // ordinal (the running count, used to build the failure's navigation label
+  // — every failure gets one, uncapped) alongside the emit decisions. The
+  // aggregate fires exactly when the count first crosses the cap — no
+  // end-of-run hook exists that spans test files, so it must be emitted inline
+  // by the failure that crosses the line; later failures emit nothing.
+  recordFailure(): AnnotationDecision {
+    const count = this.readCount() + 1;
+    this.writeCount(count);
+    return {
+      ordinal: count,
+      emitAnnotation: count <= this.max,
+      emitAggregate: count === this.max + 1,
+    };
+  }
+}
+
+// GITHUB_STEP_SUMMARY is 1 MiB per step and content just under the limit can
+// be silently dropped (actions/runner#4337). Stay at ~half so bucket mode —
+// many processes appending to the same file — has headroom; the file size
+// itself is the cross-process coordinator.
+export const kStepSummaryBudgetBytes = 512 * 1024;
+
+// Append markdown to the GitHub Actions step summary. No-op when the file is
+// unset (local runs, or steps without a summary). `path` semantics: omitted →
+// $GITHUB_STEP_SUMMARY; `null` (or "") → guaranteed no-op. Tests must pass
+// `null` or a temp path, never an explicit `undefined` — that triggers the
+// default parameter and, on CI, writes to the REAL step summary (found by
+// trial run cderv/quarto-cli#29767179626).
+export function stepSummary(
+  markdown: string,
+  path?: string | null,
+): void {
+  const p = path === undefined ? Deno.env.get("GITHUB_STEP_SUMMARY") : path;
+  if (!p) return;
+  Deno.writeTextFileSync(p, markdown, { append: true });
+}
+
+// Current size of the step-summary file (0 when unset/missing). Callers
+// compare against kStepSummaryBudgetBytes to decide whether to degrade.
+// Same `path` semantics as stepSummary.
+export function stepSummarySize(
+  path?: string | null,
+): number {
+  const p = path === undefined ? Deno.env.get("GITHUB_STEP_SUMMARY") : path;
+  if (!p) return 0;
+  try {
+    return Deno.statSync(p).size;
+  } catch {
+    return 0;
+  }
+}
+
+function htmlEscape(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+// A table cell must not contain a raw `|` (column separator) or newline (row
+// terminator); HTML-escape the rest so angle brackets in test names render.
+function summaryCell(s: string): string {
+  return htmlEscape(s).replaceAll("|", "\\|").replace(/\r?\n/g, " ");
+}
+
+function formatDuration(ms: number): string {
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+// A failure's navigation label: the step-wide ordinal prefixed with the
+// runner OS (RUNNER_OS: "Linux"/"Windows"/"macOS"; anything else → X). The
+// run summary page concatenates every job's summary, so the prefix keeps the
+// label unambiguous across jobs — it is the Ctrl+F target that ties a table
+// row to its detail block (step-summary heading anchors do not resolve, so
+// there is no link; the shared ASCII label is the navigation).
+export function failureLabel(ordinal: number, runnerOs: string): string {
+  const os = runnerOs.toLowerCase();
+  const prefix = os.startsWith("linux")
+    ? "L"
+    : os.startsWith("windows")
+    ? "W"
+    : os.startsWith("macos")
+    ? "M"
+    : "X";
+  return `${prefix}-F${ordinal}`;
+}
+
+// The clustering key for a failure: the first three non-empty lines of the
+// ANSI-stripped excerpt. Three, not one, because the first line alone is a
+// generic banner for many failure kinds and would over-cluster.
+export function excerptSignature(excerpt: string): string {
+  return stripAnsi(excerpt)
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .slice(0, 3)
+    .join("\n");
+}
+
+export function summaryTableHeader(): string {
+  return "| # | Test file | Test | Duration |\n| :-- | :-- | :-- | --: |\n";
+}
+
+export function summaryTableRow(
+  label: string,
+  file: string,
+  name: string,
+  durationMs: number,
+): string {
+  return `| ${label} | \`${file}\` | ${summaryCell(name)} | ${
+    formatDuration(durationMs)
+  } |\n`;
+}
+
+// Degraded row emitted once the summary file is over budget: the failure is
+// still recorded by name (the complete record), just without duration/output.
+// The label column renders the same plain text as a full row.
+export function summaryTableRowNameOnly(
+  label: string,
+  file: string,
+  name: string,
+): string {
+  return `| ${label} | \`${file}\` | ${summaryCell(name)} | |\n`;
+}
+
+export interface ClusterMember {
+  label: string;
+  file: string;
+  testName: string;
+  repro: string;
+}
+
+export interface FailureCluster {
+  label: string;
+  members: ClusterMember[];
+  excerpt: string;
+}
+
+// Expandable output block for one CLUSTER of same-signature failures. Preceded
+// by a label-only `#### L-F7` heading (the second Ctrl+F hit). The <summary>
+// label names the first failing test (file + test name); with >1 member it
+// also carries the member count and lists every member (label + file + repro).
+// One shared excerpt (the first member's) renders inside a <pre> with
+// HTML-escaped content so backticks/pipes/angle brackets in captured output
+// can't break out. GFM ends a table at the first non-row line, so these blocks
+// are flushed after all table rows, never interleaved between them.
+export function summaryClusterBlock(cluster: FailureCluster): string {
+  const first = cluster.members[0];
+  const n = cluster.members.length;
+  const count = n > 1 ? ` (${n} tests)` : "";
+  const summaryLabel = `<code>${htmlEscape(first.file)}</code> — ${
+    htmlEscape(first.testName).replace(/\r?\n/g, " ")
+  }${count}`;
+  // With more than one member, list every clustered failure (label + file +
+  // repro) so the reader can reach each one; the shared excerpt is shown once.
+  let memberList = "";
+  if (n > 1) {
+    memberList = "\n" + cluster.members
+      .map((m) =>
+        `- ${m.label} · <code>${htmlEscape(m.file)}</code> (<code>${
+          htmlEscape(m.repro)
+        }</code>)`
+      )
+      .join("\n") + "\n";
+  }
+  const body = htmlEscape(`${first.repro}\n\n${cluster.excerpt}`);
+  return `\n#### ${cluster.label}\n\n<details><summary>${summaryLabel}</summary>\n${memberList}\n<pre>\n${body}\n</pre>\n</details>\n\n`;
+}
+
+// Trimmed annotation message: the repro, a blank line, the first `maxLines`
+// non-empty excerpt lines, an ellipsis, then a pointer at the step-summary
+// entry (by label). The full repro+excerpt already lives in the summary on the
+// same page, so the annotation only needs enough to identify the failure.
+export function annotationBody(
+  repro: string,
+  excerpt: string,
+  label: string,
+  maxLines = 5,
+): string {
+  const lines = stripAnsi(excerpt)
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .slice(0, maxLines);
+  return `${repro}\n\n${lines.join("\n")}\n…\nFull output: step summary → ${label}`;
+}
+
 // GitHub API
 
 // A Github Release for a Github Repo
diff --git a/tests/README.md b/tests/README.md
index 1035d2ce279..4ba622d82c8 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -439,7 +439,7 @@ To run in binary mode locally:
 ```bash
 # 1. Build a distribution (after ./configure.sh)
 cd package/src
-./quarto-bld prepare-dist --set-version "$(cat ../../version.txt)+test.$(date +%Y%m%d)"
+./quarto-bld prepare-dist --set-version "$(cat ../../version.txt)"
 cd ../..
 
 # 2. Copy the built dist OUTSIDE the git checkout. An in-repo quarto
diff --git a/tests/gha-grouping.ts b/tests/gha-grouping.ts
new file mode 100644
index 00000000000..9ce7f2afd6f
--- /dev/null
+++ b/tests/gha-grouping.ts
@@ -0,0 +1,110 @@
+/*
+ * gha-grouping.ts
+ *
+ * Per-test-file GitHub Actions `::group::` emission for the default
+ * (non-bucketed) test run (Phase 2 of dev-docs/ci-test-log-grouping-design.md).
+ *
+ * The GitHub Actions runner cannot nest groups: a second `::group::`
+ * implicitly closes the first, and content after the inner group ends up
+ * outside any group. So there must be exactly one owner of grouping per code
+ * path. The harness owns grouping ONLY when nothing else does — on CI, with no
+ * outer orchestrator claiming the step (the YAML bucket loop sets
+ * QUARTO_TESTS_GHA_ORCHESTRATED and emits its own groups). That ownership test
+ * is harnessOwnsStep() from src/tools/github.ts, the same switch Phase 1 uses.
+ *
+ * Copyright (C) 2020-2026 Posit Software, PBC
+ */
+
+import { endGroup, harnessOwnsStep, startGroup } from "../src/tools/github.ts";
+
+// Per-file grouping state machine. Emits group markers through injected
+// callbacks so unit tests drive it without touching the environment or
+// capturing console output. Enforces the single-open-group invariant: entering
+// a new file closes the previous file's group before opening the next, and a
+// group is only ever closed if one is actually open (no stray `::endgroup::`).
+// The `gate` decides ownership per call, so a run where the harness never owns
+// the step never emits or mutates state.
+export class GroupEmitter {
+  private openFile: string | undefined = undefined;
+
+  constructor(
+    private readonly gate: () => boolean,
+    private readonly onStart: (title: string) => void,
+    private readonly onEnd: () => void,
+  ) {}
+
+  // Open the group for `file`, closing the previous file's group first. A
+  // repeated call for the same still-open file is a no-op — the group stays
+  // open across all of that file's tests.
+  enterFile(file: string): void {
+    if (!this.gate()) return;
+    if (this.openFile === file) return;
+    if (this.openFile !== undefined) this.onEnd();
+    this.onStart(file);
+    this.openFile = file;
+  }
+
+  // Close the current group if one is open (failure path, and unload). Safe to
+  // call when nothing is open — no marker is emitted then, so the failure
+  // path's close followed by the unload close never double-emits.
+  close(): void {
+    if (!this.gate()) return;
+    if (this.openFile !== undefined) {
+      this.onEnd();
+      this.openFile = undefined;
+    }
+  }
+
+  // The file whose group is currently open, if any (inspection/tests).
+  currentFile(): string | undefined {
+    return this.openFile;
+  }
+}
+
+// Parse a V8 error stack and return the `file://` URL (with any trailing
+// `:line:column` removed) of the first `.test.ts` frame — the test file whose
+// top-level `test(...)` call is registering, reading from the innermost frame
+// outward. Harness frames (test.ts, gha-grouping.ts) never end in `.test.ts`,
+// so they are skipped implicitly. Returns undefined for a missing or
+// unparseable stack, or when no test-file frame is present; never throws. Kept
+// pure (string in, string out) so registration-time file resolution is
+// unit-testable without a real stack or a configured environment.
+export function testFileUrlFromStack(
+  stack: string | undefined,
+): string | undefined {
+  if (stack === undefined) return undefined;
+  try {
+    // A V8 frame is `    at <fn> (file:///…:line:col)` or the bare
+    // `    at file:///…:line:col`. The lazy `\S*?` stops at the first
+    // `.test.ts`, so the trailing `:line:column` (and any closing paren) stay
+    // out of the captured URL; `\S` never crosses a newline, so the match is
+    // confined to one frame. On Windows the drive-letter colon sits inside the
+    // URL and is preserved. match() scans top-down, so the innermost (first)
+    // `.test.ts` frame — the registering test file — wins; harness frames
+    // (test.ts, gha-grouping.ts) never contain `.test.ts` and are skipped.
+    const match = stack.match(/file:\/\/\/?\S*?\.test\.ts/);
+    return match?.[0];
+  } catch {
+    return undefined;
+  }
+}
+
+// Module singleton wired to the real workflow-command emitters and gated on
+// harnessOwnsStep(). startGroup/endGroup additionally no-op off CI, so this is
+// doubly safe: local runs never emit, and orchestrated (bucket) runs stay
+// byte-identical because the gate is false there.
+const emitter = new GroupEmitter(harnessOwnsStep, startGroup, endGroup);
+
+// Open (or transition to) the group for a test file. Call at the start of each
+// harness test's fn, before any output; `file` is the tests-relative
+// forward-slash path used as the group title.
+export function enterTestFileGroup(file: string): void {
+  emitter.enterFile(file);
+}
+
+// Close any open group. Call on the failure path (before fail() throws, so the
+// FAILED line lands outside the group) and at unload (so the terminal
+// ERRORS/FAILURES/summary sections are never grouped).
+export function closeTestFileGroup(): void {
+  emitter.close();
+}
diff --git a/tests/test.ts b/tests/test.ts
index 31a37fddfd2..e8fb8869264 100644
--- a/tests/test.ts
+++ b/tests/test.ts
@@ -17,7 +17,78 @@ import { runningInCI } from "../src/core/ci-info.ts";
 import { relative, fromFileUrl } from "../src/deno_ral/path.ts";
 import { quartoConfig } from "../src/core/quarto.ts";
 import { isWindows } from "../src/deno_ral/platform.ts";
-
+import {
+  AnnotationBudget,
+  annotationBody,
+  excerptSignature,
+  type FailureCluster,
+  failureLabel,
+  error as ghError,
+  harnessOwnsStep,
+  isGitHubActions,
+  kStepSummaryBudgetBytes,
+  stepSummary,
+  stepSummarySize,
+  stripAnsi,
+  summaryClusterBlock,
+  summaryTableHeader,
+  summaryTableRow,
+  summaryTableRowNameOnly,
+} from "../src/tools/github.ts";
+import {
+  closeTestFileGroup,
+  enterTestFileGroup,
+  testFileUrlFromStack,
+} from "./gha-grouping.ts";
+
+
+// GitHub Actions failure-surfacing state (Phase 1 of
+// dev-docs/ci-test-log-grouping-design.md). Everything here is a no-op unless
+// GITHUB_ACTIONS=true, so local test output stays byte-identical.
+//
+// SCOPE WARNING: Deno instantiates each test FILE's module graph separately
+// (verified on the pinned 2.7.14) — this module-level state is per test file,
+// not per process, and `unload` fires once per file. Anything that must be
+// per-STEP (the annotation budget) is coordinated through a sidecar file
+// inside AnnotationBudget instead of module state.
+const kExcerptLines = 20;
+const annotationBudget = new AnnotationBudget();
+// Per-file header flag: each failing test file starts its own summary table.
+let summaryHeaderEmitted = false;
+// Phase 2.1 (dev-docs/ci-test-log-grouping-design.md): the per-file group is
+// opened once at registration (module-eval) time — before Deno prints its
+// "running N tests from" and announcement frame lines — so those lines land
+// inside the group instead of above it. Per-file module state (see SCOPE
+// WARNING above) makes this once-per-file for free, mirroring
+// summaryHeaderEmitted; the first test() call in the file attempts it.
+let registrationGroupAttempted = false;
+// GFM ends a table at the first non-row line, so per-failure <details> blocks
+// cannot sit between table rows; buffer them and flush after this file's rows
+// at its unload event. Failures with an identical excerpt signature cluster
+// into ONE block (keyed by signature) — a run where dozens of tests share one
+// error collapses to a handful of blocks instead of dozens of duplicates. The
+// first member's label anchors the cluster; the map is per test-file module
+// instance (see the SCOPE WARNING above), which is why the ordinal/label are
+// step-wide (sidecar counter) but the clustering is per file.
+const pendingClusters = new Map<string, FailureCluster>();
+
+if (isGitHubActions()) {
+  globalThis.addEventListener("unload", () => {
+    // Fires at the end of EACH test file's module instance. Close this
+    // file's group if still open — this is what ends a passing file's group
+    // before the next file starts, and keeps Deno's terminal
+    // ERRORS/FAILURES/summary sections outside any group (Phase 2). No-op
+    // unless the harness owns the step.
+    closeTestFileGroup();
+    // Flush this file's clustered detail blocks after its row table (one
+    // block per signature), stopping if the shared summary file crosses the
+    // size budget.
+    for (const cluster of pendingClusters.values()) {
+      if (stepSummarySize() > kStepSummaryBudgetBytes) break;
+      stepSummary(summaryClusterBlock(cluster));
+    }
+  });
+}
 
 export interface TestLogConfig {
   // Path to log file
@@ -213,7 +284,49 @@ export function unitTest(
   });
 }
 
+// Resolve a Deno test's declaring file from context.origin: the absolute path
+// (fromFileUrl on Windows, URL pathname elsewhere) and the tests-relative path
+// (run-tests.sh runs from tests/). Used both to open the per-file GitHub
+// Actions group at the start of fn and to build the repro command on failure.
+function testFileFromOrigin(origin: string): {
+  absPath: string;
+  relPath: string;
+} {
+  const absPath = isWindows
+    ? fromFileUrl(origin)
+    : (new URL(origin)).pathname;
+  const quartoRoot = join(quartoConfig.binPath(), "..", "..", "..");
+  const relPath = relative(join(quartoRoot, "tests"), absPath);
+  return { absPath, relPath };
+}
+
+// Resolve the registering test file at registration (module-eval) time, when
+// there is no context.origin yet, by walking the current call stack (Phase
+// 2.1). testFileUrlFromStack picks the first `.test.ts` frame — the file whose
+// top-level test() call is running — and testFileFromOrigin turns that URL into
+// the tests-relative forward-slash path. Returns undefined when the stack
+// cannot be parsed; the body-time enterTestFileGroup(origin) then opens (or
+// transitions to) the correct group, so a missed guess is only a lost early
+// open, never a wrong or duplicated group.
+function testFileFromStack(): string | undefined {
+  const url = testFileUrlFromStack(new Error().stack);
+  if (url === undefined) return undefined;
+  return testFileFromOrigin(url).relPath.replaceAll("\\", "/");
+}
+
 export function test(test: TestDescriptor) {
+  // Phase 2.1: open this file's group now, at registration time, so Deno's
+  // "running N tests from" and announcement lines land inside it. Once per file
+  // (registrationGroupAttempted), gated on harnessOwnsStep() so local and
+  // orchestrated (bucket) runs do no stack resolution and stay byte-identical.
+  if (!registrationGroupAttempted && harnessOwnsStep()) {
+    registrationGroupAttempted = true;
+    const file = testFileFromStack();
+    if (file !== undefined) {
+      enterTestFileGroup(file);
+    }
+  }
+
   const testName = test.context.name
     ? `[${test.type}] > ${test.name} (${test.context.name})`
     : `[${test.type}] > ${test.name}`;
@@ -229,187 +342,321 @@ export function test(test: TestDescriptor) {
   const args: Deno.TestDefinition = {
     name: testName,
     async fn(context) {
-      await initDenoDom();
-      const runTest = !test.context.prereq || await test.context.prereq();
-      if (runTest) {
-        const wd = Deno.cwd();
-        if (test.context?.cwd) {
-          Deno.chdir(test.context.cwd());
-        }
-
-        if (test.context.setup) {
-          await test.context.setup();
-        }
-
-        // In binary mode the spawned quarto owns the log file; the harness
-        // must not initialize (or later destroy) its own logger for
-        // capture — cleanupLogger() would permanently tear down the
-        // default handlers for subsequent tests in this process.
-        const binMode = isBinaryMode();
-
-        let cleanedup = false;
-        const cleanupLogOnce = async () => {
-          if (!cleanedup && !binMode) {
-            await cleanupLogger();
-            cleanedup = true;
+      // GitHub Actions per-file log grouping (Phase 2 of
+      // dev-docs/ci-test-log-grouping-design.md): open (or transition to) the
+      // group for this test's declaring file before any output. Gated on
+      // harnessOwnsStep() so local and orchestrated (bucket) runs do no origin
+      // resolution and stay byte-identical; enterTestFileGroup re-checks the
+      // gate for its other caller.
+      if (harnessOwnsStep()) {
+        enterTestFileGroup(
+          testFileFromOrigin(context.origin).relPath.replaceAll("\\", "/"),
+        );
+      }
+      try {
+        const testStart = performance.now();
+        await initDenoDom();
+        const runTest = !test.context.prereq || await test.context.prereq();
+        if (runTest) {
+          const wd = Deno.cwd();
+          if (test.context?.cwd) {
+            Deno.chdir(test.context.cwd());
           }
-        };
-
-        // Capture the output
-        const log = Deno.makeTempFileSync({ suffix: ".json" });
-        const logTarget = test.logConfig?.log || log;
-        const handlers = binMode ? undefined : await initializeLogger({
-          log: logTarget,
-          level: test.logConfig?.level || "INFO",
-          format: test.logConfig?.format || "json-stream",
-          quiet: true,
-        });
-
-        const logOutput = (path: string) => {
-          if (existsSync(path)) {
-            return readExecuteOutput(path);
-          } else {
-            return undefined;
+
+          if (test.context.setup) {
+            await test.context.setup();
           }
-        };
-        let lastVerify;
 
-        try {
+          // In binary mode the spawned quarto owns the log file; the harness
+          // must not initialize (or later destroy) its own logger for
+          // capture — cleanupLogger() would permanently tear down the
+          // default handlers for subsequent tests in this process.
+          const binMode = isBinaryMode();
+
+          let cleanedup = false;
+          const cleanupLogOnce = async () => {
+            if (!cleanedup && !binMode) {
+              await cleanupLogger();
+              cleanedup = true;
+            }
+          };
+
+          // Capture the output
+          const log = Deno.makeTempFileSync({ suffix: ".json" });
+          const logTarget = test.logConfig?.log || log;
+          const handlers = binMode ? undefined : await initializeLogger({
+            log: logTarget,
+            level: test.logConfig?.level || "INFO",
+            format: test.logConfig?.format || "json-stream",
+            quiet: true,
+          });
 
-          try {
-            await test.execute(logTarget);
-          } catch (e) {
-            if (binMode) {
-              // no harness logger in binary mode — append the failure to
-              // the log file directly so verifiers (and the failure
-              // report) still see it
-              const message = e instanceof Error
-                ? `${e.message}\n${e.stack ?? ""}`
-                : String(e);
-              appendLogError(logTarget, message);
+          const logOutput = (path: string) => {
+            if (existsSync(path)) {
+              return readExecuteOutput(path);
             } else {
-              logError(e);
+              return undefined;
             }
-          }
+          };
+          let lastVerify;
 
-          // Cleanup the output logging
-          await cleanupLogOnce();
+          try {
 
-          if (handlers) {
-            flushLoggers(handlers);
-          }
+            try {
+              await test.execute(logTarget);
+            } catch (e) {
+              if (binMode) {
+                // no harness logger in binary mode — append the failure to
+                // the log file directly so verifiers (and the failure
+                // report) still see it
+                const message = e instanceof Error
+                  ? `${e.message}\n${e.stack ?? ""}`
+                  : String(e);
+                appendLogError(logTarget, message);
+              } else {
+                logError(e);
+              }
+            }
 
-          // Read the output. Verifiers must read logTarget - the harness
-          // logger and the binary-mode child both write there; reading the
-          // temp file would hand every log verifier an empty array whenever
-          // logConfig.log is set. And a missing log is a FAILURE - skipping
-          // verification would pass the test without checking anything.
-          const testOutput = logOutput(logTarget);
-          if (testOutput === undefined) {
-            fail(`test log file is missing: ${logTarget}`);
-          } else {
-            for (const ver of test.verify) {
-              lastVerify = ver;
-              if (userSession) {
-                const verifyMsg = "[verify] > " + ver.name;
-                console.log(userSession ? colors.dim(verifyMsg) : verifyMsg);
+            // Cleanup the output logging
+            await cleanupLogOnce();
+
+            if (handlers) {
+              flushLoggers(handlers);
+            }
+
+            // Read the output. Verifiers must read logTarget - the harness
+            // logger and the binary-mode child both write there; reading the
+            // temp file would hand every log verifier an empty array whenever
+            // logConfig.log is set. And a missing log is a FAILURE - skipping
+            // verification would pass the test without checking anything.
+            const testOutput = logOutput(logTarget);
+            if (testOutput === undefined) {
+              fail(`test log file is missing: ${logTarget}`);
+            } else {
+              for (const ver of test.verify) {
+                lastVerify = ver;
+                if (userSession) {
+                  const verifyMsg = "[verify] > " + ver.name;
+                  console.log(userSession ? colors.dim(verifyMsg) : verifyMsg);
+                }
+                await ver.verify(testOutput);
               }
-              await ver.verify(testOutput);
             }
-          }
-        } catch (ex) {
-          if (!(ex instanceof Error)) throw ex;
-
-          const border = "-".repeat(80);
-          const coloredName = userSession
-            ? colors.brightGreen(colors.italic(testName))
-            : testName;
-
-          // Compute an inset based upon the testName
-          const offset = testName.indexOf(">");
-
-          // Form the test runner command
-          const absPath = isWindows
-            ? fromFileUrl(context.origin)
-            : (new URL(context.origin)).pathname;
-
-          const quartoRoot = join(quartoConfig.binPath(), "..", "..", "..");
-          const relPath = relative(
-            join(quartoRoot, "tests"),
-            absPath,
-          );
-          const command = isWindows
-            ? "run-tests.ps1"
-            : "./run-tests.sh";
-          const testCommand = `${
-            offset > 0 ? " ".repeat(offset + 2) : ""
-          }${command} ${relPath}`;
-          const coloredTestCommand = userSession
-            ? colors.brightGreen(testCommand)
-            : testCommand;
-
-          const verifyFailed = `[verify] > ${
-            lastVerify ? lastVerify.name : "unknown"
-          }`;
-          const coloredVerify = userSession
-            ? colors.brightGreen(verifyFailed)
-            : verifyFailed;
-
-          // guarded: a corrupt/unparseable log must not clobber the
-          // assembled failure report with a secondary parse error
-          let logMessages: ExecuteOutput[] | undefined;
-          try {
-            logMessages = logOutput(logTarget);
-          } catch {
-            logMessages = undefined;
-          }
+          } catch (ex) {
+            if (!(ex instanceof Error)) throw ex;
+
+            // Pop out of the per-file group BEFORE emitting the ::error
+            // annotation and throwing, so the annotation, the FAILED result
+            // line, and the end-of-run failure detail all land outside any
+            // collapsed group (Phase 2, spike-verified). The next test re-opens
+            // a group with the same file title.
+            closeTestFileGroup();
+
+            const border = "-".repeat(80);
+            const coloredName = userSession
+              ? colors.brightGreen(colors.italic(testName))
+              : testName;
+
+            // Compute an inset based upon the testName
+            const offset = testName.indexOf(">");
+
+            // Form the test runner command
+            const { absPath, relPath } = testFileFromOrigin(context.origin);
+            const command = isWindows
+              ? "run-tests.ps1"
+              : "./run-tests.sh";
+            const testCommand = `${
+              offset > 0 ? " ".repeat(offset + 2) : ""
+            }${command} ${relPath}`;
+            const coloredTestCommand = userSession
+              ? colors.brightGreen(testCommand)
+              : testCommand;
+
+            const verifyFailed = `[verify] > ${
+              lastVerify ? lastVerify.name : "unknown"
+            }`;
+            const coloredVerify = userSession
+              ? colors.brightGreen(verifyFailed)
+              : verifyFailed;
+
+            // guarded: a corrupt/unparseable log must not clobber the
+            // assembled failure report with a secondary parse error
+            let logMessages: ExecuteOutput[] | undefined;
+            try {
+              logMessages = logOutput(logTarget);
+            } catch {
+              logMessages = undefined;
+            }
 
-          // Create distinctive failure marker for easy log navigation
-          // This helps users find the failure when clicking GitHub Actions annotations
-          const failureMarker = `━━━ TEST FAILURE: ${testName}`;
-          const coloredFailureMarker = userSession
-            ? colors.red(colors.bold(failureMarker))
-            : failureMarker;
-
-          const output: string[] = [
-            "",
-            "",
-            coloredFailureMarker,
-            border,
-            coloredName,
-            coloredTestCommand,
-            "",
-            coloredVerify,
-            "",
-            ex.message,
-            ex.stack ?? "",
-            "",
-          ];
-
-          if (logMessages && logMessages.length > 0) {
-            output.push("OUTPUT:");
-            logMessages.forEach((out) => {
-              const parts = out.msg.split("\n");
-              parts.forEach((part) => {
-                output.push("    " + part);
+            // Create distinctive failure marker for easy log navigation
+            // This helps users find the failure when clicking GitHub Actions annotations
+            const failureMarker = `━━━ TEST FAILURE: ${testName}`;
+            const coloredFailureMarker = userSession
+              ? colors.red(colors.bold(failureMarker))
+              : failureMarker;
+
+            const output: string[] = [
+              "",
+              "",
+              coloredFailureMarker,
+              border,
+              coloredName,
+              coloredTestCommand,
+              "",
+              coloredVerify,
+              "",
+              ex.message,
+              ex.stack ?? "",
+              "",
+            ];
+
+            if (logMessages && logMessages.length > 0) {
+              output.push("OUTPUT:");
+              logMessages.forEach((out) => {
+                const parts = out.msg.split("\n");
+                parts.forEach((part) => {
+                  output.push("    " + part);
+                });
               });
-            });
-          }
+            }
 
-          fail(output.join("\n"));
-        } finally {
-          safeRemoveSync(log);
-          await cleanupLogOnce();
-          if (test.context.teardown) {
-            await test.context.teardown();
-          }
+            // GitHub Actions: a failure annotation (navigation) and a
+            // step-summary row (the complete failure record). No-op off CI.
+            if (isGitHubActions()) {
+              const fwd = (p: string) => p.replaceAll("\\", "/");
+              // The repro path is tests-relative (run-tests.sh runs from
+              // tests/); the annotation file= is repo-relative with forward
+              // slashes. For smoke-all doc tests the navigable file is the
+              // rendered document (embedded in the test name by
+              // smoke-all.test.ts), not the harness .test.ts file.
+              let reproPath = fwd(relPath);
+              if (fwd(absPath).endsWith("/smoke/smoke-all.test.ts")) {
+                const m = fwd(testName).match(
+                  /(\S+\.(?:qmd|ipynb|md))(?=\s|$)/,
+                );
+                if (m) {
+                  reproPath = m[1];
+                }
+              }
+              const annotationFile = `tests/${reproPath}`;
+              const repro = `${command} ${reproPath}`;
 
-          if (test.context?.cwd) {
-            Deno.chdir(wd);
+              const rawExcerpt: string[] = [ex.message];
+              if (ex.stack) {
+                rawExcerpt.push(ex.stack);
+              }
+              if (logMessages && logMessages.length > 0) {
+                rawExcerpt.push("OUTPUT:");
+                for (const out of logMessages) {
+                  for (const part of out.msg.split("\n")) {
+                    rawExcerpt.push("    " + part);
+                  }
+                }
+              }
+              const excerpt = stripAnsi(rawExcerpt.join("\n"))
+                .split("\n")
+                .slice(0, kExcerptLines)
+                .join("\n");
+
+              // Record the failure step-wide (sidecar counter) to get its
+              // ordinal, then build the navigation label. This runs for EVERY
+              // CI failure — including orchestrated bucket legs, whose rows
+              // need labels too — because the counter write is a file, not
+              // stdout, so orchestrated stdout stays byte-identical. Only the
+              // emit decisions below are gated on the harness owning the step.
+              const decision = annotationBudget.recordFailure();
+              const label = failureLabel(
+                decision.ordinal,
+                Deno.env.get("RUNNER_OS") ?? "",
+              );
+
+              // Step-summary row — emitted in ALL modes (cap-free, size-
+              // coordinated via the file). Degrade to name-only once the
+              // shared file is over budget.
+              const overBudget = stepSummarySize() > kStepSummaryBudgetBytes;
+              if (!summaryHeaderEmitted) {
+                stepSummary(summaryTableHeader());
+                summaryHeaderEmitted = true;
+              }
+              if (overBudget) {
+                stepSummary(
+                  summaryTableRowNameOnly(label, annotationFile, testName),
+                );
+              } else {
+                const durationMs = Math.round(performance.now() - testStart);
+                stepSummary(
+                  summaryTableRow(label, annotationFile, testName, durationMs),
+                );
+                // Cluster the detail block by excerpt signature: identical
+                // errors share ONE block, anchored by (and headed with) the
+                // FIRST member's label. Each row keeps its OWN unique label
+                // (matching its annotation title); a non-first member's second
+                // navigation hit is its `- L-Fn ·` line in the cluster's
+                // member list, not a heading. The row already streamed above,
+                // so a mid-file crash still leaves the complete record.
+                const signature = excerptSignature(excerpt);
+                const member = { label, file: annotationFile, testName, repro };
+                const existing = pendingClusters.get(signature);
+                if (existing) {
+                  existing.members.push(member);
+                } else {
+                  pendingClusters.set(signature, {
+                    label,
+                    members: [member],
+                    excerpt,
+                  });
+                }
+              }
+
+              // Failure annotation — navigation only, and only when the
+              // harness owns the step. The budget is step-wide (sidecar
+              // counter file — module state is per test FILE, see the scope
+              // warning at the top); the failure that crosses the cap emits
+              // the single aggregate as the step's 10th and last annotation.
+              // The message is trimmed (the full output is in the summary on
+              // the same page) and the title carries the label so annotations
+              // cross-reference their summary entry.
+              if (harnessOwnsStep()) {
+                if (decision.emitAnnotation) {
+                  ghError(annotationBody(repro, excerpt, label), {
+                    file: annotationFile,
+                    title: `${label} · ${testName}`,
+                  });
+                } else if (decision.emitAggregate) {
+                  ghError(
+                    "Further test failures are not annotated (GitHub caps " +
+                      "annotations per step) — see the step summary for " +
+                      "the complete list",
+                    { title: "More test failures" },
+                  );
+                }
+              }
+            }
+
+            fail(output.join("\n"));
+          } finally {
+            safeRemoveSync(log);
+            await cleanupLogOnce();
+            if (test.context.teardown) {
+              await test.context.teardown();
+            }
+
+            if (test.context?.cwd) {
+              Deno.chdir(wd);
+            }
           }
+        } else {
+          warning(`Skipped - ${test.name}`);
         }
-      } else {
-        warning(`Skipped - ${test.name}`);
+      } catch (e) {
+        // Close the per-file group before ANY failure propagates to Deno.
+        // init/prereq/setup/teardown errors bypass the execute/verify
+        // failure path (which closes it itself; close() is idempotent) and
+        // would otherwise leave the FAILED result line inside a collapsed
+        // group until the unload handler runs.
+        closeTestFileGroup();
+        throw e;
       }
     },
     ignore,
diff --git a/tests/tools/check-gha-log.ts b/tests/tools/check-gha-log.ts
new file mode 100644
index 00000000000..7fdb9bcf082
--- /dev/null
+++ b/tests/tools/check-gha-log.ts
@@ -0,0 +1,157 @@
+#!/usr/bin/env -S deno run --allow-read
+/*
+ * check-gha-log.ts
+ *
+ * Dev-only regression guard for the harness's GitHub Actions log grouping
+ * (Phase 2 of dev-docs/ci-test-log-grouping-design.md). Reads a captured run
+ * log and mechanically asserts invariants 1–3:
+ *
+ *   1. No nesting — every `::group::` is closed (`::endgroup::`) before the
+ *      next one opens; no group is left open at end of log.
+ *   2. Group markers start at column 0 (the runner only parses them there).
+ *   3. No HARNESS test's `... FAILED` result line, and no `ERRORS`/`FAILURES`
+ *      section header, sits between a `::group::` and its `::endgroup::`
+ *      (failure detail must land outside collapsed groups). Non-harness
+ *      (direct `Deno.test`) FAILED lines are exempt — invariant 3 is scoped to
+ *      harness-registered tests under the lazy-closure policy.
+ *
+ * A stray `::endgroup::` with no open group is harmless (design invariant 2)
+ * and is NOT flagged.
+ *
+ * Usage:
+ *   GITHUB_ACTIONS=true ./run-tests.sh <subset> | tee log.txt
+ *   deno run --allow-read tests/tools/check-gha-log.ts log.txt
+ *
+ * Re-run on every Deno version bump: the reporter's output framing is
+ * version-sensitive (see "Spike results" / "Caveat" in the design doc).
+ *
+ * Copyright (C) 2020-2026 Posit Software, PBC
+ */
+
+import { stripAnsi } from "../../src/tools/github.ts";
+
+export interface Violation {
+  line: number;
+  message: string;
+  text: string;
+}
+
+const kGroupOpen = "::group::";
+const kGroupClose = "::endgroup::";
+// A harness test name is `[smoke] > ...` / `[unit] > ...` (see test() in
+// tests/test.ts); Deno prints its result as `<name> ... FAILED (<dur>)`.
+const kHarnessFailed = /^\[(smoke|unit)\] > .* \.\.\. FAILED/;
+const kSectionHeader = /^(ERRORS|FAILURES)$/;
+const kMarkerAnywhere = /::(group|endgroup)::/;
+
+export function checkLog(content: string): Violation[] {
+  const violations: Violation[] = [];
+  const lines = content.split("\n");
+
+  let depth = 0;
+  let openGroupLine = 0;
+  let openGroupTitle = "";
+
+  lines.forEach((raw, i) => {
+    const n = i + 1;
+    const line = stripAnsi(raw).replace(/\r$/, "");
+
+    const isGroupOpen = line.startsWith(kGroupOpen);
+    const isGroupClose = line === kGroupClose;
+
+    // Invariant 2: markers must start at column 0. A marker substring anywhere
+    // but the start of the line means the runner would not parse it.
+    if (!isGroupOpen && !isGroupClose && kMarkerAnywhere.test(line)) {
+      violations.push({
+        line: n,
+        message: "group marker not at column 0",
+        text: raw,
+      });
+      return;
+    }
+
+    if (isGroupOpen) {
+      // Invariant 1: no nesting — a group must not open while one is open.
+      if (depth > 0) {
+        violations.push({
+          line: n,
+          message:
+            `nested ::group:: — group opened at line ${openGroupLine} ` +
+            `(${openGroupTitle}) was not closed first`,
+          text: raw,
+        });
+      }
+      depth++;
+      openGroupLine = n;
+      openGroupTitle = line.slice(kGroupOpen.length);
+      return;
+    }
+
+    if (isGroupClose) {
+      // A stray ::endgroup:: at depth 0 is harmless (invariant 2) — don't go
+      // negative, don't flag.
+      if (depth > 0) depth--;
+      return;
+    }
+
+    // Invariant 3: failure detail must land outside groups.
+    if (depth > 0) {
+      if (kHarnessFailed.test(line)) {
+        violations.push({
+          line: n,
+          message:
+            `harness FAILED result line inside group ${openGroupTitle} ` +
+            `(opened at line ${openGroupLine})`,
+          text: raw,
+        });
+      } else if (kSectionHeader.test(line.trim())) {
+        violations.push({
+          line: n,
+          message:
+            `${line.trim()} section header inside group ${openGroupTitle} ` +
+            `(opened at line ${openGroupLine})`,
+          text: raw,
+        });
+      }
+    }
+  });
+
+  // Invariant 1: no group left open at end of log (unload must close it).
+  if (depth > 0) {
+    violations.push({
+      line: lines.length,
+      message:
+        `group left open at end of log: ${openGroupTitle} ` +
+        `(opened at line ${openGroupLine})`,
+      text: "",
+    });
+  }
+
+  return violations;
+}
+
+if (import.meta.main) {
+  const path = Deno.args[0];
+  if (!path) {
+    console.error("usage: check-gha-log.ts <log-file>");
+    Deno.exit(2);
+  }
+  const content = Deno.readTextFileSync(path);
+  const violations = checkLog(content);
+  if (violations.length === 0) {
+    console.log(
+      `OK: ${path} — grouping invariants hold ` +
+        "(no nesting, markers at column 0, no harness FAILED / ERRORS / " +
+        "FAILURES inside a group).",
+    );
+    Deno.exit(0);
+  }
+  console.error(
+    `FAIL: ${path} — ${violations.length} grouping violation(s):`,
+  );
+  for (const v of violations) {
+    console.error(`  line ${v.line}: ${v.message}`);
+    if (v.text) console.error(`    | ${v.text}`);
+  }
+  Deno.exit(1);
+}
diff --git a/tests/unit/gha-grouping.test.ts b/tests/unit/gha-grouping.test.ts
new file mode 100644
index 00000000000..c4d50aa89e2
--- /dev/null
+++ b/tests/unit/gha-grouping.test.ts
@@ -0,0 +1,241 @@
+/*
+ * gha-grouping.test.ts
+ *
+ * Tests for the per-test-file GitHub Actions grouping state machine (Phase 2
+ * of dev-docs/ci-test-log-grouping-design.md): open/close on file change,
+ * defensive close when nothing is open, the failure-path close + same-file
+ * reopen, the ownership gate (both env dimensions), and the single-open-group
+ * invariant.
+ *
+ * Copyright (C) 2020-2026 Posit Software, PBC
+ */
+
+import { unitTest } from "../test.ts";
+import { assert, assertEquals } from "testing/asserts";
+import { GroupEmitter, testFileUrlFromStack } from "../gha-grouping.ts";
+import { harnessOwnsStep } from "../../src/tools/github.ts";
+
+// Records every marker the emitter produces, in order, and tracks the
+// running open-group depth so the single-open-group invariant can be asserted.
+class Recorder {
+  readonly markers: string[] = [];
+  depth = 0;
+  maxDepth = 0;
+
+  start = (title: string) => {
+    this.markers.push(`group:${title}`);
+    this.depth++;
+    this.maxDepth = Math.max(this.maxDepth, this.depth);
+  };
+  end = () => {
+    this.markers.push("endgroup");
+    this.depth--;
+  };
+
+  emitter(gate: () => boolean = () => true): GroupEmitter {
+    return new GroupEmitter(gate, this.start, this.end);
+  }
+}
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - opens a group on first file", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter();
+  e.enterFile("smoke/a.test.ts");
+  // no stray endgroup before the very first group
+  assertEquals(rec.markers, ["group:smoke/a.test.ts"]);
+  assertEquals(e.currentFile(), "smoke/a.test.ts");
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - same file keeps one group open", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter();
+  e.enterFile("smoke/a.test.ts");
+  e.enterFile("smoke/a.test.ts");
+  e.enterFile("smoke/a.test.ts");
+  // repeated entries for the same file are no-ops
+  assertEquals(rec.markers, ["group:smoke/a.test.ts"]);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - file change closes then opens", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter();
+  e.enterFile("smoke/a.test.ts");
+  e.enterFile("smoke/b.test.ts");
+  assertEquals(rec.markers, [
+    "group:smoke/a.test.ts",
+    "endgroup",
+    "group:smoke/b.test.ts",
+  ]);
+  // never more than one group open at a time
+  assertEquals(rec.maxDepth, 1);
+  assertEquals(rec.depth, 1);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - close is defensive when nothing is open", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter();
+  // closing with no open group emits nothing (no stray ::endgroup::)
+  e.close();
+  assertEquals(rec.markers, []);
+  assertEquals(e.currentFile(), undefined);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - failure-path close, then same-file reopen", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter();
+  e.enterFile("smoke/a.test.ts");
+  // failure path closes the group so the FAILED line lands outside it
+  e.close();
+  assertEquals(e.currentFile(), undefined);
+  // the next test of the same file re-opens a fresh (sequential) group
+  e.enterFile("smoke/a.test.ts");
+  assertEquals(rec.markers, [
+    "group:smoke/a.test.ts",
+    "endgroup",
+    "group:smoke/a.test.ts",
+  ]);
+  assertEquals(rec.maxDepth, 1);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - double close never double-emits", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter();
+  e.enterFile("smoke/a.test.ts");
+  // failure-path close followed by the unload close
+  e.close();
+  e.close();
+  assertEquals(rec.markers, ["group:smoke/a.test.ts", "endgroup"]);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - gate off: no emission, no state change", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter(() => false);
+  e.enterFile("smoke/a.test.ts");
+  e.enterFile("smoke/b.test.ts");
+  e.close();
+  assertEquals(rec.markers, []);
+  assertEquals(e.currentFile(), undefined);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - single-open-group invariant across many files", async () => {
+  const rec = new Recorder();
+  const e = rec.emitter();
+  for (const f of ["a", "b", "c", "d"]) {
+    e.enterFile(`smoke/${f}.test.ts`);
+  }
+  e.close();
+  // depth never exceeded 1, and everything is closed at the end
+  assertEquals(rec.maxDepth, 1);
+  assertEquals(rec.depth, 0);
+  // balanced: one endgroup per group
+  const opens = rec.markers.filter((m) => m.startsWith("group:")).length;
+  const closes = rec.markers.filter((m) => m === "endgroup").length;
+  assertEquals(opens, closes);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - ownership gate honors both env dimensions", async () => {
+  // The singleton wrappers gate on harnessOwnsStep(); confirm its truth table
+  // matches the grouping contract: emit only on CI with no orchestrator.
+  // null = "treat env var as unset"; an explicit undefined would read the
+  // REAL env via the default parameter — set inside CI bucket steps.
+  assertEquals(harnessOwnsStep(true, null), true);
+  assertEquals(harnessOwnsStep(true, ""), true);
+  assertEquals(harnessOwnsStep(true, "1"), false);
+  assertEquals(harnessOwnsStep(false, null), false);
+  assertEquals(harnessOwnsStep(false, "1"), false);
+
+  // a GroupEmitter driven by that gate emits nothing when orchestrated
+  const rec = new Recorder();
+  const orchestrated = rec.emitter(() => harnessOwnsStep(true, "1"));
+  orchestrated.enterFile("smoke/a.test.ts");
+  assertEquals(rec.markers, []);
+  assert(rec.maxDepth === 0);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - stack: Linux bare frame yields the test-file URL", async () => {
+  const stack = [
+    "Error",
+    "    at testFileUrlFromStack (file:///home/runner/quarto-cli/tests/gha-grouping.ts:30:10)",
+    "    at test (file:///home/runner/quarto-cli/tests/test.ts:340:20)",
+    "    at file:///home/runner/quarto-cli/tests/unit/foo.test.ts:12:1",
+  ].join("\n");
+  // the trailing :line:column is stripped; harness frames (.ts, not .test.ts)
+  // are skipped implicitly
+  assertEquals(
+    testFileUrlFromStack(stack),
+    "file:///home/runner/quarto-cli/tests/unit/foo.test.ts",
+  );
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - stack: Windows drive-letter frame yields the test-file URL", async () => {
+  const stack = [
+    "Error",
+    "    at test (file:///C:/Users/x/quarto-cli/tests/test.ts:340:20)",
+    "    at file:///C:/Users/x/quarto-cli/tests/smoke/render/bar.test.ts:3:5",
+  ].join("\n");
+  // the drive-letter colon must not be mistaken for the :line:column suffix
+  assertEquals(
+    testFileUrlFromStack(stack),
+    "file:///C:/Users/x/quarto-cli/tests/smoke/render/bar.test.ts",
+  );
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - stack: function-wrapped frame in parentheses", async () => {
+  const stack = [
+    "Error",
+    "    at Object.fn (file:///home/runner/quarto-cli/tests/unit/baz.test.ts:9:1)",
+  ].join("\n");
+  // the wrapping parentheses are not part of the URL
+  assertEquals(
+    testFileUrlFromStack(stack),
+    "file:///home/runner/quarto-cli/tests/unit/baz.test.ts",
+  );
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - stack: first test-file frame wins over later ones", async () => {
+  const stack = [
+    "Error",
+    "    at testFileUrlFromStack (file:///home/runner/quarto-cli/tests/gha-grouping.ts:30:10)",
+    "    at test (file:///home/runner/quarto-cli/tests/test.ts:340:20)",
+    "    at file:///home/runner/quarto-cli/tests/unit/first.test.ts:5:1",
+    "    at file:///home/runner/quarto-cli/tests/unit/second.test.ts:8:1",
+  ].join("\n");
+  // reading innermost-outward, the closest test file is the registering one
+  assertEquals(
+    testFileUrlFromStack(stack),
+    "file:///home/runner/quarto-cli/tests/unit/first.test.ts",
+  );
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - stack: no test-file frame yields undefined", async () => {
+  const stack = [
+    "Error",
+    "    at testFileUrlFromStack (file:///home/runner/quarto-cli/tests/gha-grouping.ts:30:10)",
+    "    at test (file:///home/runner/quarto-cli/tests/test.ts:340:20)",
+  ].join("\n");
+  // only harness frames present — nothing to attribute the group to
+  assertEquals(testFileUrlFromStack(stack), undefined);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-grouping - stack: missing or malformed stack yields undefined", async () => {
+  // a missing stack (some runtimes), an empty string, and free text with no
+  // file:// frame all resolve to undefined rather than throwing
+  assertEquals(testFileUrlFromStack(undefined), undefined);
+  assertEquals(testFileUrlFromStack(""), undefined);
+  assertEquals(testFileUrlFromStack("not a stack trace at all"), undefined);
+});
diff --git a/tests/unit/github-actions-reporting.test.ts b/tests/unit/github-actions-reporting.test.ts
new file mode 100644
index 00000000000..257c7d3b8e9
--- /dev/null
+++ b/tests/unit/github-actions-reporting.test.ts
@@ -0,0 +1,291 @@
+/*
+ * github-actions-reporting.test.ts
+ *
+ * Tests for the GitHub Actions failure-surfacing helpers used by the test
+ * harness (dev-docs/ci-test-log-grouping-design.md): the annotation
+ * cap/aggregate counter and its step-wide ordinal, the orchestrated-mode
+ * gate, ANSI stripping, the stat-based step-summary size budget (including
+ * the degrade-to-name-only path), the failure labels, excerpt-signature
+ * clustering, the trimmed annotation body, and workflow-command escaping of
+ * hostile test names.
+ *
+ * Copyright (C) 2020-2026 Posit Software, PBC
+ */
+
+import { unitTest } from "../test.ts";
+import { assert, assertEquals } from "testing/asserts";
+import {
+  annotationBody,
+  AnnotationBudget,
+  escapeData,
+  escapeProperty,
+  excerptSignature,
+  failureLabel,
+  harnessOwnsStep,
+  kStepSummaryBudgetBytes,
+  stepSummary,
+  stepSummarySize,
+  stripAnsi,
+  summaryClusterBlock,
+  summaryTableHeader,
+  summaryTableRow,
+  summaryTableRowNameOnly,
+} from "../../src/tools/github.ts";
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - annotation budget caps at 9 then aggregates once", async () => {
+  // null counter path → instance-local state, never touches the real
+  // per-step sidecar file (which exists when this suite runs on CI)
+  const budget = new AnnotationBudget(9, null);
+  const decisions = [];
+  for (let i = 0; i < 12; i++) {
+    decisions.push(budget.recordFailure());
+  }
+  // exactly 9 per-test annotations, leaving room for one aggregate under
+  // GitHub's 10-per-step cap
+  assertEquals(decisions.filter((d) => d.emitAnnotation).length, 9);
+  assertEquals(decisions.slice(0, 9).every((d) => d.emitAnnotation), true);
+  // the 10th failure — and only the 10th — emits the single aggregate
+  assertEquals(decisions.map((d) => d.emitAggregate), [
+    false, false, false, false, false, false, false, false, false,
+    true, false, false,
+  ]);
+  // the ordinal counts every failure, uncapped
+  assertEquals(decisions.map((d) => d.ordinal), [
+    1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
+  ]);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - annotation budget honors a custom cap", async () => {
+  const budget = new AnnotationBudget(2, null);
+  assertEquals(budget.recordFailure(), { ordinal: 1, emitAnnotation: true, emitAggregate: false });
+  assertEquals(budget.recordFailure(), { ordinal: 2, emitAnnotation: true, emitAggregate: false });
+  assertEquals(budget.recordFailure(), { ordinal: 3, emitAnnotation: false, emitAggregate: true });
+  assertEquals(budget.recordFailure(), { ordinal: 4, emitAnnotation: false, emitAggregate: false });
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - annotation budget is step-wide across module instances", async () => {
+  // Deno instantiates each test file's module graph separately, so each file
+  // gets its own AnnotationBudget instance; the sidecar counter file is what
+  // makes the cap per-step. Two instances sharing one file must consume ONE
+  // budget between them, and the ordinal must keep counting across instances.
+  const counter = Deno.makeTempFileSync({ suffix: ".count" });
+  Deno.removeSync(counter); // budget must cope with a not-yet-created file
+  try {
+    const fileA = new AnnotationBudget(3, counter);
+    const fileB = new AnnotationBudget(3, counter);
+    assertEquals(fileA.recordFailure(), { ordinal: 1, emitAnnotation: true, emitAggregate: false });
+    assertEquals(fileA.recordFailure(), { ordinal: 2, emitAnnotation: true, emitAggregate: false });
+    // a fresh instance (new "file") continues the same step-wide count
+    assertEquals(fileB.recordFailure(), { ordinal: 3, emitAnnotation: true, emitAggregate: false });
+    // cap crossed in instance B: exactly one aggregate, then silence — in
+    // both instances — while the ordinal keeps climbing
+    assertEquals(fileB.recordFailure(), { ordinal: 4, emitAnnotation: false, emitAggregate: true });
+    assertEquals(fileA.recordFailure(), { ordinal: 5, emitAnnotation: false, emitAggregate: false });
+    assertEquals(fileB.recordFailure(), { ordinal: 6, emitAnnotation: false, emitAggregate: false });
+  } finally {
+    try {
+      Deno.removeSync(counter);
+    } catch {
+      // already gone
+    }
+  }
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - failureLabel prefixes the ordinal with the runner OS", async () => {
+  // RUNNER_OS is "Linux" / "Windows" / "macOS"; the prefix keeps the label a
+  // stable ASCII token that is unambiguous across the run page's concatenated
+  // per-job summaries (the label is the Ctrl+F navigation target).
+  assertEquals(failureLabel(7, "Linux"), "L-F7");
+  assertEquals(failureLabel(7, "Windows"), "W-F7");
+  assertEquals(failureLabel(7, "macOS"), "M-F7");
+  // unknown / empty runner → X
+  assertEquals(failureLabel(1, ""), "X-F1");
+  assertEquals(failureLabel(3, "FreeBSD"), "X-F3");
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - excerptSignature is the first 3 non-empty ANSI-stripped lines", async () => {
+  // blank lines are skipped, exactly three lines are taken, color codes gone;
+  // line content (including indentation) is preserved so identical failures
+  // produce byte-identical signatures.
+  const excerpt = "\x1b[31mone\x1b[0m\n\n  two  \n\nthree\nfour\nfive";
+  assertEquals(excerptSignature(excerpt), "one\n  two  \nthree");
+  // fewer than three non-empty lines → all of them
+  assertEquals(excerptSignature("only\n\n"), "only");
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - identical-error excerpts share a signature; distinct ones don't", async () => {
+  // this equality is exactly the clustering decision: same signature → same
+  // Map key → one cluster; the first line alone is too generic, hence three.
+  const a = "AssertionError: x\n  at foo\n  at bar\n  detail-a";
+  const b = "AssertionError: x\n  at foo\n  at bar\n  detail-b"; // differs past line 3
+  const c = "TypeError: y\n  at baz\n  at qux";
+  assertEquals(excerptSignature(a), excerptSignature(b), "same first 3 lines cluster");
+  assert(excerptSignature(a) !== excerptSignature(c), "different errors do not cluster");
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - annotationBody trims to repro + 5 lines + summary pointer", async () => {
+  const excerpt = "l1\nl2\nl3\nl4\nl5\nl6\nl7";
+  const body = annotationBody("./run-tests.sh x.qmd", excerpt, "L-F7");
+  assert(body.startsWith("./run-tests.sh x.qmd\n\n"), "repro then a blank line");
+  assert(body.includes("l1\nl2\nl3\nl4\nl5"), "first five excerpt lines kept");
+  assert(!body.includes("l6"), "sixth line dropped");
+  assert(body.includes("…"), "ellipsis marks the truncation");
+  assert(
+    body.trimEnd().endsWith("Full output: step summary → L-F7"),
+    "pointer line carries the label",
+  );
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - harnessOwnsStep gate", async () => {
+  // owns the step: on CI with no orchestrator claiming it. null = "treat as
+  // unset" — an explicit undefined would trigger the default parameter and
+  // read the REAL env, which IS set inside CI bucket steps, flipping this
+  // test's result depending on where it runs.
+  assertEquals(harnessOwnsStep(true, null), true);
+  assertEquals(harnessOwnsStep(true, ""), true);
+  // an outer orchestrator owns the step
+  assertEquals(harnessOwnsStep(true, "1"), false);
+  // never emits off CI
+  assertEquals(harnessOwnsStep(false, null), false);
+  assertEquals(harnessOwnsStep(false, "1"), false);
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - stripAnsi removes color codes", async () => {
+  assertEquals(stripAnsi("\x1b[31mred\x1b[0m"), "red");
+  assertEquals(stripAnsi("\x1b[1m\x1b[32mbold green\x1b[0m done"), "bold green done");
+  // plain text is untouched
+  assertEquals(stripAnsi("no color here"), "no color here");
+  // newlines are preserved (only escapes are stripped)
+  assertEquals(stripAnsi("line1\n\x1b[31mline2\x1b[0m"), "line1\nline2");
+});
+
+unitTest("gha-reporting - step summary size budget and degrade path", async () => {
+  const tmp = Deno.makeTempFileSync({ suffix: ".md" });
+  try {
+    // fresh file: size is 0, well under budget
+    assertEquals(stepSummarySize(tmp), 0);
+
+    // append accumulates and stat reflects the growth
+    stepSummary("x".repeat(100), tmp);
+    assertEquals(stepSummarySize(tmp), 100);
+    assert(stepSummarySize(tmp) < kStepSummaryBudgetBytes, "still under budget");
+
+    // push the file past the budget → the degrade decision flips
+    stepSummary("y".repeat(kStepSummaryBudgetBytes), tmp);
+    assert(
+      stepSummarySize(tmp) > kStepSummaryBudgetBytes,
+      "now over budget → callers degrade to name-only rows",
+    );
+
+    // no-op (does not throw) when the summary file is explicitly absent.
+    // null is the sentinel; an explicit `undefined` would trigger the
+    // default parameter and hit the REAL $GITHUB_STEP_SUMMARY on CI (the
+    // bug this trial-run regression guards: cderv/quarto-cli run 29767179626)
+    stepSummary("ignored", "");
+    stepSummary("ignored", null);
+    assertEquals(stepSummarySize(""), 0);
+    assertEquals(stepSummarySize(null), 0);
+  } finally {
+    Deno.removeSync(tmp);
+  }
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - summary table carries a plain-text label column", async () => {
+  // step-summary heading anchors do NOT resolve (verified: fork run
+  // 29923715216), so the label is plain text in EVERY row — no `[..](#..)`
+  // link syntax. Ctrl+F on the label still gives row ↔ detail navigation.
+  const header = summaryTableHeader();
+  assert(header.startsWith("| # | Test file | Test | Duration |"), "leading # column");
+
+  const row = summaryTableRow("L-F7", "tests/docs/smoke-all/x.qmd", "a|b\nc <tag>", 1234);
+  assert(row.startsWith("| L-F7 |"), "plain label in the # column");
+  assert(!row.includes("](#"), "no fragment-link syntax");
+  assert(row.includes("\\|"), "pipe escaped");
+  assert(!row.includes("b\nc"), "newline collapsed");
+  assert(row.includes("&lt;tag&gt;"), "angle brackets escaped");
+  assert(row.includes("1.23s"), "duration formatted");
+
+  // degraded row shares the same plain label rendering, empty duration cell
+  const nameOnly = summaryTableRowNameOnly("L-F8", "tests/docs/smoke-all/x.qmd", "a|b");
+  assert(nameOnly.startsWith("| L-F8 |"), "name-only row carries the label too");
+  assert(nameOnly.includes("\\|"), "pipe escaped in name-only row");
+  assert(nameOnly.trimEnd().endsWith("| |"), "empty duration cell");
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - single-member cluster renders a labeled detail block", async () => {
+  const block = summaryClusterBlock({
+    label: "L-F3",
+    members: [{
+      label: "L-F3",
+      file: "docs/smoke-all/x.qmd",
+      testName: "[smoke] > quarto render docs/smoke-all/x.qmd <b>",
+      repro: "./run-tests.sh docs/smoke-all/x.qmd",
+    }],
+    excerpt: "boom <script> & ``` end",
+  });
+  // the label-only heading precedes the block (the second Ctrl+F hit) and is
+  // nothing but the label, so no arbitrary test name lands in a heading
+  assert(block.includes("#### L-F3"), "label-only heading precedes the block");
+  assert(
+    block.includes("<summary><code>docs/smoke-all/x.qmd</code> — "),
+    "summary label carries the test file",
+  );
+  assert(
+    block.includes("[smoke] &gt; quarto render docs/smoke-all/x.qmd &lt;b&gt;"),
+    "test name in label is HTML-escaped",
+  );
+  assert(!block.includes("tests)</summary>"), "no (N tests) count for a single member");
+  assert(!block.includes("<summary>output</summary>"), "no anonymous label");
+  assert(block.includes("<pre>"));
+  assert(block.includes("&lt;script&gt;"), "angle brackets escaped");
+  assert(block.includes("&amp;"), "ampersand escaped");
+  assert(block.includes("./run-tests.sh docs/smoke-all/x.qmd"), "repro in the block body");
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - multi-member cluster lists members and shares one excerpt", async () => {
+  const block = summaryClusterBlock({
+    label: "L-F3",
+    members: [
+      { label: "L-F3", file: "a.qmd", testName: "first", repro: "./run-tests.sh a.qmd" },
+      { label: "L-F9", file: "b.qmd", testName: "second", repro: "./run-tests.sh b.qmd" },
+    ],
+    excerpt: "shared boom",
+  });
+  assert(block.includes("#### L-F3"), "cluster anchored on the first member's label");
+  assert(block.includes("(2 tests)"), "member count in the summary label");
+  assert(block.includes("L-F9"), "second member is listed");
+  assert(
+    block.includes("<code>b.qmd</code>") && block.includes("./run-tests.sh b.qmd"),
+    "per-member file and repro in the list",
+  );
+  // ONE shared excerpt (the first member's), not one per member
+  assertEquals(
+    (block.match(/shared boom/g) || []).length,
+    1,
+    "excerpt appears exactly once",
+  );
+});
+
+// deno-lint-ignore require-await
+unitTest("gha-reporting - escaping of hostile test names", async () => {
+  // escapeData (annotation message): %, CR, LF
+  assertEquals(escapeData("a%b\nc\rd"), "a%25b%0Ac%0Dd");
+  // escapeProperty (file=/title=): additionally : and ,
+  assertEquals(escapeProperty("a%b:c,d\ne"), "a%25b%3Ac%2Cd%0Ae");
+  // a name with :: (which would otherwise be read as a command terminator)
+  assert(escapeProperty("[smoke] > weird::name").includes("%3A%3A"));
+  // % is escaped first, so an existing %25 is not double-decoded
+  assertEquals(escapeProperty("100%,done"), "100%25%2Cdone");
+});