@celilo/e2e 0.7.17 → 0.9.0

package/src/cli/build.ts

@@ -19,10 +19,11 @@
  */
 
 import { execSync, spawnSync } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { ensureRegistryServerBundle } from '../registry-bundle';
+import { gunzipSync } from 'node:zlib';
 import { stageAptRepo } from '../../scripts/stage-apt-repo';
+import { ensureRegistryServerBundle } from '../registry-bundle';
 
 /** Walk up from pkgDir to find the monorepo root (contains a `modules/` dir). */
 function findMonorepoRoot(pkgDir: string): string | null {
@@ -56,6 +57,13 @@ interface BuildOptions {
   moduleDirs: string[];
   save: boolean;
   skipModules: boolean;
+  /**
+   * Bake `management:latest` from the PUBLISHED @celilo/cli on real npm
+   * instead of the monorepo DEV cli served by the sim registry. Runs a
+   * standalone container on the default docker network (real internet) —
+   * the simulated topology has no route to npmjs.org.
+   */
+  published: boolean;
 }
 
 /**
@@ -75,7 +83,7 @@ interface BuildOptions {
  * keeps build-infra working in npm-installed @celilo/e2e, where these
  * staging dirs aren't relevant.
  */
-function stageSimulatorInputs(pkgDir: string): void {
+async function stageSimulatorInputs(pkgDir: string): Promise<void> {
   // Try CWD first — when cele2e is installed globally, `pkgDir` is
   // somewhere like `~/.bun/install/global/node_modules/@celilo/e2e`,
   // which doesn't have a `modules/` sibling. Walking up from CWD
@@ -84,7 +92,13 @@ function stageSimulatorInputs(pkgDir: string): void {
   // Mirrors the same CWD-then-pkgDir pattern used for module
   // discovery further down.
   const repoRoot = findMonorepoRoot(process.cwd()) ?? findMonorepoRoot(pkgDir);
-  if (!repoRoot) return;
+  if (!repoRoot) {
+    // No monorepo (npm-installed @celilo/e2e) → fetch the same caches from
+    // the public celilo sources instead of building them from workspace
+    // source, so build-infra still works for a monorepo-free consumer (ce-i2i).
+    await stageFromPublic(pkgDir);
+    return;
+  }
 
   const websiteSrc = join(repoRoot, 'modules', 'celilo-website', 'site');
   const websiteCache = join(pkgDir, '.celilo-website-cache');
@@ -154,6 +168,201 @@ function stageSimulatorInputs(pkgDir: string): void {
   console.log('');
 }
 
+/**
+ * The published @celilo/* packages the npm-registry-sim must serve so
+ * install.sh's `bun add -g @celilo/cli @celilo/event-bus @celilo/e2e`
+ * resolves its full transitive closure against the sim. Mirrors
+ * PACKAGES_TO_PACK in scripts/pack-celilo-packages.ts (the monorepo
+ * equivalent that packs from workspace source instead of fetching).
+ */
+const PUBLISHED_CELILO_PACKAGES = [
+  '@celilo/cli',
+  '@celilo/capabilities',
+  '@celilo/cli-display',
+  '@celilo/e2e',
+  '@celilo/event-bus',
+] as const;
+
+/**
+ * npm-consumer counterpart to the monorepo staging above (ce-i2i). With no
+ * `modules/` source tree to build from, fetch the sim-content caches from
+ * the public celilo sources so `cele2e build-infra` still produces working
+ * simulator images. Everything is pulled over the public internet, which
+ * build-infra already requires (docker base images, the caddy apt repo, ACME):
+ *
+ *   .npm-registry-cache/   ← published @celilo/* tarballs (npm registry)
+ *   .celilo-website-cache/ ← install.sh from https://celilo.computer (all the
+ *                            bake step's `curl celilo.computer/install.sh` needs)
+ *   .apt-repo-cache/pool/  ← real celilo + celilo-bootstrap .debs fetched from
+ *                            apt.celilo.computer (only bootstrap-apt needs them).
+ *
+ * Sources are overridable via CELILO_E2E_NPM_REGISTRY / CELILO_E2E_WEBSITE_BASE
+ * / CELILO_E2E_APT_BASE (used by the monorepo-free CI smoke test, ce-1pe).
+ */
+async function stageFromPublic(pkgDir: string): Promise<void> {
+  console.log(`${bold}Staging simulator inputs (npm-consumer mode)...${reset}\n`);
+
+  const registry = (process.env.CELILO_E2E_NPM_REGISTRY ?? 'https://registry.npmjs.org').replace(
+    /\/+$/,
+    '',
+  );
+  const websiteBase = (process.env.CELILO_E2E_WEBSITE_BASE ?? 'https://celilo.computer').replace(
+    /\/+$/,
+    '',
+  );
+
+  // (a) npm-registry-cache: the published @celilo/* tarballs.
+  const npmCache = join(pkgDir, '.npm-registry-cache');
+  rmSync(npmCache, { recursive: true, force: true });
+  mkdirSync(npmCache, { recursive: true });
+  process.stdout.write(`  ${'npm-registry (fetch)'.padEnd(28)} `);
+  const t0 = Date.now();
+  for (const pkg of PUBLISHED_CELILO_PACKAGES) {
+    await fetchPublishedTarball(pkg, npmCache, registry);
+  }
+  console.log(
+    `${green}✔${reset}  ${dim}${Math.round((Date.now() - t0) / 1000)}s, ${PUBLISHED_CELILO_PACKAGES.length} tarball(s)${reset}`,
+  );
+
+  // (b) celilo-website-cache: the bake step's `curl celilo.computer/install.sh`
+  // only needs install.sh served, so fetch it (bootstrap.sh best-effort — it's
+  // referenced by install.sh's help text but not needed for the bake path).
+  const websiteCache = join(pkgDir, '.celilo-website-cache');
+  rmSync(websiteCache, { recursive: true, force: true });
+  mkdirSync(websiteCache, { recursive: true });
+  process.stdout.write(`  ${'celilo-website (fetch)'.padEnd(28)} `);
+  const t1 = Date.now();
+  await fetchSiteFile(websiteBase, 'install.sh', websiteCache, { required: true });
+  await fetchSiteFile(websiteBase, 'bootstrap.sh', websiteCache, { required: false });
+  console.log(`${green}✔${reset}  ${dim}${Math.round((Date.now() - t1) / 1000)}s${reset}`);
+
+  // (c) apt-repo-cache/pool: the real celilo + celilo-bootstrap .debs, fetched
+  // from apt.celilo.computer so the bootstrap-apt test's `apt install
+  // celilo-bootstrap` resolves. Only that test exercises this path; if the
+  // fetch fails we leave the pool empty (build-infra still succeeds for
+  // everyone) and bootstrap-apt fails loudly with the sim's "empty repo".
+  const aptBase = (process.env.CELILO_E2E_APT_BASE ?? 'https://apt.celilo.computer').replace(
+    /\/+$/,
+    '',
+  );
+  const pool = join(pkgDir, '.apt-repo-cache', 'pool');
+  rmSync(join(pkgDir, '.apt-repo-cache'), { recursive: true, force: true });
+  mkdirSync(pool, { recursive: true });
+  process.stdout.write(`  ${'apt-repo (fetch)'.padEnd(28)} `);
+  const t2 = Date.now();
+  try {
+    const count = await fetchAptPool(aptBase, pool);
+    console.log(
+      `${green}✔${reset}  ${dim}${Math.round((Date.now() - t2) / 1000)}s, ${count} deb(s)${reset}`,
+    );
+  } catch (err) {
+    console.log(
+      `${yellow}empty${reset}  ${dim}(${err instanceof Error ? err.message : String(err)})${reset}`,
+    );
+  }
+
+  console.log('');
+}
+
+/**
+ * Fetch the celilo + celilo-bootstrap .debs from a real apt repo laid out like
+ * apt.celilo.computer (`deb <base>/ stable main`) into `pool`. Parses the
+ * per-arch Packages index for its `Filename: pool/...` entries and downloads
+ * each referenced .deb (deduped across arches, so the arch-all bootstrap deb is
+ * fetched once). Returns the number of debs staged; throws if none were found.
+ */
+export async function fetchAptPool(base: string, pool: string): Promise<number> {
+  const filenames = new Set<string>();
+  for (const arch of ['amd64', 'arm64']) {
+    const dir = `${base}/dists/stable/main/binary-${arch}`;
+    const packages = await fetchPackagesIndex(dir);
+    for (const line of packages.split('\n')) {
+      const m = line.match(/^Filename:\s*(\S+)/);
+      if (m) filenames.add(m[1]);
+    }
+  }
+  if (filenames.size === 0) {
+    throw new Error(`no debs in ${base} stable/main — repo layout changed?`);
+  }
+  for (const filename of filenames) {
+    const url = `${base}/${filename}`;
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`fetching ${url}: HTTP ${res.status}`);
+    writeFileSync(join(pool, basename(filename)), Buffer.from(await res.arrayBuffer()));
+  }
+  return filenames.size;
+}
+
+/** Fetch a Packages index from an apt binary-<arch> dir, uncompressed or .gz. */
+async function fetchPackagesIndex(dir: string): Promise<string> {
+  const plain = await fetch(`${dir}/Packages`);
+  if (plain.ok) return await plain.text();
+  const gz = await fetch(`${dir}/Packages.gz`);
+  if (!gz.ok) throw new Error(`fetching ${dir}/Packages(.gz): HTTP ${gz.status}`);
+  return gunzipSync(Buffer.from(await gz.arrayBuffer())).toString('utf8');
+}
+
+/**
+ * Download a package's `latest` published tarball from the npm registry into
+ * destDir. Uses the registry's own tarball filename so the npm-registry-sim
+ * (which indexes tarballs by their embedded package.json) serves it verbatim.
+ */
+export async function fetchPublishedTarball(
+  pkg: string,
+  destDir: string,
+  registry: string,
+): Promise<void> {
+  const packumentUrl = `${registry}/${pkg}`;
+  const packumentRes = await fetch(packumentUrl);
+  if (!packumentRes.ok) {
+    throw new Error(
+      `Fetching packument for ${pkg} (${packumentUrl}): HTTP ${packumentRes.status}. ` +
+        `Is ${pkg} published to ${registry}?`,
+    );
+  }
+  const packument = (await packumentRes.json()) as {
+    'dist-tags'?: Record<string, string>;
+    versions?: Record<string, { dist?: { tarball?: string } }>;
+  };
+  const latest = packument['dist-tags']?.latest;
+  const tarballUrl = latest ? packument.versions?.[latest]?.dist?.tarball : undefined;
+  if (!latest || !tarballUrl) {
+    throw new Error(`${pkg}: registry ${registry} has no dist-tags.latest tarball`);
+  }
+  const tgzRes = await fetch(tarballUrl);
+  if (!tgzRes.ok) {
+    throw new Error(`Fetching tarball for ${pkg}@${latest} (${tarballUrl}): HTTP ${tgzRes.status}`);
+  }
+  const filename =
+    tarballUrl.split('/').pop() ?? `${pkg.replace('@', '').replace('/', '-')}-${latest}.tgz`;
+  writeFileSync(join(destDir, filename), Buffer.from(await tgzRes.arrayBuffer()));
+}
+
+/**
+ * Download a single file from the published site into destDir. Throws on a
+ * missing required file; silently skips an absent optional one.
+ */
+export async function fetchSiteFile(
+  base: string,
+  name: string,
+  destDir: string,
+  opts: { required: boolean },
+): Promise<void> {
+  const url = `${base}/${name}`;
+  let res: Response;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    if (opts.required) throw err;
+    return;
+  }
+  if (!res.ok) {
+    if (opts.required) throw new Error(`Fetching ${url}: HTTP ${res.status}`);
+    return;
+  }
+  writeFileSync(join(destDir, name), Buffer.from(await res.arrayBuffer()));
+}
+
 function packageNetapp(moduleDir: string, netappsDir: string): void {
   const absDir = resolve(moduleDir);
   if (!existsSync(absDir)) {
@@ -201,6 +410,58 @@ function packageNetapp(moduleDir: string, netappsDir: string): void {
   console.log(`${green}✔${reset}  ${dim}${elapsed}s  ${size}${reset}`);
 }
 
+/**
+ * Consumer (npm-installed) staging: fetch standard-module .netapps from the
+ * public celilo registry into `netappsDir`. In the monorepo we package these
+ * from source (packageNetapp); an npm consumer has no `modules/` source, so
+ * getRegistryVolumes() binds `./netapps` into the sim registry and we fill it
+ * here at build-infra time (which has network — the test RUN stays hermetic
+ * against the local sim). No version-pinning: the capability system governs
+ * compatibility at import time (validateCapabilityAccess), surfacing a
+ * mismatch as an actionable import error rather than a brittle lockfile.
+ */
+export async function stageNetappsFromRegistry(netappsDir: string): Promise<void> {
+  const base = (process.env.CELILO_REGISTRY_URL ?? 'https://celilo.computer/registry').replace(
+    /\/+$/,
+    '',
+  );
+  console.log(`${bold}Fetching standard-module netapps from registry...${reset}`);
+  console.log(`  ${dim}${base}${reset}\n`);
+
+  // ponytail: single page (per_page=100). Paginate if >100 modules ever ship.
+  const listUrl = `${base}/api/v1/modules?per_page=100`;
+  const listResp = await fetch(listUrl, { signal: AbortSignal.timeout(30_000) });
+  if (!listResp.ok) {
+    console.error(`${red}Registry list failed: HTTP ${listResp.status} ${listUrl}${reset}`);
+    process.exit(1);
+  }
+  const { modules } = (await listResp.json()) as {
+    modules: Array<{ name: string; max_version: string }>;
+  };
+  if (!modules || modules.length === 0) {
+    console.error(`${red}Registry returned no modules — nothing to stage${reset}`);
+    process.exit(1);
+  }
+
+  for (const { name, max_version } of modules) {
+    process.stdout.write(`  ${name.padEnd(20)} `);
+    const t0 = Date.now();
+    const dlUrl = `${base}/api/v1/modules/${encodeURIComponent(name)}/${encodeURIComponent(max_version)}/download`;
+    const resp = await fetch(dlUrl, { signal: AbortSignal.timeout(60_000) });
+    if (!resp.ok) {
+      console.log(`${red}✗${reset}`);
+      console.error(`${red}  download failed: HTTP ${resp.status} ${dlUrl}${reset}`);
+      process.exit(1);
+    }
+    const bytes = new Uint8Array(await resp.arrayBuffer());
+    writeFileSync(join(netappsDir, `${name}.netapp`), bytes);
+    console.log(
+      `${green}✔${reset}  ${dim}${max_version}  ${Math.round((Date.now() - t0) / 1000)}s  ${(bytes.length / 1024).toFixed(0)}KB${reset}`,
+    );
+  }
+  console.log('');
+}
+
 function buildDockerImages(pkgDir: string): void {
   // Refresh the bundled registry-server source before docker build —
   // Dockerfile.registry copies from <pkgDir>/registry-server, which is
@@ -295,7 +556,7 @@ function tagVanillaManagement(): void {
  * build-infra so the operator can't accidentally proceed with a
  * non-functional default management image.
  */
-function bakeManagement(pkgDir: string): void {
+function bakeManagement(pkgDir: string, published: boolean): void {
   const bakeScript = join(pkgDir, 'bin', 'e2e-bake-management');
   if (!existsSync(bakeScript)) {
     console.error(
@@ -305,9 +566,14 @@ function bakeManagement(pkgDir: string): void {
     process.exit(1);
   }
 
-  console.log(`${bold}Baking celilo into management:latest via install.sh...${reset}\n`);
+  console.log(
+    published
+      ? `${bold}Baking PUBLISHED @celilo/cli into management:latest from real npm...${reset}\n`
+      : `${bold}Baking celilo into management:latest via install.sh...${reset}\n`,
+  );
   const start = Date.now();
-  const result = spawnSync('bun', ['run', bakeScript], { stdio: 'inherit' });
+  const bakeArgs = ['run', bakeScript, ...(published ? ['--published'] : [])];
+  const result = spawnSync('bun', bakeArgs, { stdio: 'inherit' });
   const elapsed = Math.round((Date.now() - start) / 1000);
 
   if (result.status !== 0) {
@@ -381,8 +647,8 @@ function saveImages(pkgDir: string): void {
   console.log('\nTo restore after colima restart:\n  cele2e load');
 }
 
-export function runBuild(options: BuildOptions): void {
-  const { pkgDir, moduleDirs, save, skipModules } = options;
+export async function runBuild(options: BuildOptions): Promise<void> {
+  const { pkgDir, moduleDirs, save, skipModules, published } = options;
   const netappsDir = join(pkgDir, 'netapps');
   mkdirSync(netappsDir, { recursive: true });
 
@@ -390,7 +656,7 @@ export function runBuild(options: BuildOptions): void {
   // and npm-registry-sim COPY from the staged dirs at docker-build time,
   // so they have to exist (and reflect current workspace state) before
   // buildDockerImages() runs.
-  stageSimulatorInputs(pkgDir);
+  await stageSimulatorInputs(pkgDir);
 
   if (!skipModules) {
     // Explicit dirs take precedence; fall back to auto-discovering all
@@ -412,6 +678,12 @@ export function runBuild(options: BuildOptions): void {
         packageNetapp(dir, netappsDir);
       }
       console.log('');
+    } else {
+      // npm consumer: no `modules/` source to package from — fetch the
+      // standard-module netapps from the registry so the sim registry
+      // (which binds ./netapps) has something to serve. Consumers need
+      // zero vendored module binaries.
+      await stageNetappsFromRegistry(netappsDir);
     }
   }
 
@@ -429,7 +701,7 @@ export function runBuild(options: BuildOptions): void {
   // simulated celilo.computer / npm registry. This is what makes the
   // default management image every test uses an actual product of
   // install.sh, rather than a parallel `bun add -g` pinning.
-  bakeManagement(pkgDir);
+  bakeManagement(pkgDir, published);
 
   // Pre-seed heavy app images so app-zone deploys load them from the cache
   // instead of pulling GB through the sim (ISS-0154).

package/src/cli/command-registry.ts

@@ -33,6 +33,9 @@ export const COMMANDS: CommandDef[] = [
       { name: '--reuse', description: 'Reuse existing network if running' },
       { name: '--live', description: 'Use live (non-simulated) internet' },
       { name: '--published', description: 'Use published .netapp packages' },
+      { name: '--notify', description: 'Desktop notification when the run finishes' },
+      { name: '--shuffle', description: 'Randomize test order to surface order-dependent bugs (seed is logged)' },
+      { name: '--seed=', description: 'Replay a specific --shuffle order (e.g. --seed=12345)' },
     ],
   },
   {
@@ -75,7 +78,12 @@ export const COMMANDS: CommandDef[] = [
   },
   {
     name: 'status',
-    description: 'Show network status and DNS health',
+    description: 'Show run-lock holder + network status (exit 3 if busy)',
+    flags: [{ name: '--json', description: 'Emit a machine-readable lock snapshot for polling' }],
+  },
+  {
+    name: 'release',
+    description: 'Free a run-lock left by --keep/up (does not tear down)',
   },
   {
     name: 'load',
@@ -101,8 +109,8 @@ export const COMMANDS: CommandDef[] = [
 
 export const UP_PRESETS = ['--caddy', '--full-stack', '--infrastructure'];
 
-export const RUN_FLAGS = ['--all', '--complete', '--ci-safe', '--all-modules', '--keep', '--reuse', '--live', '--published'];
+export const RUN_FLAGS = ['--all', '--complete', '--ci-safe', '--all-modules', '--keep', '--reuse', '--live', '--published', '--notify'];
 
 export const DOWN_FLAGS = ['--keep', '--all'];
 
-export const BUILD_INFRA_FLAGS = ['--save'];
+export const BUILD_INFRA_FLAGS = ['--save', '--skip-modules', '--published'];

package/src/cli/completion.ts

@@ -119,6 +119,7 @@ _cele2e() {
             '--reuse[Reuse existing network if running]' \\
             '--live[Use live (non-simulated) internet]' \\
             '--published[Use published .netapp packages]' \\
+            '--notify[Desktop notification when the run finishes]' \\
             '--ci[Plain log output: one line per step, no spinner]' \\
             '--no-ci[Force spinner even when a CI env var is set]' \\
             '*::test name or module path:_cele2e_run_args'
@@ -137,6 +138,8 @@ _cele2e() {
         build-infra)
           _arguments \\
             '--save[Save Docker images to tarball after build]' \\
+            '--skip-modules[Skip .netapp packaging (only rebuild Docker images)]' \\
+            '--published[Bake management:latest with the published @celilo/cli from real npm]' \\
             '*:module directory:_directories'
           ;;
         shell)
@@ -148,7 +151,10 @@ _cele2e() {
         completion)
           _arguments '1: :_cele2e_completion_shells'
           ;;
-        status|load|clear-timing|list)
+        status)
+          _arguments '--json[Emit a machine-readable lock snapshot for polling]'
+          ;;
+        release|load|clear-timing)
           ;;
       esac
       ;;
@@ -164,7 +170,8 @@ _cele2e_commands() {
     'build-infra:Rebuild @celilo/e2e Docker images and standard module .netapps'
     'clear-timing:Clear saved timing history for test ETAs'
     'shell:Shell into a running container (default: management)'
-    'status:Show network status and DNS health'
+    'status:Show run-lock holder + network status (exit 3 if busy)'
+    'release:Free a run-lock left by --keep/up (does not tear down)'
     'load:Load cached Docker images from tarball'
     'scaffold:Generate a new test file from template'
     'version:Show cele2e version'

package/src/cli/index.ts

@@ -23,6 +23,7 @@ import { runBuild } from './build';
 import { runScaffold } from './scaffold';
 import { generateBashCompletion, generateZshCompletion, getCompletions } from './completion';
 import { findAllModules, findModulesWithMatchingTest } from './module-discovery';
+import { acquireRunLock, clearLock, E2eBusyError, formatBusy, lockStatus, markKept } from '../run-lock';
 
 const PKG_DIR = resolve(import.meta.dir, '../..');
 const BIN_DIR = join(PKG_DIR, 'bin');
@@ -127,7 +128,8 @@ Commands:
   clear-timing      Clear saved timing history used for test ETAs
   version           Show cele2e version
   shell [container] Shell into a running container (default: management)
-  status            Show network status and DNS health
+  status            Show run-lock holder + network status (exit 3 if busy)
+  release           Free a run-lock left by --keep/up (does not tear down)
   load              Load cached Docker images from tarball
   scaffold <name>   Generate a new test file from template
   completion <shell> Generate shell completion script (zsh|bash)
@@ -139,6 +141,7 @@ Options for \`run\`:
   --reuse           Reuse existing network if running
   --live            Use live (non-simulated) internet
   --published       Use published .netapp packages
+  --notify          Desktop notification when the run finishes (best-effort)
   --ci              Plain log output: one ✔/✗ line per step, no spinner
                     (auto-on when a CI env var is set; --no-ci forces off)
 
@@ -154,6 +157,8 @@ Options for \`down\`:
 Options for \`build-infra\`:
   --save            Save Docker images to tarball after build
   --skip-modules    Skip .netapp packaging (only rebuild Docker images)
+  --published       Bake management:latest with the PUBLISHED @celilo/cli from
+                    real npm (default: bake the monorepo DEV cli via the sim)
 
 Examples:
   cele2e run --all                  # FULL regression: every module suite + top-level e2e/tests/
@@ -297,16 +302,55 @@ switch (command) {
     process.exit(0);
   }
 
-  case 'up':
+  case 'up': {
+    // `up` leaves an interactive network running, so it holds the run-lock in a
+    // kept state (cleared by `cele2e down`/`release`) to stop a concurrent run
+    // from wiping it.
+    try {
+      acquireRunLock({ test: 'up', runId: process.env.CELE2E_RUN_ID ?? crypto.randomUUID() });
+      markKept();
+    } catch (err) {
+      if (err instanceof E2eBusyError) {
+        console.error(err.message);
+        process.exit(3);
+      }
+      throw err;
+    }
     runScript('e2e-up', args);
+  }
 
   case 'down':
+    // Tearing the network down frees the (possibly kept) lock.
+    clearLock();
     runScript('e2e-down', args, { E2E_TEST_DIR: stateDir });
 
   case 'shell':
     runScript('e2e-shell', args);
 
+  case 'release': {
+    // Free a lock left by `--keep`/`up` (a `kept` stack) so the next run can
+    // proceed. Does not tear the stack down — use `cele2e down` for that.
+    const had = clearLock();
+    console.log(had ? 'Released the e2e run-lock.' : 'No e2e run-lock held.');
+    process.exit(0);
+  }
+
   case 'status': {
+    // Run-lock is the contention surface other sessions poll. Report it first;
+    // exit 0 = free, 3 = busy. `--json` emits a machine-readable snapshot.
+    const lock = lockStatus();
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(lock));
+      process.exit(lock.free ? 0 : 3);
+    }
+    console.log('=== Run Lock ===');
+    if (lock.free) {
+      console.log('  free');
+    } else if (lock.holder) {
+      console.log(`  BUSY — ${formatBusy(lock.holder)}`);
+    }
+    console.log('');
+
     const persistentFile = join(stateDir, '.e2e-persistent.json');
     let projectName: string | undefined;
     if (existsSync(persistentFile)) {
@@ -331,8 +375,20 @@ switch (command) {
   case 'build-infra': {
     const save = args.includes('--save');
     const skipModules = args.includes('--skip-modules');
+    const published = args.includes('--published');
     const moduleDirs = args.filter((a) => !a.startsWith('--'));
-    runBuild({ pkgDir: PKG_DIR, moduleDirs, save, skipModules });
+    // build-infra mutates the shared Docker images — serialize against runs.
+    // Released via the lock's exit handler (runBuild may process.exit on failure).
+    try {
+      acquireRunLock({ test: 'build-infra', runId: process.env.CELE2E_RUN_ID ?? crypto.randomUUID() });
+    } catch (err) {
+      if (err instanceof E2eBusyError) {
+        console.error(err.message);
+        process.exit(3);
+      }
+      throw err;
+    }
+    await runBuild({ pkgDir: PKG_DIR, moduleDirs, save, skipModules, published });
     break;
   }
 

package/src/cli-version-contract.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from 'bun:test';
+import { checkCliVersion } from './cli-version-contract';
+
+// ce-5qp: harness<->CLI version contract fails fast on a stale management image.
+
+test('accepts a CLI at or above the minimum', () => {
+  expect(checkCliVersion('celilo 0.9.1', '0.9.0')).toBeNull();
+  expect(checkCliVersion('celilo 0.9.0', '0.9.0')).toBeNull();
+  expect(checkCliVersion('celilo 1.2.3', '0.9.0')).toBeNull();
+});
+
+test('rejects a stale CLI with an actionable message', () => {
+  const msg = checkCliVersion('celilo 0.5.0-alpha.5', '0.9.0');
+  expect(msg).toContain('celilo 0.5.0-alpha.5');
+  expect(msg).toContain('>=0.9.0');
+  expect(msg).toContain('build-infra');
+});
+
+test('reports unparseable version output instead of silently passing', () => {
+  expect(checkCliVersion('command not found', '0.9.0')).toContain('Could not parse');
+  expect(checkCliVersion('', '0.9.0')).toContain('Could not parse');
+});

package/src/cli-version-contract.ts

@@ -0,0 +1,37 @@
+/**
+ * Harness<->CLI version contract (ce-5qp). The management image ships a
+ * baked-in `celilo` CLI; a published harness run against a stale image
+ * (e.g. an old npm consumer's `cele2e build-infra`) used to hang ~90s in
+ * `system init` and surface only "canceled". Instead we check the baked CLI
+ * version up front and fail fast (<10s) with an actionable message.
+ *
+ * Bump MIN_CLI_VERSION whenever the harness starts relying on a CLI
+ * feature/flag that older CLIs lack. It's the MINIMUM the harness needs,
+ * not an exact pin.
+ */
+export const MIN_CLI_VERSION = '0.9.0';
+
+/**
+ * Pure core of the contract: given the raw `celilo --version` stdout, decide
+ * whether it satisfies `minVersion`. Returns an actionable error string when
+ * it doesn't, or `null` when OK. No I/O, so it's unit-testable without a
+ * running management container.
+ */
+export function checkCliVersion(versionStdout: string, minVersion = MIN_CLI_VERSION): string | null {
+  // Output is `celilo <version>` (apps/celilo displayVersion). Grab the token.
+  const version = versionStdout.match(/celilo\s+(\S+)/)?.[1];
+  if (!version) {
+    return (
+      `Could not parse celilo version from "${versionStdout.trim()}" ` +
+      `(harness requires >=${minVersion}). Is the management image's celilo CLI intact?`
+    );
+  }
+  if (Bun.semver.order(version, minVersion) < 0) {
+    return (
+      `Management image has celilo ${version}, harness requires >=${minVersion}. ` +
+      `Rebuild the management image against a newer @celilo/cli ` +
+      `(e.g. \`cele2e build-infra\`, or \`--published\` after publishing).`
+    );
+  }
+  return null;
+}