@celilo/e2e 0.19.2 → 0.20.0

package/src/live-stack.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { type DockerReader, LiveStackError, findLiveE2eStack } from './live-stack';
+import type { LockStatus } from './run-lock';
+import { startupCleanup } from './shared-infra';
+
+/**
+ * The live-stack guard for the startup cleanup (celilo#1297, ce-h04y).
+ *
+ * The #1297 incident: a second cele2e invocation got past the host-global run
+ * lock and nukeE2eResources force-removed another run's mid-flight stack. The
+ * guard checks Docker and the lock file at the removal site. These tests prove
+ * the wiring through the injected runner: a live stack refuses with NOTHING
+ * removed, a dead one sweeps. Delete the guard call and the first test goes
+ * red — the removal commands run behind what should have been a refusal.
+ */
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const SHARED_INFRA_SRC = readFileSync(join(DIR, 'shared-infra.ts'), 'utf-8');
+
+/** Recording fake: answers `docker ps` from `psOutput`, records every command. */
+function fakeDocker(psOutput: string): { docker: DockerReader; commands: string[] } {
+  const commands: string[] = [];
+  return {
+    commands,
+    docker: (args) => {
+      commands.push(args.join(' '));
+      if (args[0] === 'ps') return psOutput;
+      return '';
+    },
+  };
+}
+
+const noLock: () => LockStatus = () => ({
+  free: true,
+  holder: null,
+  heartbeatAgeMs: null,
+  suspect: false,
+  ownKept: false,
+});
+
+function foreignLock(overrides: Partial<LockStatus> = {}): () => LockStatus {
+  return () => ({
+    free: false,
+    holder: {
+      pid: 1,
+      hostname: hostname(),
+      session: 'polecat/ce-9999 (some other worktree)',
+      test: 'crew-alerting',
+      runId: 'run-abc',
+      startedAt: new Date(Date.now() - 5 * 60_000).toISOString(),
+      beatAt: Date.now() - 45_000,
+      state: 'running',
+    },
+    heartbeatAgeMs: 45_000,
+    suspect: false,
+    ownKept: false,
+    ...overrides,
+  });
+}
+
+describe('findLiveE2eStack', () => {
+  test('refuses when a celilo-e2e-* container is running, naming it', () => {
+    const { docker } = fakeDocker(
+      'celilo-e2e-shared_namecheap-dns\trunning\ncelilo-e2e-1788769175864_fw-main\texited\n',
+    );
+    const refusal = findLiveE2eStack(docker, noLock);
+    expect(refusal).not.toBeNull();
+    expect(refusal?.reason).toContain('celilo-e2e-shared_namecheap-dns');
+    expect(refusal?.reason).not.toContain('celilo-e2e-1788769175864_fw-main');
+    expect(refusal?.reason).toContain('cele2e down');
+    expect(refusal?.runningContainers).toEqual(['celilo-e2e-shared_namecheap-dns']);
+  });
+
+  test('proceeds when every container is exited', () => {
+    const { docker } = fakeDocker(
+      'celilo-e2e-1788769175864_fw-main\texited\ncelilo-e2e-shared_registry\tdead\n',
+    );
+    expect(findLiveE2eStack(docker, noLock)).toBeNull();
+  });
+
+  test('treats paused and restarting containers as live — they hold real state', () => {
+    for (const state of ['paused', 'restarting', 'running']) {
+      const { docker } = fakeDocker(`celilo-e2e-shared_registry\t${state}\n`);
+      const refusal = findLiveE2eStack(docker, noLock);
+      expect(refusal?.runningContainers).toEqual(['celilo-e2e-shared_registry']);
+    }
+  });
+
+  test('refuses on a foreign lock with a fresh heartbeat, naming session, test and heartbeat age', () => {
+    const { docker } = fakeDocker('');
+    const refusal = findLiveE2eStack(docker, foreignLock());
+    expect(refusal).not.toBeNull();
+    expect(refusal?.reason).toContain('polecat/ce-9999');
+    expect(refusal?.reason).toContain('crew-alerting');
+    expect(refusal?.reason).toContain('heartbeat 45s old');
+    expect(refusal?.holder?.runId).toBe('run-abc');
+  });
+
+  test('exempts our own lock — the caller holds it for its whole run', () => {
+    const { docker } = fakeDocker('');
+    const own: () => LockStatus = () => ({
+      free: false,
+      holder: {
+        pid: process.pid,
+        hostname: hostname(),
+        session: 'whatever (this worktree)',
+        test: 'caddy-internal-private',
+        runId: 'run-own',
+        startedAt: new Date().toISOString(),
+        beatAt: Date.now(),
+        state: 'running',
+      },
+      heartbeatAgeMs: 0,
+      suspect: false,
+      ownKept: false,
+    });
+    expect(findLiveE2eStack(docker, own)).toBeNull();
+  });
+
+  test('the container check has no own-lock exemption — a stolen lock says "ours" while another run owns the containers', () => {
+    // The #1297 suspected path: the second invocation ends up holding the lock
+    // while the first run's containers are still up. Only Docker can tell that
+    // truth, so running containers refuse even when the lock is ours.
+    const { docker } = fakeDocker('celilo-e2e-shared_namecheap-dns\trunning\n');
+    const refusal = findLiveE2eStack(docker, foreignLock({ holder: null }));
+    expect(refusal?.runningContainers.length).toBe(1);
+  });
+});
+
+describe('startupCleanup', () => {
+  test('refuses behind a live stack and removes NOTHING (celilo#1297)', () => {
+    const { docker, commands } = fakeDocker('celilo-e2e-shared_namecheap-dns\trunning\n');
+    expect(() => startupCleanup('/tmp/e2e', docker, noLock)).toThrow(LiveStackError);
+    // Only the ps read happened. No compose down, no rm, no prune.
+    expect(commands).toEqual([expect.stringContaining('ps -a --filter name=celilo-e2e')]);
+    expect(commands.some((c) => c.includes(' down '))).toBe(false);
+    expect(commands.some((c) => c.includes('rm -f'))).toBe(false);
+    expect(commands.some((c) => c.includes('prune'))).toBe(false);
+  });
+
+  test('sweeps when the environment is provably dead, compose down before the force sweep', () => {
+    const { docker, commands } = fakeDocker('celilo-e2e-1788769175864_fw-main\texited\n');
+    startupCleanup('/tmp/e2e', docker, noLock);
+    const down = commands.findIndex((c) => c.includes('compose -f docker-compose.shared.yml'));
+    const rm = commands.findIndex((c) => c.includes('rm -f'));
+    const netPrune = commands.findIndex((c) => c.includes('network prune'));
+    const volPrune = commands.findIndex((c) => c.includes('volume prune'));
+    expect(down).toBeGreaterThanOrEqual(0);
+    expect(rm).toBeGreaterThan(down);
+    expect(netPrune).toBeGreaterThan(rm);
+    expect(volPrune).toBeGreaterThan(netPrune);
+    // The sweep keys off the celilo-e2e prefix; it must never name the shared
+    // project in a force removal (the graceful compose down above owns that).
+    for (const command of commands.filter((c) => c.includes('rm -f'))) {
+      expect(command).not.toContain('celilo-e2e-shared');
+    }
+  });
+});
+
+// The guard is only real if it is WIRED — a perfect guard nobody calls is the
+// same failure as no guard. These source assertions pin the two removal sites
+// in ensureSharedInfra; the behavioral tests above pin the guard itself.
+describe('wiring in shared-infra.ts', () => {
+  test('the start-of-run nuke runs through startupCleanup, which guards first', () => {
+    expect(SHARED_INFRA_SRC).toContain('startupCleanup(e2eDir)');
+    const cleanupBody = SHARED_INFRA_SRC.slice(
+      SHARED_INFRA_SRC.indexOf('export function startupCleanup'),
+      SHARED_INFRA_SRC.indexOf('nukeE2eResources(e2eDir, docker)'),
+    );
+    expect(cleanupBody).toContain('findLiveE2eStack(docker, lock)');
+  });
+
+  test('the DNS-restart branch guards before tearing down the running stack', () => {
+    const branchBody = SHARED_INFRA_SRC.slice(
+      SHARED_INFRA_SRC.indexOf('DNS check failed'),
+      SHARED_INFRA_SRC.indexOf('await stopSharedInfra()'),
+    );
+    expect(branchBody).toContain('refuseOnLiveStack()');
+  });
+});

package/src/live-stack.ts

@@ -0,0 +1,145 @@
+/**
+ * Live-stack guard for the e2e startup cleanup (celilo#1297, ce-h04y).
+ *
+ * nukeE2eResources tears down EVERY celilo-e2e-* container by name prefix, on
+ * the assumption that holding the run-lock proves no other session's stack is
+ * live. The #1297 incident broke that assumption: a second invocation got past
+ * the lock anyway and force-removed another run's mid-flight stack, nine
+ * containers, the suite dead at 12.95s with exit 137. Which lock path let it
+ * through is not reconstructable, and does not need to be — the guard defends
+ * every path by checking ground truth (Docker and the lock file) at the
+ * removal site instead of trusting the lock's own verdict.
+ *
+ * Decided (peba, 2026-09-07, option a): before the startup cleanup removes
+ * anything, it refuses when any celilo-e2e-* container is still live or the
+ * run-lock heartbeat is fresh and foreign. It removes only what is provably
+ * dead. There is no --force: an operator who wants a live stack gone uses
+ * `cele2e down`.
+ *
+ * Deliberately NOT guarded: the runner's end-of-run stopSharedInfra teardown.
+ * The owner tearing down its own live stack is the normal exit path, and the
+ * guard's container check would refuse it by definition.
+ */
+
+import type { ExecFileSyncOptions } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import {
+  type LockHolder,
+  type LockStatus,
+  formatAge,
+  formatBusy,
+  heartbeatAgeMs,
+  isSameSession,
+  lockStatus,
+} from './run-lock';
+
+/**
+ * Docker access, injected so the guard and the sweep it protects are
+ * unit-testable without a daemon (the seam lane from ce-h4no). Unlike
+ * proxmox-provisioner's DockerRunner this carries per-call timeouts and cwd,
+ * which the compose sweep needs.
+ */
+export type DockerReader = (args: string[], opts?: { timeoutMs?: number; cwd?: string }) => string;
+
+export const realDocker: DockerReader = (args, opts) =>
+  execFileSync('docker', args, {
+    encoding: 'utf-8',
+    timeout: opts?.timeoutMs ?? 60_000,
+    cwd: opts?.cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  } satisfies ExecFileSyncOptions).trim();
+
+/** What the guard found, and the human-readable refusal naming it. */
+export interface LiveStackRefusal {
+  reason: string;
+  /** Container names still live, when the refusal is about containers. */
+  runningContainers: string[];
+  /** The foreign lock holder, when the refusal is about the lock. */
+  holder: LockHolder | null;
+}
+
+export class LiveStackError extends Error {
+  constructor(readonly refusal: LiveStackRefusal) {
+    super(refusal.reason);
+    this.name = 'LiveStackError';
+  }
+}
+
+/**
+ * Container states that mean the container cannot be holding a live stack.
+ * Everything else (running, paused, restarting) is live: paused containers
+ * keep their memory, restarting ones own their networks, and `docker rm -f`
+ * on either kills real work.
+ */
+const DEAD_STATES = new Set(['exited', 'created', 'dead']);
+
+function isOwnHolder(h: LockHolder): boolean {
+  return h.pid === process.pid || isSameSession(h);
+}
+
+/**
+ * Inspect the machine for a live e2e stack. Returns a refusal when the caller
+ * must not remove anything, null when the environment is provably dead.
+ *
+ * The lock check exempts our own process (the caller holds the lock for its
+ * whole run; without the exemption every run would refuse its own cleanup).
+ * The container check has NO exemption: a stolen lock (the #1297 suspected
+ * path) makes the lock file say "ours" while another run's containers are
+ * still up, so only Docker itself can tell that truth.
+ */
+export function findLiveE2eStack(
+  docker: DockerReader = realDocker,
+  lock: () => LockStatus = lockStatus,
+): LiveStackRefusal | null {
+  const status = lock();
+  if (!status.free && status.holder && !isOwnHolder(status.holder)) {
+    const h = status.holder;
+    const heartbeat =
+      h.state === 'running' ? `, heartbeat ${formatAge(heartbeatAgeMs(h))} old` : '';
+    return {
+      reason: `refusing to clean up: the run lock is held by another session — ${formatBusy(h)}${heartbeat}`,
+      runningContainers: [],
+      holder: h,
+    };
+  }
+
+  const out = docker([
+    'ps',
+    '-a',
+    '--filter',
+    'name=celilo-e2e',
+    '--format',
+    '{{.Names}}\t{{.State}}',
+  ]);
+  const running = out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => line.split('\t'))
+    .filter((parts) => parts.length === 2 && !DEAD_STATES.has(parts[1] ?? ''))
+    .map((parts) => parts[0] ?? '');
+  if (running.length > 0) {
+    return {
+      reason: `refusing to clean up: ${running.length} live celilo-e2e-* container(s):\n${running.map((n) => `  - ${n}`).join('\n')}\nA live stack owns these. Clear it with: cele2e down`,
+      runningContainers: running,
+      holder: null,
+    };
+  }
+  return null;
+}
+
+/**
+ * The startup-cleanup boundary: refuse with exit 3 when a live stack is in
+ * the way, return when the caller may remove. Exiting here (rather than
+ * throwing) is what makes the refusal survive every caller shape: the run
+ * path's bun test child, `cele2e up`, and the build paths all surface a
+ * process exit code without each one needing its own handling.
+ */
+export function refuseOnLiveStack(
+  docker: DockerReader = realDocker,
+  lock: () => LockStatus = lockStatus,
+): void {
+  const refusal = findLiveE2eStack(docker, lock);
+  if (!refusal) return;
+  console.error(`\n${refusal.reason}\n`);
+  process.exit(3);
+}

package/src/no-unjustified-sleep.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Recurrence gate for celilo#1267: readiness waits in packages/e2e must poll
+ * an observable condition (waitFor or a poll loop), never sleep a fixed
+ * duration.
+ *
+ * apps/celilo/CLAUDE.md prohibits sleeping to mask race conditions, but until
+ * now nothing enforced it in this package. respondWith slept 500ms for the
+ * responder to boot; on a loaded host that was not enough, the next command
+ * hit an unanswered interview, and the error read as a missing fixture value
+ * rather than as harness timing.
+ *
+ * The rule here: every fixed sleep in packages/e2e/src must carry an inline
+ * `e2e-sleep-ok:` justification on the same line or the line above. A poll
+ * loop's cadence sleep carries one honestly; a bare readiness gate cannot, so
+ * it fails this gate instead of failing five suites under load.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const SLEEP_PATTERN = /new Promise\(\s*\(?r\)?\s*=>\s*setTimeout\(r\s*,/;
+
+function srcDir(): string {
+  let dir = import.meta.dir;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'apps')) && existsSync(join(dir, 'modules')))
+      return join(dir, 'packages', 'e2e', 'src');
+    dir = resolve(dir, '..');
+  }
+  throw new Error('could not locate repo root (no ancestor with apps/ + modules/)');
+}
+
+function tsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...tsFiles(full));
+    else if (entry.endsWith('.ts') && !entry.endsWith('.test.ts')) out.push(full);
+  }
+  return out;
+}
+
+interface Violation {
+  file: string;
+  line: number;
+  text: string;
+}
+
+function unjustifiedSleeps(): Violation[] {
+  const violations: Violation[] = [];
+  for (const file of tsFiles(srcDir())) {
+    const lines = readFileSync(file, 'utf-8').split('\n');
+    lines.forEach((text, i) => {
+      if (!SLEEP_PATTERN.test(text)) return;
+      const justified = text.includes('e2e-sleep-ok:') || lines[i - 1]?.includes('e2e-sleep-ok:');
+      if (!justified) violations.push({ file, line: i + 1, text: text.trim() });
+    });
+  }
+  return violations;
+}
+
+describe('recurrence gate: no bare readiness sleeps in packages/e2e (celilo#1267)', () => {
+  test('the scan reaches a non-trivial set of files (sanity — it actually ran)', () => {
+    const files = tsFiles(srcDir());
+    expect(files.length).toBeGreaterThan(10);
+  });
+
+  test('every fixed sleep carries an e2e-sleep-ok justification', () => {
+    const violations = unjustifiedSleeps();
+    const report = violations
+      .map(
+        (v) =>
+          `${v.file}:${v.line}: ${v.text}\n  Add an inline \`e2e-sleep-ok: <reason>\` comment on this line or the one above, or poll an observable condition with waitFor.`,
+      )
+      .join('\n');
+    expect(violations, `Unjustified fixed sleeps:\n${report}`).toEqual([]);
+  });
+
+  test('the known poll-cadence sleeps are still present and justified (the rule engages)', () => {
+    // Reach probe, not reasoning: if the justified count drops to zero the
+    // scan is matching nothing and the gate above proves nothing.
+    const violations = unjustifiedSleeps();
+    const total = tsFiles(srcDir()).reduce((count, file) => {
+      const lines = readFileSync(file, 'utf-8').split('\n');
+      return count + lines.filter((text) => SLEEP_PATTERN.test(text)).length;
+    }, 0);
+    expect(total - violations.length).toBeGreaterThan(3);
+  });
+});

package/src/proxmox-provisioner.test.ts

@@ -9,6 +9,7 @@ import { describe, expect, test } from 'bun:test';
 import type { GuestRecord } from '@celilo/terraform-fake';
 import {
   CONTAINER_PREFIX,
+  GUEST_PROJECT_LABEL,
   containerNameFor,
   createDockerProvisioner,
   parseNet,
@@ -60,8 +61,10 @@ describe('createGuest', () => {
   });
 
   test('names the container so the debris sweep can find it', async () => {
-    // cele2e doctor and the by-name cleanup both key off this prefix; an
-    // unprefixed container leaks silently between runs.
+    // cele2e doctor keys off this prefix; an unprefixed container leaks
+    // silently between runs. Project membership is a separate concern — the
+    // per-test sweeps cannot match this name (no timestamp in it), so the
+    // label test below is what teardown actually keys off.
     const { runner, find } = stubDocker();
     await provisionerWith(runner).createGuest(guest());
 
@@ -70,6 +73,19 @@ describe('createGuest', () => {
     expect(name).toBe('celilo-e2e-lxc-203');
   });
 
+  test('labels the guest with its compose project so teardown can find it (celilo#1247)', async () => {
+    // The name cannot carry project membership (no timestamp), and compose's
+    // own labels cannot be borrowed (the guest is not a compose service, and
+    // compose down removes orphans only on the full label set — verified:
+    // a bare com.docker.compose.project label is not enough). The explicit
+    // label is what projectTeardownCommands lists guests by.
+    const { runner, find } = stubDocker();
+    await provisionerWith(runner).createGuest(guest());
+
+    const run = find('run') ?? [];
+    expect(run[run.indexOf('--label') + 1]).toBe(`${GUEST_PROJECT_LABEL}=celilo-e2e-test`);
+  });
+
   test('passes the gateway through, since target-setup routes from it', async () => {
     const { runner, find } = stubDocker();
     await provisionerWith(runner).createGuest(guest());

package/src/proxmox-provisioner.ts

@@ -30,6 +30,20 @@ import { ZONE_GATEWAYS, type Zone } from './types';
  */
 export const CONTAINER_PREFIX = 'celilo-e2e-';
 
+/**
+ * Marks a sim-created guest as belonging to a compose project.
+ *
+ * The name prefix alone is not enough for cleanup: a guest is named
+ * `celilo-e2e-lxc-<vmid>` with no timestamp in it, so every by-name filter the
+ * sweeps use (`celilo-e2e-1<ts>`, `celilo-e2e-<ts>`) misses it. A guest left
+ * behind keeps its zone network's endpoint alive, the network rm fails with
+ * "has active endpoints", and the subnet stays allocated — every later suite
+ * in the run then dies creating that network (celilo#1247). The label is what
+ * `projectTeardownCommands` filters on; it carries the project value, so
+ * teardown finds exactly the guests of the project it is tearing down.
+ */
+export const GUEST_PROJECT_LABEL = 'celilo-e2e.project';
+
 /** Shells out to `docker`. Injected so the logic is testable without a daemon. */
 export type DockerRunner = (args: string[]) => string;
 
@@ -71,6 +85,7 @@ export function zoneForGateway(gateway: string): Zone | undefined {
 export function createDockerProvisioner(options: DockerProvisionerOptions) {
   const docker = options.docker ?? realDocker;
   const readyTimeoutMs = options.readyTimeoutMs ?? 60_000;
+  // e2e-sleep-ok: injectable test seam; real callers poll a condition between sleeps.
   const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
 
   const assertOurs = (name: string): void => {
@@ -96,6 +111,12 @@ export function createDockerProvisioner(options: DockerProvisionerOptions) {
       const name = containerNameFor(guest.vmid);
       assertOurs(name);
 
+      // Project membership must be discoverable without the name: teardown
+      // matches on this label because the guest's name carries no timestamp.
+      // Added before the readiness wait, so even a guest that never finishes
+      // booting is still findable and removable.
+      const projectLabel = ['--label', `${GUEST_PROJECT_LABEL}=${options.project}`] as const;
+
       // Same image selection rule the compose generator uses for machines: the
       // app zone needs a dockerd-capable box.
       const image =
@@ -106,6 +127,7 @@ export function createDockerProvisioner(options: DockerProvisionerOptions) {
         '-d',
         '--name',
         name,
+        ...projectLabel,
         '--hostname',
         guest.hostname,
         '--network',

package/src/public-sim-routes.test.ts

@@ -34,7 +34,7 @@ const ISP_EDGE = '100.64.0.1';
 const EDGE_SERVICE = 'fw-ext';
 
 interface ComposeService {
-  build?: { dockerfile?: string };
+  image?: string;
   networks?: Record<string, unknown>;
 }
 
@@ -61,7 +61,14 @@ function publicSimulators(yaml: string): Array<{ name: string; dockerfile: strin
   const compose = parse(yaml) as { services?: Record<string, ComposeService> };
   return Object.entries(compose.services ?? {})
     .filter(([name, svc]) => name !== EDGE_SERVICE && svc.networks?.['internet-external'])
-    .map(([name, svc]) => ({ name, dockerfile: svc.build?.dockerfile ?? '' }));
+    .map(([name, svc]) => ({
+      name,
+      // The compose carries the tag, not the Dockerfile: the bake convention
+      // is tag `celilo-e2e/<name>` <-> `docker/Dockerfile.<name>` (build-infra
+      // tags every Dockerfile exactly that way). A drift in the convention
+      // makes the reads below fail loudly, which is what we want.
+      dockerfile: `docker/Dockerfile.${(svc.image ?? '').replace('celilo-e2e/', '').replace(/:.*/, '')}`,
+    }));
 }
 
 /**

package/src/repo-root.ts

@@ -0,0 +1,33 @@
+/**
+ * Where the celilo monorepo is, if we are inside one.
+ *
+ * Its own module because two unrelated consumers need it and neither may
+ * import the other: `cli/build.ts` uses it to find modules to package, and
+ * `doctor.ts` uses it to fingerprint the source a baked image came from —
+ * and `build.ts` already imports `doctor.ts`, so the reverse edge would be a
+ * cycle. Re-exported from `cli/build.ts` so its existing callers and its
+ * recurrence test are unchanged.
+ */
+
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/**
+ * Walk up from `startDir` to the celilo checkout, or null.
+ *
+ * The marker is `apps/celilo/package.json` and must stay that specific
+ * (ce-dbc): keying on a bare `modules/` directory made a stray empty
+ * `node_modules/modules` from a botched `bun add -g` read as the monorepo
+ * root, which skipped the published-staging path and crashed the packer for
+ * every npm consumer.
+ */
+export function findMonorepoRoot(startDir: string): string | null {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(dir, 'apps', 'celilo', 'package.json'))) return dir;
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}

package/src/run-args.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'bun:test';
+import { KNOWN_RUN_FLAGS, filterTestFilesByPatterns, parseRunArgs } from './run-args';
+
+describe('parseRunArgs', () => {
+  test('--help is recognized as help, never discarded into run-everything', () => {
+    const parsed = parseRunArgs(['--help']);
+    expect(parsed.helpRequested).toBe(true);
+    expect(parsed.unknownFlags).toEqual([]);
+    expect(parsed.patterns).toEqual([]);
+  });
+
+  test('every known flag is accepted and yields no patterns', () => {
+    const parsed = parseRunArgs([...KNOWN_RUN_FLAGS, '--seed=42']);
+    expect(parsed.unknownFlags).toEqual([]);
+    expect(parsed.patterns).toEqual([]);
+    expect(parsed.helpRequested).toBe(false);
+  });
+
+  test('positional patterns survive flag parsing in order', () => {
+    const parsed = parseRunArgs(['deploy', '--keep', 'caddy', '--verbose']);
+    expect(parsed.patterns).toEqual(['deploy', 'caddy']);
+    expect(parsed.unknownFlags).toEqual([]);
+  });
+
+  test('an unrecognised --flag is reported, not silently discarded', () => {
+    // The old runner stripped every --arg it did not know, leaving zero
+    // patterns: run everything. `--al` must error, not launch the catalogue.
+    const parsed = parseRunArgs(['--al', '--dry-run']);
+    expect(parsed.unknownFlags).toEqual(['--al', '--dry-run']);
+    expect(parsed.patterns).toEqual([]);
+    expect(parsed.helpRequested).toBe(false);
+  });
+
+  test('the CLI discovery aliases are unknown to the runner', () => {
+    // `cele2e run` strips --all/--all-modules before exec. If one ever
+    // reaches the runner directly it must error, not run everything.
+    const parsed = parseRunArgs(['--all', '--all-modules']);
+    expect(parsed.unknownFlags).toEqual(['--all', '--all-modules']);
+  });
+});
+
+describe('filterTestFilesByPatterns', () => {
+  const files = [
+    '/mods/knot/e2e/aspect-fanout.test.ts',
+    '/top/tests/aspect-fanout-new-systems.test.ts',
+    '/top/tests/caddy-internal-private.test.ts',
+  ];
+
+  test('an exact pattern selects only its own file, not the sibling it prefixes', () => {
+    // The old substring-OR filter dragged aspect-fanout-new-systems into
+    // `cele2e run aspect-fanout caddy-internal-private` whenever the
+    // top-level dir was in the collected set.
+    const picked = filterTestFilesByPatterns(files, ['aspect-fanout', 'caddy-internal-private']);
+    expect(picked).toEqual([
+      '/mods/knot/e2e/aspect-fanout.test.ts',
+      '/top/tests/caddy-internal-private.test.ts',
+    ]);
+  });
+
+  test('a pattern with no exact match keeps substring semantics', () => {
+    const picked = filterTestFilesByPatterns(files, ['fanout-new']);
+    expect(picked).toEqual(['/top/tests/aspect-fanout-new-systems.test.ts']);
+  });
+
+  test('several patterns union their matches', () => {
+    const picked = filterTestFilesByPatterns(files, ['aspect-fanout-new-systems', 'aspect-fanout']);
+    expect(picked).toEqual([
+      '/mods/knot/e2e/aspect-fanout.test.ts',
+      '/top/tests/aspect-fanout-new-systems.test.ts',
+    ]);
+  });
+
+  test('no patterns selects everything', () => {
+    expect(filterTestFilesByPatterns(files, [])).toEqual(files);
+  });
+});