@celilo/e2e 0.19.3 → 0.20.0

package/src/source-fingerprint.test.ts

@@ -0,0 +1,213 @@
+/**
+ * The fingerprint has one job: change when the baked CLI would change, and not
+ * otherwise. Both halves are failure modes. A fingerprint that misses an edit
+ * lets a stale image pass as fresh, which is the bug this exists to catch; one
+ * that changes on every unrelated edit produces a warning nobody reads, which
+ * is the same outcome by a different route.
+ *
+ * So each test here edits a real throwaway checkout and asserts which way the
+ * answer moved.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  applyWorkingTree,
+  bakedSourcePaths,
+  computeSourceFingerprint,
+  fingerprintFrom,
+  readWorkingTreeEntries,
+} from './source-fingerprint';
+
+let repo: string;
+
+function git(...args: string[]): void {
+  execFileSync('git', ['-C', repo, ...args], { stdio: 'ignore' });
+}
+
+function write(relative: string, content: string): void {
+  const full = join(repo, relative);
+  mkdirSync(join(full, '..'), { recursive: true });
+  writeFileSync(full, content);
+}
+
+beforeEach(() => {
+  repo = mkdtempSync(join(tmpdir(), 'fingerprint-repo-'));
+  write('apps/celilo/package.json', '{"name":"@celilo/cli","version":"1.0.0"}\n');
+  write('apps/celilo/src/index.ts', 'export const version = 1;\n');
+  write('packages/capabilities/src/index.ts', 'export const cap = 1;\n');
+  write('packages/capabilities/package.json', '{"name":"@celilo/capabilities"}\n');
+  write('packages/e2e/src/runner.ts', 'export const harness = 1;\n');
+  write('packages/e2e/package.json', '{"name":"@celilo/e2e"}\n');
+  git('init', '-q');
+  git('config', 'user.email', 'test@celilo.invalid');
+  git('config', 'user.name', 'test');
+  git('add', '-A');
+  git('commit', '-qm', 'initial');
+});
+
+afterEach(() => rmSync(repo, { recursive: true, force: true }));
+
+describe('bakedSourcePaths', () => {
+  test('covers the app and every package, derived from the tree', () => {
+    const paths = bakedSourcePaths(repo);
+    expect(paths).toContain('apps/celilo/src');
+    expect(paths).toContain('apps/celilo/drizzle');
+    expect(paths).toContain('packages/capabilities/src');
+    expect(paths).toContain('packages/capabilities/package.json');
+  });
+
+  test('excludes packages/e2e, which runs from the worktree and is never stale', () => {
+    // Including it would fire the warning continuously for anyone working on
+    // the rig, which is the fastest way to teach people to ignore it.
+    expect(bakedSourcePaths(repo).some((p) => p.startsWith('packages/e2e'))).toBe(false);
+  });
+
+  test('a new package is covered the day it is added, without editing a list', () => {
+    write('packages/brand-new/src/index.ts', 'export const x = 1;\n');
+    expect(bakedSourcePaths(repo)).toContain('packages/brand-new/src');
+  });
+});
+
+describe('fingerprintFrom', () => {
+  test('is stable for the same inputs', () => {
+    const files = [{ path: 'a.ts', hash: 'abc' }];
+    expect(fingerprintFrom(files)).toBe(fingerprintFrom(files));
+  });
+
+  test('does not depend on the order git happened to list files in', () => {
+    const a = { path: 'a.ts', hash: 'aa' };
+    const b = { path: 'b.ts', hash: 'bb' };
+    expect(fingerprintFrom([a, b])).toBe(fingerprintFrom([b, a]));
+  });
+
+  test('a changed file content is a different fingerprint', () => {
+    expect(fingerprintFrom([{ path: 'a.ts', hash: 'aa' }])).not.toBe(
+      fingerprintFrom([{ path: 'a.ts', hash: 'zz' }]),
+    );
+  });
+
+  test('a removed file is a different fingerprint', () => {
+    expect(fingerprintFrom([{ path: 'a.ts', hash: 'aa' }])).not.toBe(fingerprintFrom([]));
+  });
+});
+
+describe('applyWorkingTree', () => {
+  const tracked = [
+    { path: 'a.ts', hash: 'indexed-a' },
+    { path: 'b.ts', hash: 'indexed-b' },
+  ];
+
+  test('an edit on disk overrides what the index holds', () => {
+    const out = applyWorkingTree(tracked, [
+      { status: ' M', path: 'a.ts', contentHash: 'ondisk-a' },
+    ]);
+    expect(out.find((f) => f.path === 'a.ts')?.hash).toBe('ondisk-a');
+    expect(out.find((f) => f.path === 'b.ts')?.hash).toBe('indexed-b');
+  });
+
+  test('an untracked file is added', () => {
+    const out = applyWorkingTree(tracked, [
+      { status: '??', path: 'c.ts', contentHash: 'ondisk-c' },
+    ]);
+    expect(out).toHaveLength(3);
+  });
+
+  test('a deleted file is removed, not recorded as empty', () => {
+    const out = applyWorkingTree(tracked, [{ status: ' D', path: 'a.ts', contentHash: '' }]);
+    expect(out.map((f) => f.path)).toEqual(['b.ts']);
+  });
+});
+
+describe('computeSourceFingerprint', () => {
+  test('a clean checkout fingerprints, and repeats', () => {
+    const first = computeSourceFingerprint(repo);
+    expect(first).not.toBeNull();
+    expect(computeSourceFingerprint(repo)).toBe(first as string);
+  });
+
+  test('an UNCOMMITTED edit to baked source moves it', () => {
+    // The case that matters most in practice: an agent edits the CLI, does not
+    // commit, runs a suite, and the image is a bake behind.
+    const before = computeSourceFingerprint(repo);
+    write('apps/celilo/src/index.ts', 'export const version = 2;\n');
+    expect(computeSourceFingerprint(repo)).not.toBe(before as string);
+  });
+
+  test('a DIFFERENT BRANCH with identical baked source fingerprints the same', () => {
+    // The reason this hashes content rather than HEAD. This machine runs seven
+    // agent worktrees on seven branches against one Docker daemon, and so one
+    // baked image. Most of those branches touch no CLI source at all; keying on
+    // the commit would make every one of them disagree with the image over an
+    // unrelated change, and a warning that is usually wrong is one nobody reads.
+    const onMain = computeSourceFingerprint(repo);
+    git('checkout', '-qb', 'some-other-branch');
+    write('README.md', '# a change that touches no baked source\n');
+    git('add', '-A');
+    git('commit', '-qm', 'unrelated work');
+    expect(computeSourceFingerprint(repo)).toBe(onMain as string);
+  });
+
+  test('a committed edit moves it too', () => {
+    const before = computeSourceFingerprint(repo);
+    write('apps/celilo/src/index.ts', 'export const version = 3;\n');
+    git('add', '-A');
+    git('commit', '-qm', 'change');
+    expect(computeSourceFingerprint(repo)).not.toBe(before as string);
+  });
+
+  test('a NEW untracked file under baked source moves it', () => {
+    const before = computeSourceFingerprint(repo);
+    write('apps/celilo/src/extra.ts', 'export const extra = 1;\n');
+    expect(computeSourceFingerprint(repo)).not.toBe(before as string);
+  });
+
+  test('an edit to packages/e2e does NOT move it', () => {
+    const before = computeSourceFingerprint(repo);
+    write('packages/e2e/src/runner.ts', 'export const harness = 99;\n');
+    expect(computeSourceFingerprint(repo)).toBe(before as string);
+  });
+
+  test('an edit outside the baked paths does NOT move it', () => {
+    const before = computeSourceFingerprint(repo);
+    write('README.md', '# unrelated\n');
+    expect(computeSourceFingerprint(repo)).toBe(before as string);
+  });
+
+  test('a directory that is not a celilo checkout has no fingerprint', () => {
+    expect(computeSourceFingerprint(mkdtempSync(join(tmpdir(), 'empty-')))).toBeNull();
+  });
+
+  test('no path at all has no fingerprint — an npm consumer has no source', () => {
+    expect(computeSourceFingerprint(undefined)).toBeNull();
+  });
+});
+
+describe('readWorkingTreeEntries', () => {
+  test('reports a modified file with its current content hash', () => {
+    write('apps/celilo/src/index.ts', 'export const version = 7;\n');
+    const entries = readWorkingTreeEntries(repo, ['apps/celilo/src']);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].path).toBe('apps/celilo/src/index.ts');
+    expect(entries[0].contentHash).not.toBe('');
+  });
+
+  test('lists an untracked file individually, not collapsed to its directory', () => {
+    // Without -uall git reports `apps/celilo/src/` for a whole new subtree, and
+    // two different new files under it would fingerprint identically.
+    mkdirSync(join(repo, 'apps/celilo/src/nested'), { recursive: true });
+    write('apps/celilo/src/nested/one.ts', 'export const one = 1;\n');
+    const entries = readWorkingTreeEntries(repo, ['apps/celilo/src']);
+    expect(entries.map((e) => e.path)).toEqual(['apps/celilo/src/nested/one.ts']);
+  });
+
+  test('a deleted file is still a deviation, with no content to hash', () => {
+    rmSync(join(repo, 'apps/celilo/src/index.ts'));
+    const entries = readWorkingTreeEntries(repo, ['apps/celilo/src']);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].contentHash).toBe('');
+  });
+});

package/src/source-fingerprint.ts

@@ -0,0 +1,201 @@
+/**
+ * A fingerprint of the celilo source that `cele2e build-infra` bakes INTO
+ * `celilo-e2e/management:latest`, so a run can tell whether the image it is
+ * about to use was built from the tree it is testing.
+ *
+ * This exists because of a specific, measured hazard. The management image
+ * carries a real installed `celilo` CLI, produced by running install.sh against
+ * the simulated npm registry, which serves tarballs packed from THIS workspace.
+ * That CLI is the artifact under test. Nothing about it announces its age: a
+ * run against a month-old image looks exactly like a run against a fresh one,
+ * passes or fails for reasons that have nothing to do with the working tree,
+ * and sends the reader to the wrong file.
+ *
+ * The defence is to measure rather than to remember. build-infra stamps the
+ * fingerprint of what it packed onto the image as a label; `cele2e doctor`
+ * recomputes it from the working tree and says so when the two differ. That is
+ * a warning, never a refusal — an operator deliberately testing an older image
+ * is doing something legitimate, and should be told rather than stopped.
+ *
+ * Deliberately NOT covered: `packages/e2e` itself. The harness runs from the
+ * host worktree on every invocation (`bun` executes the checkout), so its
+ * source is never stale by construction, and including it would make the
+ * warning fire continuously for anyone working on the rig — the fastest way to
+ * teach people to ignore it.
+ *
+ * For the same reason the fingerprint is CONTENT, not commit. This machine runs
+ * seven agent worktrees on seven branches against one Docker daemon and
+ * therefore one baked image, and most of those branches do not touch the CLI at
+ * all. Hashing `HEAD` would make every one of them disagree with the image on
+ * the strength of an unrelated commit, and a warning that is usually wrong is
+ * one nobody reads. Hashing the bytes means a branch that changed no baked
+ * source agrees with the image, which is exactly what is true of it.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Docker label carrying the fingerprint. Reverse-DNS so it cannot collide with
+ * a label from a base image.
+ */
+export const SOURCE_LABEL = 'computer.celilo.e2e.source';
+
+/**
+ * Value stamped by `build-infra --published`, whose CLI comes from real npm
+ * rather than from this tree. There is no source to be stale against, so the
+ * freshness check reports the mode and stops.
+ */
+export const PUBLISHED_FINGERPRINT_PREFIX = 'published:';
+
+/**
+ * Repo-relative paths whose content reaches the baked CLI.
+ *
+ * Derived from the tree rather than listed, so a new `packages/<x>` is covered
+ * the day it is added — the failure mode of a hand-written list is that it
+ * covers what someone remembered, not what the repo contains (celilo#582).
+ */
+export function bakedSourcePaths(repoRoot: string): string[] {
+  const paths = ['apps/celilo/src', 'apps/celilo/drizzle', 'apps/celilo/package.json'];
+  const packagesDir = join(repoRoot, 'packages');
+  if (existsSync(packagesDir)) {
+    for (const name of readdirSync(packagesDir).sort()) {
+      // See the header: the harness runs from the worktree, never from the image.
+      if (name === 'e2e') continue;
+      if (!statSync(join(packagesDir, name)).isDirectory()) continue;
+      for (const sub of ['src', 'package.json']) {
+        if (existsSync(join(packagesDir, name, sub))) paths.push(`packages/${name}/${sub}`);
+      }
+    }
+  }
+  // install.sh is the script the bake actually executes; a change to it changes
+  // what lands in the image even when no package source moved.
+  const installSh = 'modules/celilo-website/site/public/install.sh';
+  if (existsSync(join(repoRoot, installSh))) paths.push(installSh);
+  return paths;
+}
+
+/** One deviation of the working tree from the index, as `git status --porcelain` reports it. */
+export interface WorkingTreeEntry {
+  /** Two-character porcelain status, e.g. ' M', '??', 'D '. */
+  status: string;
+  path: string;
+  /** sha256 of the file's current content, or '' when it no longer exists. */
+  contentHash: string;
+}
+
+/** A path and the hash of its current content. */
+export interface FileHash {
+  path: string;
+  hash: string;
+}
+
+/**
+ * The fingerprint: every baked file paired with the hash of its bytes.
+ *
+ * Pure, so the composition is testable without a repo. Two checkouts holding
+ * the same baked source fingerprint identically no matter what branch, commit
+ * or edit history produced it; changing one byte of one baked file changes it.
+ * Entries are sorted here rather than trusted from the caller, so git's output
+ * order cannot change the answer.
+ */
+export function fingerprintFrom(files: FileHash[]): string {
+  const hash = createHash('sha256');
+  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    hash.update(`${file.path} ${file.hash}\n`);
+  }
+  return hash.digest('hex').slice(0, 16);
+}
+
+function git(repoRoot: string, args: string[]): string {
+  return execFileSync('git', ['-C', repoRoot, ...args], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 15_000,
+  });
+}
+
+/**
+ * Read the working tree's deviations from HEAD across the baked paths.
+ *
+ * `--porcelain=v1 -z` is used because a path with a space in it is otherwise
+ * ambiguous, and `-uall` so an untracked FILE inside a tracked directory is
+ * listed individually rather than collapsed to its directory.
+ */
+export function readWorkingTreeEntries(repoRoot: string, paths: string[]): WorkingTreeEntry[] {
+  const raw = git(repoRoot, ['status', '--porcelain=v1', '-z', '-uall', '--', ...paths]);
+  const entries: WorkingTreeEntry[] = [];
+  for (const record of raw.split('\0')) {
+    if (record.length < 4) continue;
+    const status = record.slice(0, 2);
+    const path = record.slice(3);
+    const abs = join(repoRoot, path);
+    let contentHash = '';
+    try {
+      if (existsSync(abs) && statSync(abs).isFile()) {
+        contentHash = createHash('sha256').update(readFileSync(abs)).digest('hex').slice(0, 16);
+      }
+    } catch {
+      // Unreadable is a deviation in itself; the status char still records it.
+    }
+    entries.push({ status, path, contentHash });
+  }
+  return entries;
+}
+
+/**
+ * Every tracked file under `paths`, paired with git's own blob hash for it.
+ *
+ * `git ls-files -s` reports the index, which is content-addressed and free —
+ * git has already hashed these. It is the working tree for every file that has
+ * not been edited since it was staged, and `readWorkingTreeEntries` corrects
+ * the rest.
+ */
+export function readTrackedBlobs(repoRoot: string, paths: string[]): FileHash[] {
+  const raw = git(repoRoot, ['ls-files', '-s', '-z', '--', ...paths]);
+  const files: FileHash[] = [];
+  for (const record of raw.split('\0')) {
+    if (!record) continue;
+    // `<mode> <blob> <stage>\t<path>`
+    const [meta, path] = record.split('\t');
+    const blob = meta?.split(/\s+/)[1];
+    if (blob && path) files.push({ path, hash: blob });
+  }
+  return files;
+}
+
+/**
+ * Fold the working tree's deviations over the indexed blobs: an edited or
+ * untracked file contributes the hash of what is on disk now, a deleted one
+ * contributes nothing.
+ *
+ * Pure, so the precedence is testable without a repo.
+ */
+export function applyWorkingTree(tracked: FileHash[], entries: WorkingTreeEntry[]): FileHash[] {
+  const byPath = new Map(tracked.map((f) => [f.path, f.hash]));
+  for (const entry of entries) {
+    if (entry.contentHash === '') byPath.delete(entry.path);
+    else byPath.set(entry.path, entry.contentHash);
+  }
+  return [...byPath].map(([path, hash]) => ({ path, hash }));
+}
+
+/**
+ * The current tree's fingerprint, or null when there is no repo to read — an
+ * npm-installed consumer has no celilo checkout, and has nothing to be stale
+ * against.
+ */
+export function computeSourceFingerprint(repoRoot: string | undefined): string | null {
+  if (!repoRoot || !existsSync(join(repoRoot, 'apps', 'celilo', 'package.json'))) return null;
+  try {
+    const paths = bakedSourcePaths(repoRoot);
+    return fingerprintFrom(
+      applyWorkingTree(readTrackedBlobs(repoRoot, paths), readWorkingTreeEntries(repoRoot, paths)),
+    );
+  } catch {
+    // Not a git checkout (a tarball extraction, say). Nothing to compare.
+    return null;
+  }
+}

package/src/stage-simulator-inputs.ts

@@ -0,0 +1,93 @@
+/**
+ * Stage the two simulator inputs the DEFAULT bake's install path depends on:
+ *
+ *   .celilo-website-cache/   ← modules/celilo-website/site/dist/ — what the
+ *                              celilo-website-sim COPYs, i.e. where install.sh
+ *                              is served from.
+ *   .npm-registry-cache/     ← bun pm pack of each @celilo/* workspace pkg —
+ *                              what the npm-registry-sim COPYs, i.e. what
+ *                              install.sh's `bun add -g` installs.
+ *
+ * `cele2e build` (cli/build.ts stageSimulatorInputs) stages these PLUS the
+ * apt-repo and libsignal inputs, which nothing in the bake's install path
+ * reads. The bake calls the two functions here directly so a standalone
+ * `e2e-bake-management` re-stages exactly what it is about to install, and
+ * not the debs too — without this, the bake reinstalls whatever tarballs the
+ * last full build left in the cache, silently shipping a CLI without the
+ * tree's changes (celilo#1299).
+ *
+ * Both are .gitignored build outputs, and both images COPY them at docker
+ * build time — re-staging alone does nothing until the sim images are
+ * rebuilt, which is the bake caller's job.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const dim = '\x1b[2m';
+const green = '\x1b[32m';
+const red = '\x1b[31m';
+const reset = '\x1b[0m';
+
+/**
+ * Build the celilo-website static site and stage its dist/ into
+ * `<pkgDir>/.celilo-website-cache/`. Throws (does not exit) so library
+ * callers — the bake — fail their own run with context rather than killing
+ * the process mid-flight.
+ */
+export function stageWebsiteDist(repoRoot: string, pkgDir: string): void {
+  const websiteSrc = join(repoRoot, 'modules', 'celilo-website', 'site');
+  const websiteCache = join(pkgDir, '.celilo-website-cache');
+  if (!existsSync(websiteSrc)) return;
+
+  process.stdout.write(`  ${'celilo-website (build)'.padEnd(28)} `);
+  const t0 = Date.now();
+  let result = spawnSync('bun', ['install'], { cwd: websiteSrc, stdio: 'pipe' });
+  if (result.status !== 0) {
+    console.log(`${red}✗${reset}`);
+    throw new Error(`bun install in ${websiteSrc} failed:\n${result.stderr?.toString()}`);
+  }
+  result = spawnSync('bun', ['run', 'build'], { cwd: websiteSrc, stdio: 'pipe' });
+  if (result.status !== 0) {
+    console.log(`${red}✗${reset}`);
+    throw new Error(`bun run build in ${websiteSrc} failed:\n${result.stderr?.toString()}`);
+  }
+  console.log(`${green}✔${reset}  ${dim}${Math.round((Date.now() - t0) / 1000)}s${reset}`);
+
+  process.stdout.write(`  ${'celilo-website (stage)'.padEnd(28)} `);
+  rmSync(websiteCache, { recursive: true, force: true });
+  mkdirSync(websiteCache, { recursive: true });
+  cpSync(join(websiteSrc, 'dist'), websiteCache, { recursive: true });
+  console.log(`${green}✔${reset}`);
+}
+
+/**
+ * Pack the @celilo/* workspace packages into `<pkgDir>/.npm-registry-cache/`
+ * by running scripts/pack-celilo-packages.ts, whose manifest records the tree
+ * fingerprint the tarballs were packed from (see that script). Re-runs are
+ * cheap and always clean the destination first, so the cache can never mix
+ * tarballs from two trees.
+ */
+export function packNpmRegistryTarballs(repoRoot: string, pkgDir: string): void {
+  const packScript = join(pkgDir, 'scripts', 'pack-celilo-packages.ts');
+  if (!existsSync(packScript)) return;
+
+  process.stdout.write(`  ${'npm-registry (pack)'.padEnd(28)} `);
+  const t0 = Date.now();
+  const npmCache = join(pkgDir, '.npm-registry-cache');
+  const result = spawnSync('bun', ['run', packScript, `--dest=${npmCache}`], {
+    cwd: repoRoot,
+    stdio: 'pipe',
+  });
+  if (result.status !== 0) {
+    console.log(`${red}✗${reset}`);
+    throw new Error(`pack-celilo-packages failed:\n${result.stderr?.toString()}`);
+  }
+  const tarballCount = existsSync(npmCache)
+    ? readdirSync(npmCache).filter((f) => f.endsWith('.tgz')).length
+    : 0;
+  console.log(
+    `${green}✔${reset}  ${dim}${Math.round((Date.now() - t0) / 1000)}s, ${tarballCount} tarball(s)${reset}`,
+  );
+}

package/src/stages.ts

@@ -0,0 +1,133 @@
+/**
+ * Staged e2e suites, as one shared mechanism.
+ *
+ * A staged suite is a pipeline: stage 1 builds the fixture, later stages assert
+ * against it, and every stage after the first is guarded so one failure skips
+ * the rest instead of reporting a cascade of fake failures.
+ *
+ * Every suite used to re-declare that guard by hand: a `stageError` variable
+ * set in each stage's catch, and a `requireStage` check at the top of every
+ * later stage. The copies had a hole (celilo#1272). A stage that TIMED OUT
+ * never reached its own catch, because bun aborts the test at its cap.
+ * stageError stayed null, requireStage did not fire, and every later stage ran
+ * against a half-built fixture. The downstream error was louder than the cause
+ * and named the wrong stage.
+ *
+ * This module closes the hole. `stage()` wraps bun's test() and tracks each
+ * stage through three endings:
+ *
+ *   resolved -> completed; the next stage runs
+ *   rejected -> failed; the FIRST failure's message is recorded, and every
+ *               later stage reports `Skipped: ...`
+ *   aborted  -> the stage body never settled. This is what a bun timeout looks
+ *               like from inside: no catch, no finally, no code after the
+ *               await. The stage stays pending, and the next requireStage sees
+ *               a pending stage and skips.
+ *
+ * The `Skipped:` prefix is load-bearing: packages/e2e/src/extract-failure.ts
+ * keys on it to split real failures from cascade-skips in the run summary.
+ * Several hand-rolled copies used messages without the colon, so their
+ * cascade-skips were tallied as real failures. One message fixes that too.
+ *
+ * State lives in the closure `createStages()` returns, not in module scope. One
+ * bun process runs every test file in a suite, so a module-level tracker would
+ * leak one suite's failure into the next file's first stage.
+ */
+
+import { test } from 'bun:test';
+
+/**
+ * The stage lifecycle state machine, without bun. You almost certainly want
+ * `createStages()`, which drives this for you. Exposed separately so its
+ * contract (especially the aborted ending) has unit tests that do not need to
+ * spawn a real timed-out test.
+ */
+export interface StageGuard {
+  /** Marks a stage begun. Throws if a prior stage is still pending. */
+  begin(name: string): void;
+  /** Marks the pending stage completed successfully. */
+  ok(): void;
+  /** Marks the pending stage failed. The first failure's message wins. */
+  fail(error: unknown): void;
+  /**
+   * Throws `Skipped: <label> — <reason>` unless every stage so far completed.
+   * The reason names the first failure, or a stage that never completed.
+   */
+  requireStage(label: string): void;
+}
+
+export function createStageGuard(): StageGuard {
+  let stageError: string | null = null;
+  let pending: string | null = null;
+
+  return {
+    begin(name) {
+      if (pending !== null) {
+        throw new Error(
+          `stage "${name}" begun while "${pending}" is still pending — a stage never completed`,
+        );
+      }
+      pending = name;
+    },
+
+    ok() {
+      pending = null;
+    },
+
+    fail(error) {
+      pending = null;
+      stageError ??= error instanceof Error ? error.message : String(error);
+    },
+
+    requireStage(label) {
+      if (stageError !== null) {
+        throw new Error(`Skipped: ${label} — ${stageError}`);
+      }
+      if (pending !== null) {
+        throw new Error(
+          `Skipped: ${label} — stage "${pending}" never completed (aborted mid-flight, almost certainly a test timeout)`,
+        );
+      }
+    },
+  };
+}
+
+/** The bun adapter: registers stages as tests with cascade semantics. */
+export interface Stages {
+  /**
+   * Registers a stage as a bun test. On failure the remaining stages skip; on
+   * a bun timeout (the body never settles) they skip too. Pass the same
+   * per-stage timeout you passed to test().
+   */
+  stage(name: string, fn: () => void | Promise<void>, timeoutMs?: number): void;
+  /** For a plain test() that should skip like a stage when the pipeline broke. */
+  requireStage(label: string): void;
+}
+
+export function createStages(): Stages {
+  const guard = createStageGuard();
+
+  return {
+    stage(name, fn, timeoutMs) {
+      test(
+        name,
+        async () => {
+          guard.requireStage(name);
+          guard.begin(name);
+          try {
+            await fn();
+            guard.ok();
+          } catch (err) {
+            guard.fail(err);
+            throw err;
+          }
+        },
+        timeoutMs,
+      );
+    },
+
+    requireStage(label) {
+      guard.requireStage(label);
+    },
+  };
+}

package/src/wait-for-run.ts

@@ -129,5 +129,6 @@ export async function waitForRunCompletion(opts: WaitOptions): Promise<WaitResul
 }
 
 function sleep(ms: number): Promise<void> {
+  // e2e-sleep-ok: poll cadence for waitForRunCompletion, which polls an observable condition.
   return new Promise((r) => setTimeout(r, ms));
 }