@specific.dev/spectest 0.52.0 → 0.54.0

package/dist/daemon.js

@@ -30,6 +30,7 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // each easy to restate subtly differently.
 import { buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
@@ -102,15 +103,13 @@ const CA_BUNDLE_PATH = process.env.SPECTEST_CA_BUNDLE_PATH ?? "/etc/spectest/ca-
 // after generating the CA, so this normally already carries both halves.
 const SYSTEM_CA_BUNDLE = process.env.SPECTEST_SYSTEM_CA_BUNDLE ?? "/etc/ssl/certs/ca-certificates.crt";
 let loaded = null;
+/** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
+ *  keep the call sites reading off the suite. */
 function casesMetadata(suite) {
-    if (!suite)
-        return [];
-    return suite.tests.map((t) => ({
-        id: t.id,
-        name: t.name,
-        dependsOn: t.dependsOn?.id,
-        timeoutMs: t.timeoutMs,
-    }));
+    return catalogueCases(suite?.tests);
+}
+function groupsMetadata(suite) {
+    return catalogueGroups(suite?.tests);
 }
 // Display-only summary of the project's fakes for the control plane (folded
 // into the env config's `fakes`, surfaced on the run page). Fakes aren't part
@@ -270,11 +269,14 @@ function docker(args, timeoutMs, env) {
  * the full captured output + exit code, so existing error handling and
  * post-hoc parsing (`summarizeBuildKit`) are unchanged.
  */
-function shxStream(file, args, timeoutMs, env, onLine) {
+function shxStream(file, args, timeoutMs, env, onLine, stdin) {
     return new Promise((resolve) => {
         const child = spawn(file, args, {
             env: env ? { ...process.env, ...env } : process.env,
         });
+        if (stdin !== undefined) {
+            child.stdin?.end(stdin);
+        }
         let stdout = "";
         let stderr = "";
         let buf = "";
@@ -416,6 +418,8 @@ async function hasBuildx() {
 // in-VM builder, so a missing/dead buildkitd just means slower builds.
 const REMOTE_BUILDER_ADDR = process.env.SPECTEST_BUILDKIT_ADDR ?? "tcp://10.42.0.1:1234";
 const REMOTE_BUILDER_NAME = "spectest-remote";
+/** Parent of the per-build buildx config dirs (see isolatedBuildxConfig).
+ *  On tmpfs: each holds a builder stub and an 8-byte node id. */
 let _remoteBuilder;
 async function ensureRemoteBuilder() {
     if (_remoteBuilder !== undefined)
@@ -829,16 +833,8 @@ async function prepareServiceImage(svc, opts) {
     }
     return buildServiceImage(svc.name, image, tag);
 }
-/**
- * What the folded CA step prints when it could not write the trust store
- * at all — the one outcome that still needs {@link ensureCaTrustedImage},
- * which can take root for the write.
- *
- * The step assembles this prefix from a shell variable so that the marker
- * appears ONLY in the step's output. BuildKit echoes each instruction into
- * the same log verbatim, so a marker written literally in the RUN would
- * match on every build whether or not the step ever printed it.
- */
+/** Printed by the folded CA step when it could not write the trust
+ *  store at all — the one outcome that still needs the derivative build. */
 const CA_FOLD_UNWRITABLE = "[spectest-ca] trust store not writable";
 /**
  * The CA-trust steps as a suffix appended to a dockerfile service's OWN
@@ -1309,6 +1305,44 @@ const INGRESS_HTTP_SERVERS = new Map();
 /** Running HTTPS servers per port (currently always {INGRESS_HTTPS_PORT}). */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INGRESS_HTTPS_SERVERS = new Map();
+/**
+ * Servers replaced by a rebind and now draining. On Bun 1.3.14 a request
+ * arriving on a kept-alive connection of a `stop(false)`-drained server
+ * dispatches into freed per-server state and can SEGFAULT the process
+ * (use-after-free class fixed upstream by oven-sh/bun#36790, first in Bun
+ * 1.4.0; observed here as `panic: Segmentation fault at address 0xA` in
+ * `server.zig onRequestFor` on ~2-3 % of runtime-TLS rebinds). Until the
+ * Bun bump lands, shrink the number of requests a drained server can ever
+ * see: every response it still serves carries `Connection: close` (one
+ * more request per surviving connection, not unlimited), and a grace timer
+ * force-closes whatever is left ({@link REBIND_DRAIN_GRACE_MS}).
+ */
+const DRAINING_INGRESS = new WeakSet();
+/** How long a drained listener may keep serving in-flight work before its
+ *  remaining connections are force-closed. Long enough for a slow proxied
+ *  response to finish, short enough to bound the 1.3.14 UAF window. */
+const REBIND_DRAIN_GRACE_MS = 15_000;
+/** Stamp `Connection: close` on a response served by a draining listener so
+ *  the kept-alive connection retires instead of lingering as a UAF trigger.
+ *  Proxied responses can carry immutable headers; rewrap when needed. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function withDrainClose(server, res) {
+    if (!DRAINING_INGRESS.has(server))
+        return res;
+    try {
+        res.headers.set("connection", "close");
+        return res;
+    }
+    catch {
+        const headers = new Headers(res.headers);
+        headers.set("connection", "close");
+        return new Response(res.body, {
+            status: res.status,
+            statusText: res.statusText,
+            headers,
+        });
+    }
+}
 /**
  * The live ingress tables — per-port routes and the :443 SNI cert table.
  *
@@ -1631,6 +1665,23 @@ function rebindHttpsListener(Bun) {
             // upload through ingress must not be collateral damage of another
             // service being provisioned.
             old.stop(false);
+            // Bun 1.3.14 landmine: a request arriving later on one of the old
+            // server's kept-alive connections dispatches into freed state and can
+            // segfault the daemon (see {@link DRAINING_INGRESS}). Mark it so any
+            // response it still serves closes its connection, and force-close the
+            // stragglers once in-flight work has had a fair window to finish.
+            DRAINING_INGRESS.add(old);
+            const graceTimer = setTimeout(() => {
+                try {
+                    old.stop(true);
+                }
+                catch {
+                    /* already fully stopped */
+                }
+            }, REBIND_DRAIN_GRACE_MS);
+            // Don't let the grace timer keep the process alive on shutdown.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            graceTimer.unref?.();
         }
         catch (err) {
             // eslint-disable-next-line no-console
@@ -1770,7 +1821,7 @@ Bun, port, byHost, listenerLabel, tlsEntries) {
         // short-lived, leaked-connection risk is bounded by the fork.
         idleTimeout: 0,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto),
+        fetch: (req, server) => dispatchIngress(req, server, byHost, listenerLabel, proto).then((res) => withDrainClose(server, res)),
         websocket: {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             async open(ws) {
@@ -3312,6 +3363,26 @@ function describeRequestBody(input, init) {
     }
     return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
 }
+/**
+ * Marks an error thrown by the instrumented fetch as *transport-level* —
+ * the connection itself failed (refused, unresolvable, reset) before any
+ * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
+ * rejection short of an abort is transport. `Symbol.for` so a duplicated
+ * SDK module instance (the bun hardlink landmine) still recognises it.
+ *
+ * Why it exists: `ctx.poll` waits for convergence, and right after a fork
+ * restore the guest can serve a ~10 s window where a connect or a DNS
+ * lookup fails once and then heals (measured 2026-08-21: a poll's first
+ * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
+ * 1 while attempt 2 would have passed). During a poll, a dead connection
+ * is just "not ready yet"; outside one it stays a hard error.
+ */
+const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
+function isTransportError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err[TRANSPORT_ERROR] === true);
+}
 /**
  * Install a fetch wrapper on `globalThis` that emits HTTP events into the
  * active recorder. Returns a restore function. Calls outside of a running
@@ -3382,6 +3453,20 @@ function installFetchWrapper() {
                 durationMs: Date.now() - start,
                 error: e?.message ?? String(err),
             }, resv);
+            // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
+            // is the caller's own signal (their AbortController or their
+            // AbortSignal.timeout) — their semantics, never retried for them.
+            if (typeof err === "object" &&
+                err !== null &&
+                e?.name !== "AbortError" &&
+                e?.name !== "TimeoutError") {
+                try {
+                    err[TRANSPORT_ERROR] = true;
+                }
+                catch {
+                    /* frozen error object — stays a hard error */
+                }
+            }
             throw err;
         }
     };
@@ -3593,6 +3678,7 @@ async function pollCall(description, fn, opts) {
     let value;
     let success = false;
     let predicateError;
+    let lastTransportError;
     // Record all iterations normally, but keep only the newest one: a new
     // attempt drops the events the previous attempt emitted, so the timeline
     // never fills with polling noise. Whichever attempt is last when the loop
@@ -3622,8 +3708,19 @@ async function pollCall(description, fn, opts) {
             }
         }
         catch (err) {
-            predicateError = err;
-            break;
+            // A transport-level fetch failure (connection refused, DNS miss —
+            // see TRANSPORT_ERROR) is "not ready yet", not a verdict: polls wait
+            // for convergence, and services legitimately refuse connections
+            // while they come up. Keep polling; the kept last attempt's http
+            // event carries the error for the timeline. Anything else — an
+            // assertion, a TypeError, a user abort — stays fatal on attempt 1.
+            if (isTransportError(err)) {
+                lastTransportError = err;
+            }
+            else {
+                predicateError = err;
+                break;
+            }
         }
         if (Date.now() - start + intervalMs > timeoutMs)
             break;
@@ -3633,7 +3730,9 @@ async function pollCall(description, fn, opts) {
         ? (predicateError?.message ?? String(predicateError))
         : success
             ? undefined
-            : `timed out after ${timeoutMs}ms`;
+            : lastTransportError !== undefined
+                ? `timed out after ${timeoutMs}ms (last attempt: ${lastTransportError?.message ?? String(lastTransportError)})`
+                : `timed out after ${timeoutMs}ms`;
     const seq = recordWait({
         description,
         attempts,
@@ -3652,7 +3751,10 @@ async function pollCall(description, fn, opts) {
     if (success) {
         return wrap(value, seq);
     }
-    throw new Error(`poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`);
+    const lastAttempt = lastTransportError !== undefined
+        ? `; last attempt: ${lastTransportError?.message ?? String(lastTransportError)}`
+        : "";
+    throw new Error(`poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts${lastAttempt})`);
 }
 function captureConsole(chunks) {
     const methods = ["log", "info", "warn", "error", "debug"];
@@ -4640,6 +4742,7 @@ function loadedSummary(l) {
     return {
         environment: l.project.environment,
         cases: casesMetadata(l.project.tests),
+        groups: groupsMetadata(l.project.tests),
         fakes: fakesSummary(l.project),
     };
 }
@@ -4703,6 +4806,7 @@ export function harnessMethods(state) {
             return {
                 environment: proj.environment,
                 cases: casesMetadata(proj.tests),
+                groups: groupsMetadata(proj.tests),
                 fakes: fakesSummary(proj),
             };
         },
@@ -4737,7 +4841,10 @@ export function harnessMethods(state) {
             return loadedSummary(requireLoaded());
         },
         envConfig: async () => requireLoaded().project.environment,
-        cases: async () => ({ cases: casesMetadata(requireLoaded().project.tests) }),
+        cases: async () => ({
+            cases: casesMetadata(requireLoaded().project.tests),
+            groups: groupsMetadata(requireLoaded().project.tests),
+        }),
         // Union of platform secret refs the loaded fakes declare (replayFake's
         // `secretRefs`). The control plane resolves these server-side and pushes
         // the values on the eval path only. Empty if nothing's loaded.

package/dist/harness/catalogue.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The test catalogue the control plane reads: one entry per case, plus the
+ * display-only groups.
+ *
+ * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
+ * `cases`) return this, so the mapping lives in one place.
+ */
+/** The subset of a `TestCase` the catalogue describes. Structural, so the
+ *  mapping needs no import from the SDK entry point. */
+export interface CatalogueCase {
+    id: string;
+    name: string;
+    dependsOn?: {
+        id: string;
+    };
+    timeoutMs?: number;
+    group?: {
+        id: string;
+        name: string;
+        dependsOn?: {
+            id: string;
+        };
+    };
+}
+export interface CaseMeta {
+    id: string;
+    name: string;
+    dependsOn?: string;
+    timeoutMs?: number;
+    /** The group this case is shown in, if any. Display only — a group never
+     *  changes the DAG, which `dependsOn` still describes in full. */
+    groupId?: string;
+}
+/** A display-only test group (`env.group(...)`), for the CLI tree and the
+ *  dashboard. `dependsOn` is the group's own level: every member of the
+ *  group depends on that same case (or on nothing, at the top level). */
+export interface GroupMeta {
+    id: string;
+    name: string;
+    dependsOn?: string;
+}
+export declare function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[];
+/**
+ * The groups the suite uses, in the order their first member appears —
+ * which is the order both surfaces render in.
+ *
+ * A group is a value the tests point at, not a registry, so the list is
+ * derived here. Members of one group hold the same group value, and its id
+ * is derived from its name and its parent, so keying by id collapses them
+ * to one entry.
+ */
+export declare function groupsMetadata(cases: readonly CatalogueCase[] | undefined): GroupMeta[];

package/dist/harness/catalogue.js

@@ -0,0 +1,39 @@
+/**
+ * The test catalogue the control plane reads: one entry per case, plus the
+ * display-only groups.
+ *
+ * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
+ * `cases`) return this, so the mapping lives in one place.
+ */
+export function casesMetadata(cases) {
+    if (!cases)
+        return [];
+    return cases.map((t) => ({
+        id: t.id,
+        name: t.name,
+        dependsOn: t.dependsOn?.id,
+        timeoutMs: t.timeoutMs,
+        groupId: t.group?.id,
+    }));
+}
+/**
+ * The groups the suite uses, in the order their first member appears —
+ * which is the order both surfaces render in.
+ *
+ * A group is a value the tests point at, not a registry, so the list is
+ * derived here. Members of one group hold the same group value, and its id
+ * is derived from its name and its parent, so keying by id collapses them
+ * to one entry.
+ */
+export function groupsMetadata(cases) {
+    if (!cases)
+        return [];
+    const groups = new Map();
+    for (const t of cases) {
+        const g = t.group;
+        if (!g || groups.has(g.id))
+            continue;
+        groups.set(g.id, { id: g.id, name: g.name, dependsOn: g.dependsOn?.id });
+    }
+    return [...groups.values()];
+}

package/dist/index.d.ts

@@ -868,13 +868,69 @@ export interface TestCase<T = unknown, S extends ServicesMap = ServicesMap, F ex
     readonly name: string;
     /** Parent test, if any. Single-parent for now. */
     readonly dependsOn?: TestCase<unknown, S, F>;
+    /** The group this test is shown in, if any — set by the `group`
+     *  option, which also supplies `dependsOn`. Display only: a group
+     *  never changes how the suite runs. See {@link TestGroup}. */
+    readonly group?: TestGroup<unknown, S, F>;
     /** Override the default per-test timeout (default 60s). */
     readonly timeoutMs?: number;
     /** @internal — the body that the in-sandbox daemon invokes. */
     readonly run: TestFn<T, unknown, S, F>;
 }
+/**
+ * A named group of sibling tests, created by `env.group(...)`. A group is
+ * purely informative — the CLI and the dashboard show its name above the
+ * tests in it, and nothing about the run changes.
+ *
+ * A group holds tests at ONE level of the tree: every member shares the
+ * group's own parent. That is why a member declares `group` INSTEAD OF
+ * `dependsOn` — the group supplies the parent, so a group can never span
+ * two levels. The descendants of a member are shown inside the group as
+ * well, but they declare only their own parent, as they always did.
+ *
+ * `P` is the return type of the parent test, so a member's `ctx.parent`
+ * is typed exactly as if it had named `dependsOn` itself.
+ *
+ * ```ts
+ * export const billing = env.group("Billing");                 // top level
+ * export const createInvoice = env.test("create invoice", { group: billing }, fn);
+ * // A child. It is shown inside "Billing" already, so it names its parent.
+ * export const refund = env.test("refund", { dependsOn: createInvoice }, fn);
+ * // Groups nest through tests: this one sits under createInvoice.
+ * export const errors = env.group("Invoice errors", { dependsOn: createInvoice });
+ * ```
+ */
+export interface TestGroup<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    /** Stable id — `<parent-case-id>/<slug of name>`, or the bare slug at
+     *  top level. Derived from the name and the parent, never minted, so it
+     *  is the same in every run: the dashboard and the run diff key on it.
+     *  Qualifying by the parent is what lets the same name appear in
+     *  different parts of the tree. */
+    readonly id: string;
+    readonly name: string;
+    /** The parent test every member of this group depends on. `undefined`
+     *  for a top-level group. */
+    readonly dependsOn?: TestCase<P, S, F>;
+}
+/** Options for {@link DefinedEnvironment.group}. */
+export interface GroupOpts<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    /** The parent every member of the group depends on. Omit it for a
+     *  top-level group. */
+    dependsOn?: TestCase<P, S, F>;
+}
+/** Test options that name the parent directly. `group` is `never` here,
+ *  so giving both options is a compile error rather than a rule the
+ *  suite has to check at load time. */
 export interface TestOpts<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     dependsOn?: TestCase<P, S, F>;
+    group?: never;
+    timeoutMs?: number;
+}
+/** Test options that name a group. The group supplies the parent, so
+ *  `dependsOn` is `never` here — see {@link TestOpts}. */
+export interface GroupedTestOpts<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
+    group: TestGroup<P, S, F>;
+    dependsOn?: never;
     timeoutMs?: number;
 }
 export type TestFn<T = void, P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> = (ctx: TestContext<P, S, F>) => T | Promise<T>;
@@ -1226,6 +1282,7 @@ export type FakeHandlesFor<F extends FakesMap> = string extends keyof F ? Record
 export interface TypedTest<S extends ServicesMap, F extends FakesMap = FakesMap> {
     <T = void>(name: string, fn: TestFn<T, undefined, S, F>): TestCase<T, S, F>;
     <T = void, P = undefined>(name: string, opts: TestOpts<P, S, F>, fn: TestFn<T, P, S, F>): TestCase<T, S, F>;
+    <T = void, P = undefined>(name: string, opts: GroupedTestOpts<P, S, F>, fn: TestFn<T, P, S, F>): TestCase<T, S, F>;
 }
 /**
  * A complete project definition: an environment, an optional one-shot
@@ -1341,6 +1398,21 @@ export interface DefinedEnvironment<S extends ServicesMap, F extends FakesMap =
      * `ctx.fakes.<key>` are strongly typed against the services and fakes
      * maps. */
     readonly test: TypedTest<S, F>;
+    /**
+     * Declare a group of sibling tests, for display only. Pass the group to
+     * a test's `group` option instead of `dependsOn` — the group carries the
+     * parent, so every member sits at one level of the tree.
+     *
+     * ```ts
+     * export const billing = env.group("Billing");
+     * export const errors = env.group("Errors", { dependsOn: createInvoice });
+     * ```
+     *
+     * Two groups with the same name AND the same parent are an error:
+     * export one group value and import it where you need it. The same name
+     * under a different parent is fine.
+     */
+    group<P = undefined>(name: string, opts?: GroupOpts<P, S, F>): TestGroup<P, S, F>;
     /** Bundle this environment with a test suite into the project default
      * export. Pass tests as a plain array for the common case, or an
      * options bag to attach project-level `setup`. (Fakes are declared on

package/dist/index.js

@@ -337,6 +337,27 @@ export function defineEnvironment(input) {
         registry.push(tc);
         return tc;
     });
+    // Group ids are derived (`<parent-case-id>/<slug>`), never minted, so a
+    // group keeps its id across runs — the dashboard and the run diff key on
+    // it. Qualifying by the parent is what lets the same name be used in
+    // different parts of the tree; only two groups under the SAME parent
+    // collide, and that is the one case we refuse. Checking at creation time
+    // (rather than in `validateSuite`) puts the error at the `env.group` call
+    // that is wrong, and catches a group that no test has joined yet.
+    const groupIds = new Set();
+    const group = (name, opts) => {
+        const parent = opts?.dependsOn;
+        const slug = slugify(name, "group");
+        const id = parent ? `${parent.id}/${slug}` : slug;
+        if (groupIds.has(id)) {
+            throw new Error(`group ${JSON.stringify(name)} is declared twice${parent ? ` under "${parent.name}"` : " at the top level"} — export one group value and import it in both places`);
+        }
+        groupIds.add(id);
+        const g = parent
+            ? { id, name, dependsOn: parent }
+            : { id, name };
+        return g;
+    };
     function project(arg) {
         const opts = Array.isArray(arg)
             ? { tests: arg }
@@ -371,6 +392,7 @@ export function defineEnvironment(input) {
     return {
         config,
         test,
+        group,
         project,
     };
 }
@@ -430,7 +452,12 @@ maybeFn) {
     return {
         id: slugify(name),
         name,
-        dependsOn: opts.dependsOn,
+        // `group` and `dependsOn` are mutually exclusive in the types, so at
+        // most one of these is set. A grouped test takes the group's parent —
+        // which is what keeps a group to one level of the tree, with no rule
+        // for the suite to check.
+        dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
+        group: opts.group,
         timeoutMs: opts.timeoutMs,
         run: fn,
     };
@@ -453,13 +480,13 @@ function validateSuite(suite) {
     }
     return suite;
 }
-function slugify(name) {
+function slugify(name, kind = "test") {
     const slug = name
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "");
     if (!slug) {
-        throw new Error(`cannot derive id from test name ${JSON.stringify(name)}`);
+        throw new Error(`cannot derive id from ${kind} name ${JSON.stringify(name)}`);
     }
     return slug;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/daemon.ts

@@ -50,6 +50,12 @@ import {
   unionDockerignore,
 } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import {
+  casesMetadata as catalogueCases,
+  groupsMetadata as catalogueGroups,
+  type CaseMeta,
+  type GroupMeta,
+} from "./harness/catalogue.js";
 import { summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import {
@@ -137,6 +143,7 @@ import {
 import { deepUnwrap, readRaw, wrap, wrapResponse } from "./inspect.js";
 import type { Wrapped, WrappedResponse } from "./inspect.js";
 import { clearRecordSecrets, setRecordSecrets } from "./record-secrets.js";
+import { generateId } from "./ids.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 
 import type {
@@ -247,21 +254,14 @@ interface Loaded {
 
 let loaded: Loaded | null = null;
 
-interface CaseMeta {
-  id: string;
-  name: string;
-  dependsOn?: string;
-  timeoutMs?: number;
+/** The catalogue mapping lives in `harness/catalogue.ts`; these wrappers
+ *  keep the call sites reading off the suite. */
+function casesMetadata(suite: TestSuite | undefined): CaseMeta[] {
+  return catalogueCases(suite?.tests);
 }
 
-function casesMetadata(suite: TestSuite | undefined): CaseMeta[] {
-  if (!suite) return [];
-  return suite.tests.map((t) => ({
-    id: t.id,
-    name: t.name,
-    dependsOn: t.dependsOn?.id,
-    timeoutMs: t.timeoutMs,
-  }));
+function groupsMetadata(suite: TestSuite | undefined): GroupMeta[] {
+  return catalogueGroups(suite?.tests);
 }
 
 interface FakeMeta {
@@ -468,11 +468,15 @@ function shxStream(
   timeoutMs: number | undefined,
   env: Record<string, string> | undefined,
   onLine: (line: string) => void,
+  stdin?: string,
 ): Promise<CmdResult> {
   return new Promise((resolve) => {
     const child = spawn(file, args, {
       env: env ? { ...process.env, ...env } : process.env,
     });
+    if (stdin !== undefined) {
+      child.stdin?.end(stdin);
+    }
     let stdout = "";
     let stderr = "";
     let buf = "";
@@ -649,6 +653,8 @@ async function hasBuildx(): Promise<boolean> {
 // in-VM builder, so a missing/dead buildkitd just means slower builds.
 const REMOTE_BUILDER_ADDR = process.env.SPECTEST_BUILDKIT_ADDR ?? "tcp://10.42.0.1:1234";
 const REMOTE_BUILDER_NAME = "spectest-remote";
+/** Parent of the per-build buildx config dirs (see isolatedBuildxConfig).
+ *  On tmpfs: each holds a builder stub and an 8-byte node id. */
 let _remoteBuilder: boolean | undefined;
 async function ensureRemoteBuilder(): Promise<boolean> {
   if (_remoteBuilder !== undefined) return _remoteBuilder;
@@ -1116,16 +1122,8 @@ async function prepareServiceImage(
   return buildServiceImage(svc.name, image, tag);
 }
 
-/**
- * What the folded CA step prints when it could not write the trust store
- * at all — the one outcome that still needs {@link ensureCaTrustedImage},
- * which can take root for the write.
- *
- * The step assembles this prefix from a shell variable so that the marker
- * appears ONLY in the step's output. BuildKit echoes each instruction into
- * the same log verbatim, so a marker written literally in the RUN would
- * match on every build whether or not the step ever printed it.
- */
+/** Printed by the folded CA step when it could not write the trust
+ *  store at all — the one outcome that still needs the derivative build. */
 const CA_FOLD_UNWRITABLE = "[spectest-ca] trust store not writable";
 
 /**
@@ -1302,13 +1300,13 @@ async function runServiceBuild(
         });
         return;
       }
-      m = line.match(/^Step (\d+\/\d+)\s*:\s*(.+)$/);
-      if (m) {
-        progressService(name, {
-          status: "building",
-          detail: `step ${m[1]} ${m[2].trim().slice(0, 60)}`,
-        });
-      }
+        m = line.match(/^Step (\d+\/\d+)\s*:\s*(.+)$/);
+        if (m) {
+          progressService(name, {
+            status: "building",
+            detail: `step ${m[1]} ${m[2].trim().slice(0, 60)}`,
+          });
+        }
     });
     const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
     if (build.code !== 0) {
@@ -1679,6 +1677,43 @@ const INGRESS_HTTP_SERVERS = new Map<number, any>();
 /** Running HTTPS servers per port (currently always {INGRESS_HTTPS_PORT}). */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const INGRESS_HTTPS_SERVERS = new Map<number, any>();
+/**
+ * Servers replaced by a rebind and now draining. On Bun 1.3.14 a request
+ * arriving on a kept-alive connection of a `stop(false)`-drained server
+ * dispatches into freed per-server state and can SEGFAULT the process
+ * (use-after-free class fixed upstream by oven-sh/bun#36790, first in Bun
+ * 1.4.0; observed here as `panic: Segmentation fault at address 0xA` in
+ * `server.zig onRequestFor` on ~2-3 % of runtime-TLS rebinds). Until the
+ * Bun bump lands, shrink the number of requests a drained server can ever
+ * see: every response it still serves carries `Connection: close` (one
+ * more request per surviving connection, not unlimited), and a grace timer
+ * force-closes whatever is left ({@link REBIND_DRAIN_GRACE_MS}).
+ */
+const DRAINING_INGRESS = new WeakSet<object>();
+/** How long a drained listener may keep serving in-flight work before its
+ *  remaining connections are force-closed. Long enough for a slow proxied
+ *  response to finish, short enough to bound the 1.3.14 UAF window. */
+const REBIND_DRAIN_GRACE_MS = 15_000;
+
+/** Stamp `Connection: close` on a response served by a draining listener so
+ *  the kept-alive connection retires instead of lingering as a UAF trigger.
+ *  Proxied responses can carry immutable headers; rewrap when needed. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function withDrainClose(server: any, res: Response): Response {
+  if (!DRAINING_INGRESS.has(server)) return res;
+  try {
+    res.headers.set("connection", "close");
+    return res;
+  } catch {
+    const headers = new Headers(res.headers);
+    headers.set("connection", "close");
+    return new Response(res.body, {
+      status: res.status,
+      statusText: res.statusText,
+      headers,
+    });
+  }
+}
 /**
  * The live ingress tables — per-port routes and the :443 SNI cert table.
  *
@@ -2035,6 +2070,22 @@ function rebindHttpsListener(Bun: any): void {
       // upload through ingress must not be collateral damage of another
       // service being provisioned.
       old.stop(false);
+      // Bun 1.3.14 landmine: a request arriving later on one of the old
+      // server's kept-alive connections dispatches into freed state and can
+      // segfault the daemon (see {@link DRAINING_INGRESS}). Mark it so any
+      // response it still serves closes its connection, and force-close the
+      // stragglers once in-flight work has had a fair window to finish.
+      DRAINING_INGRESS.add(old);
+      const graceTimer = setTimeout(() => {
+        try {
+          old.stop(true);
+        } catch {
+          /* already fully stopped */
+        }
+      }, REBIND_DRAIN_GRACE_MS);
+      // Don't let the grace timer keep the process alive on shutdown.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (graceTimer as any).unref?.();
     } catch (err) {
       // eslint-disable-next-line no-console
       console.warn("[ingress] failed to drain the previous https listener:", err);
@@ -2193,7 +2244,9 @@ function bindIngressServer(
     idleTimeout: 0,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     fetch: (req: Request, server: any): Response | Promise<Response> =>
-      dispatchIngress(req, server, byHost, listenerLabel, proto),
+      dispatchIngress(req, server, byHost, listenerLabel, proto).then((res) =>
+        withDrainClose(server, res),
+      ),
     websocket: {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       async open(ws: any) {
@@ -4092,6 +4145,30 @@ function describeRequestBody(
   return { body: `[non-text body: ${body.constructor?.name ?? typeof body}]` };
 }
 
+/**
+ * Marks an error thrown by the instrumented fetch as *transport-level* —
+ * the connection itself failed (refused, unresolvable, reset) before any
+ * HTTP reply existed. `fetch` never rejects for an HTTP status, so every
+ * rejection short of an abort is transport. `Symbol.for` so a duplicated
+ * SDK module instance (the bun hardlink landmine) still recognises it.
+ *
+ * Why it exists: `ctx.poll` waits for convergence, and right after a fork
+ * restore the guest can serve a ~10 s window where a connect or a DNS
+ * lookup fails once and then heals (measured 2026-08-21: a poll's first
+ * fetch hung 12 s in resolution, threw, and killed a 60 s poll on attempt
+ * 1 while attempt 2 would have passed). During a poll, a dead connection
+ * is just "not ready yet"; outside one it stays a hard error.
+ */
+const TRANSPORT_ERROR = Symbol.for("spectest.transportError");
+
+function isTransportError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as Record<symbol, unknown>)[TRANSPORT_ERROR] === true
+  );
+}
+
 /**
  * Install a fetch wrapper on `globalThis` that emits HTTP events into the
  * active recorder. Returns a restore function. Calls outside of a running
@@ -4161,6 +4238,21 @@ function installFetchWrapper(): () => void {
         durationMs: Date.now() - start,
         error: e?.message ?? String(err),
       }, resv);
+      // Tag transport failures for ctx.poll (see TRANSPORT_ERROR). An abort
+      // is the caller's own signal (their AbortController or their
+      // AbortSignal.timeout) — their semantics, never retried for them.
+      if (
+        typeof err === "object" &&
+        err !== null &&
+        e?.name !== "AbortError" &&
+        e?.name !== "TimeoutError"
+      ) {
+        try {
+          (err as Record<symbol, unknown>)[TRANSPORT_ERROR] = true;
+        } catch {
+          /* frozen error object — stays a hard error */
+        }
+      }
       throw err;
     }
   };
@@ -4412,6 +4504,7 @@ async function pollCall<T>(
   let value: T | undefined;
   let success = false;
   let predicateError: unknown;
+  let lastTransportError: unknown;
 
   // Record all iterations normally, but keep only the newest one: a new
   // attempt drops the events the previous attempt emitted, so the timeline
@@ -4442,8 +4535,18 @@ async function pollCall<T>(
         break;
       }
     } catch (err) {
-      predicateError = err;
-      break;
+      // A transport-level fetch failure (connection refused, DNS miss —
+      // see TRANSPORT_ERROR) is "not ready yet", not a verdict: polls wait
+      // for convergence, and services legitimately refuse connections
+      // while they come up. Keep polling; the kept last attempt's http
+      // event carries the error for the timeline. Anything else — an
+      // assertion, a TypeError, a user abort — stays fatal on attempt 1.
+      if (isTransportError(err)) {
+        lastTransportError = err;
+      } else {
+        predicateError = err;
+        break;
+      }
     }
     if (Date.now() - start + intervalMs > timeoutMs) break;
     await new Promise((r) => setTimeout(r, intervalMs));
@@ -4454,7 +4557,11 @@ async function pollCall<T>(
       ? ((predicateError as Error)?.message ?? String(predicateError))
       : success
         ? undefined
-        : `timed out after ${timeoutMs}ms`;
+        : lastTransportError !== undefined
+          ? `timed out after ${timeoutMs}ms (last attempt: ${
+              (lastTransportError as Error)?.message ?? String(lastTransportError)
+            })`
+          : `timed out after ${timeoutMs}ms`;
   const seq = recordWait({
     description,
     attempts,
@@ -4474,8 +4581,12 @@ async function pollCall<T>(
   if (success) {
     return wrap(value as T, seq) as T;
   }
+  const lastAttempt =
+    lastTransportError !== undefined
+      ? `; last attempt: ${(lastTransportError as Error)?.message ?? String(lastTransportError)}`
+      : "";
   throw new Error(
-    `poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`,
+    `poll ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts${lastAttempt})`,
   );
 }
 
@@ -5651,6 +5762,7 @@ function loadedSummary(l: ReturnType<typeof requireLoaded>) {
   return {
     environment: l.project.environment,
     cases: casesMetadata(l.project.tests),
+    groups: groupsMetadata(l.project.tests),
     fakes: fakesSummary(l.project),
   };
 }
@@ -5719,6 +5831,7 @@ export function harnessMethods(state: RouteState): MethodTable {
       return {
         environment: proj.environment,
         cases: casesMetadata(proj.tests),
+        groups: groupsMetadata(proj.tests),
         fakes: fakesSummary(proj),
       };
     },
@@ -5758,7 +5871,10 @@ export function harnessMethods(state: RouteState): MethodTable {
 
     envConfig: async () => requireLoaded().project.environment,
 
-    cases: async () => ({ cases: casesMetadata(requireLoaded().project.tests) }),
+    cases: async () => ({
+      cases: casesMetadata(requireLoaded().project.tests),
+      groups: groupsMetadata(requireLoaded().project.tests),
+    }),
 
     // Union of platform secret refs the loaded fakes declare (replayFake's
     // `secretRefs`). The control plane resolves these server-side and pushes

package/src/groups.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+
+import { defineEnvironment } from "./index";
+
+const newEnv = () =>
+  defineEnvironment({
+    name: "groups",
+    services: { web: { image: { type: "registry", reference: "nginx" } } },
+  });
+
+describe("env.group", () => {
+  test("a member takes the group's parent, so a group is one level", () => {
+    const env = newEnv();
+    const parent = env.test("create invoice", async () => ({ id: 7 }));
+    const errors = env.group("Errors", { dependsOn: parent });
+    const member = env.test("refund too much", { group: errors }, async () => {});
+
+    expect(member.dependsOn).toBe(parent);
+    expect(member.group).toBe(errors);
+  });
+
+  test("a top-level group leaves its members roots", () => {
+    const env = newEnv();
+    const billing = env.group("Billing");
+    const member = env.test("create invoice", { group: billing }, async () => {});
+
+    expect(member.dependsOn).toBeUndefined();
+    expect(member.group!.id).toBe("billing");
+  });
+
+  test("the id is qualified by the parent, so a name can repeat elsewhere", () => {
+    const env = newEnv();
+    const a = env.test("create invoice", async () => {});
+    const b = env.test("refund", { dependsOn: a }, async () => {});
+
+    expect(env.group("Errors", { dependsOn: a }).id).toBe("create-invoice/errors");
+    expect(env.group("Errors", { dependsOn: b }).id).toBe("refund/errors");
+    expect(env.group("Errors").id).toBe("errors");
+  });
+
+  test("two groups with the same name and parent are refused", () => {
+    const env = newEnv();
+    const parent = env.test("create invoice", async () => {});
+    env.group("Errors", { dependsOn: parent });
+
+    expect(() => env.group("Errors", { dependsOn: parent })).toThrow(
+      /"Errors" is declared twice under "create invoice"/,
+    );
+  });
+
+  test("two top-level groups with the same name are refused", () => {
+    const env = newEnv();
+    env.group("Billing");
+    expect(() => env.group("Billing")).toThrow(/twice at the top level/);
+  });
+
+  test("a grouped test still validates its parent is in the suite", () => {
+    const env = newEnv();
+    const parent = env.test("create invoice", async () => {});
+    const errors = env.group("Errors", { dependsOn: parent });
+    const member = env.test("refund too much", { group: errors }, async () => {});
+
+    expect(() => env.project({ tests: [member] }).tests).toThrow(
+      /depends on "create invoice" which is not in the suite/,
+    );
+    expect(env.project({ tests: [parent, member] }).tests!.tests).toHaveLength(2);
+  });
+});

package/src/harness/catalogue.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+
+import { casesMetadata, groupsMetadata, type CatalogueCase } from "./catalogue";
+
+const billing = { id: "billing", name: "Billing" };
+const errors = {
+  id: "create-invoice/errors",
+  name: "Errors",
+  dependsOn: { id: "create-invoice" },
+};
+
+const cases: CatalogueCase[] = [
+  { id: "create-invoice", name: "create invoice", group: billing },
+  { id: "list-invoices", name: "list invoices", group: billing },
+  { id: "refund", name: "refund", dependsOn: { id: "create-invoice" } },
+  {
+    id: "refund-too-much",
+    name: "refund too much",
+    dependsOn: { id: "create-invoice" },
+    group: errors,
+    timeoutMs: 1000,
+  },
+];
+
+describe("casesMetadata", () => {
+  test("flattens the case refs to ids", () => {
+    expect(casesMetadata(cases)[3]).toEqual({
+      id: "refund-too-much",
+      name: "refund too much",
+      dependsOn: "create-invoice",
+      timeoutMs: 1000,
+      groupId: "create-invoice/errors",
+    });
+  });
+
+  test("a case in no group carries no group id", () => {
+    expect(casesMetadata(cases)[2]!.groupId).toBeUndefined();
+  });
+
+  test("no suite is an empty catalogue", () => {
+    expect(casesMetadata(undefined)).toEqual([]);
+  });
+});
+
+describe("groupsMetadata", () => {
+  test("one entry per group, where its first member appears", () => {
+    expect(groupsMetadata(cases)).toEqual([
+      { id: "billing", name: "Billing", dependsOn: undefined },
+      {
+        id: "create-invoice/errors",
+        name: "Errors",
+        dependsOn: "create-invoice",
+      },
+    ]);
+  });
+
+  test("a suite with no groups has none", () => {
+    expect(groupsMetadata([{ id: "a", name: "a" }])).toEqual([]);
+    expect(groupsMetadata(undefined)).toEqual([]);
+  });
+});

package/src/harness/catalogue.ts

@@ -0,0 +1,67 @@
+/**
+ * The test catalogue the control plane reads: one entry per case, plus the
+ * display-only groups.
+ *
+ * Ported out of `daemon.ts`. Three harness methods (`load`, `loadTests`,
+ * `cases`) return this, so the mapping lives in one place.
+ */
+
+/** The subset of a `TestCase` the catalogue describes. Structural, so the
+ *  mapping needs no import from the SDK entry point. */
+export interface CatalogueCase {
+  id: string;
+  name: string;
+  dependsOn?: { id: string };
+  timeoutMs?: number;
+  group?: { id: string; name: string; dependsOn?: { id: string } };
+}
+
+export interface CaseMeta {
+  id: string;
+  name: string;
+  dependsOn?: string;
+  timeoutMs?: number;
+  /** The group this case is shown in, if any. Display only — a group never
+   *  changes the DAG, which `dependsOn` still describes in full. */
+  groupId?: string;
+}
+
+/** A display-only test group (`env.group(...)`), for the CLI tree and the
+ *  dashboard. `dependsOn` is the group's own level: every member of the
+ *  group depends on that same case (or on nothing, at the top level). */
+export interface GroupMeta {
+  id: string;
+  name: string;
+  dependsOn?: string;
+}
+
+export function casesMetadata(cases: readonly CatalogueCase[] | undefined): CaseMeta[] {
+  if (!cases) return [];
+  return cases.map((t) => ({
+    id: t.id,
+    name: t.name,
+    dependsOn: t.dependsOn?.id,
+    timeoutMs: t.timeoutMs,
+    groupId: t.group?.id,
+  }));
+}
+
+/**
+ * The groups the suite uses, in the order their first member appears —
+ * which is the order both surfaces render in.
+ *
+ * A group is a value the tests point at, not a registry, so the list is
+ * derived here. Members of one group hold the same group value, and its id
+ * is derived from its name and its parent, so keying by id collapses them
+ * to one entry.
+ */
+export function groupsMetadata(cases: readonly CatalogueCase[] | undefined): GroupMeta[] {
+  if (!cases) return [];
+  const groups = new Map<string, GroupMeta>();
+  for (const t of cases) {
+    const g = t.group;
+    if (!g || groups.has(g.id)) continue;
+    groups.set(g.id, { id: g.id, name: g.name, dependsOn: g.dependsOn?.id });
+  }
+  return [...groups.values()];
+}

package/src/index.ts

@@ -1330,18 +1330,89 @@ export interface TestCase<
   readonly name: string;
   /** Parent test, if any. Single-parent for now. */
   readonly dependsOn?: TestCase<unknown, S, F>;
+  /** The group this test is shown in, if any — set by the `group`
+   *  option, which also supplies `dependsOn`. Display only: a group
+   *  never changes how the suite runs. See {@link TestGroup}. */
+  readonly group?: TestGroup<unknown, S, F>;
   /** Override the default per-test timeout (default 60s). */
   readonly timeoutMs?: number;
   /** @internal — the body that the in-sandbox daemon invokes. */
   readonly run: TestFn<T, unknown, S, F>;
 }
 
+/**
+ * A named group of sibling tests, created by `env.group(...)`. A group is
+ * purely informative — the CLI and the dashboard show its name above the
+ * tests in it, and nothing about the run changes.
+ *
+ * A group holds tests at ONE level of the tree: every member shares the
+ * group's own parent. That is why a member declares `group` INSTEAD OF
+ * `dependsOn` — the group supplies the parent, so a group can never span
+ * two levels. The descendants of a member are shown inside the group as
+ * well, but they declare only their own parent, as they always did.
+ *
+ * `P` is the return type of the parent test, so a member's `ctx.parent`
+ * is typed exactly as if it had named `dependsOn` itself.
+ *
+ * ```ts
+ * export const billing = env.group("Billing");                 // top level
+ * export const createInvoice = env.test("create invoice", { group: billing }, fn);
+ * // A child. It is shown inside "Billing" already, so it names its parent.
+ * export const refund = env.test("refund", { dependsOn: createInvoice }, fn);
+ * // Groups nest through tests: this one sits under createInvoice.
+ * export const errors = env.group("Invoice errors", { dependsOn: createInvoice });
+ * ```
+ */
+export interface TestGroup<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /** Stable id — `<parent-case-id>/<slug of name>`, or the bare slug at
+   *  top level. Derived from the name and the parent, never minted, so it
+   *  is the same in every run: the dashboard and the run diff key on it.
+   *  Qualifying by the parent is what lets the same name appear in
+   *  different parts of the tree. */
+  readonly id: string;
+  readonly name: string;
+  /** The parent test every member of this group depends on. `undefined`
+   *  for a top-level group. */
+  readonly dependsOn?: TestCase<P, S, F>;
+}
+
+/** Options for {@link DefinedEnvironment.group}. */
+export interface GroupOpts<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  /** The parent every member of the group depends on. Omit it for a
+   *  top-level group. */
+  dependsOn?: TestCase<P, S, F>;
+}
+
+/** Test options that name the parent directly. `group` is `never` here,
+ *  so giving both options is a compile error rather than a rule the
+ *  suite has to check at load time. */
 export interface TestOpts<
   P = undefined,
   S extends ServicesMap = ServicesMap,
   F extends FakesMap = FakesMap,
 > {
   dependsOn?: TestCase<P, S, F>;
+  group?: never;
+  timeoutMs?: number;
+}
+
+/** Test options that name a group. The group supplies the parent, so
+ *  `dependsOn` is `never` here — see {@link TestOpts}. */
+export interface GroupedTestOpts<
+  P = undefined,
+  S extends ServicesMap = ServicesMap,
+  F extends FakesMap = FakesMap,
+> {
+  group: TestGroup<P, S, F>;
+  dependsOn?: never;
   timeoutMs?: number;
 }
 
@@ -1772,6 +1843,11 @@ export interface TypedTest<
     opts: TestOpts<P, S, F>,
     fn: TestFn<T, P, S, F>,
   ): TestCase<T, S, F>;
+  <T = void, P = undefined>(
+    name: string,
+    opts: GroupedTestOpts<P, S, F>,
+    fn: TestFn<T, P, S, F>,
+  ): TestCase<T, S, F>;
 }
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -1914,6 +1990,24 @@ export interface DefinedEnvironment<
    * `ctx.fakes.<key>` are strongly typed against the services and fakes
    * maps. */
   readonly test: TypedTest<S, F>;
+  /**
+   * Declare a group of sibling tests, for display only. Pass the group to
+   * a test's `group` option instead of `dependsOn` — the group carries the
+   * parent, so every member sits at one level of the tree.
+   *
+   * ```ts
+   * export const billing = env.group("Billing");
+   * export const errors = env.group("Errors", { dependsOn: createInvoice });
+   * ```
+   *
+   * Two groups with the same name AND the same parent are an error:
+   * export one group value and import it where you need it. The same name
+   * under a different parent is fine.
+   */
+  group<P = undefined>(
+    name: string,
+    opts?: GroupOpts<P, S, F>,
+  ): TestGroup<P, S, F>;
   /** Bundle this environment with a test suite into the project default
    * export. Pass tests as a plain array for the common case, or an
    * options bag to attach project-level `setup`. (Fakes are declared on
@@ -2023,6 +2117,35 @@ export function defineEnvironment<
     return tc;
   }) as unknown as TypedTest<S, F>;
 
+  // Group ids are derived (`<parent-case-id>/<slug>`), never minted, so a
+  // group keeps its id across runs — the dashboard and the run diff key on
+  // it. Qualifying by the parent is what lets the same name be used in
+  // different parts of the tree; only two groups under the SAME parent
+  // collide, and that is the one case we refuse. Checking at creation time
+  // (rather than in `validateSuite`) puts the error at the `env.group` call
+  // that is wrong, and catches a group that no test has joined yet.
+  const groupIds = new Set<string>();
+  const group = <P = undefined>(
+    name: string,
+    opts?: GroupOpts<P, S, F>,
+  ): TestGroup<P, S, F> => {
+    const parent = opts?.dependsOn;
+    const slug = slugify(name, "group");
+    const id = parent ? `${parent.id}/${slug}` : slug;
+    if (groupIds.has(id)) {
+      throw new Error(
+        `group ${JSON.stringify(name)} is declared twice${
+          parent ? ` under "${parent.name}"` : " at the top level"
+        } — export one group value and import it in both places`,
+      );
+    }
+    groupIds.add(id);
+    const g: TestGroup<P, S, F> = parent
+      ? { id, name, dependsOn: parent }
+      : { id, name };
+    return g;
+  };
+
   function project(
     arg?: TestCase<unknown, S, F>[] | ProjectOpts<S, F>,
   ): Project<S, F> {
@@ -2056,6 +2179,7 @@ export function defineEnvironment<
   return {
     config,
     test,
+    group,
     project,
   };
 }
@@ -2113,12 +2237,12 @@ function validateFakes(env: EnvironmentConfig, fakes: FakesMap): void {
 function buildTestCase(
   name: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  optsOrFn: TestOpts<any> | TestFn<unknown, any>,
+  optsOrFn: AnyTestOpts | TestFn<unknown, any>,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   maybeFn?: TestFn<unknown, any>,
 ): TestCase<unknown> {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const [opts, fn]: [TestOpts<any>, TestFn<unknown, any>] =
+  const [opts, fn]: [AnyTestOpts, TestFn<unknown, any>] =
     typeof optsOrFn === "function" ? [{}, optsOrFn] : [optsOrFn, maybeFn!];
   if (typeof fn !== "function") {
     throw new TypeError(
@@ -2128,12 +2252,27 @@ function buildTestCase(
   return {
     id: slugify(name),
     name,
-    dependsOn: opts.dependsOn,
+    // `group` and `dependsOn` are mutually exclusive in the types, so at
+    // most one of these is set. A grouped test takes the group's parent —
+    // which is what keeps a group to one level of the tree, with no rule
+    // for the suite to check.
+    dependsOn: opts.dependsOn ?? opts.group?.dependsOn,
+    group: opts.group,
     timeoutMs: opts.timeoutMs,
     run: fn,
   };
 }
 
+/** The two option shapes as one, for the untyped runtime implementation.
+ *  The public overloads keep them apart — see {@link TestOpts}. */
+interface AnyTestOpts {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  dependsOn?: TestCase<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  group?: TestGroup<any>;
+  timeoutMs?: number;
+}
+
 function validateSuite<
   S extends ServicesMap,
   F extends FakesMap,
@@ -2162,13 +2301,15 @@ function validateSuite<
   return suite;
 }
 
-function slugify(name: string): string {
+function slugify(name: string, kind: "test" | "group" = "test"): string {
   const slug = name
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
   if (!slug) {
-    throw new Error(`cannot derive id from test name ${JSON.stringify(name)}`);
+    throw new Error(
+      `cannot derive id from ${kind} name ${JSON.stringify(name)}`,
+    );
   }
   return slug;
 }