@celilo/e2e 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/e2e",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "E2E test infrastructure for Celilo-deployed applications. Provides a simulated internet with DNS hierarchy, ACME server, firewalls, and target machines in Docker.",
   "type": "module",
   "main": "./src/index.ts",
@@ -18,7 +18,7 @@
     "celilo-e2e-infra": "./bin/e2e-infra"
   },
   "scripts": {
-    "test": "bun test --timeout 30000 tests/",
+    "test": "bun test --timeout 30000 ./tests/ ./src/ ./npm-registry-server/ ./simulators/",
     "test:completion": "bun test tests/completion",
     "test:integration": "bun test tests-integration/"
   },
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@celilo/capabilities": "^3.1.0",
+    "@celilo/capabilities": "^3.3.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/event-bus": "^0.6.0",
     "@celilo/terraform-fake": "^0.3.1",

package/registry-server/src/bootstrap.ts

@@ -33,6 +33,8 @@ export interface BootstrapEntry {
    * apps/celilo/designs/REGISTRY_BROWSE_UI.md (Phase 2 step 0).
    */
   description?: string;
+  /** Manifest's `icon` field, when present. Served like `description`. */
+  icon?: string;
 }
 
 /**
@@ -60,11 +62,14 @@ export function scanBootstrapDir(bootstrapDir: string): Map<string, BootstrapEnt
       const name = idMatch?.[1]?.trim() ?? entry.name;
       const version = versionMatch?.[1]?.trim() ?? '0.0.0';
       const description = descriptionMatch?.[1]?.trim().replace(/^['"]|['"]$/g, '');
+      const iconMatch = yaml.match(/^icon:\s*(.+?)\s*$/m);
+      const icon = iconMatch?.[1]?.trim().replace(/^['"]|['"]$/g, '');
       entries.set(name, {
         name,
         version,
         sourceDir: join(bootstrapDir, entry.name),
         description,
+        icon,
       });
     } catch {
       // skip malformed manifests — matches e2e server behavior

package/registry-server/src/server.test.ts

@@ -217,6 +217,64 @@ describe('GET /api/v1/modules (search)', () => {
     expect(found?.description).toBe('');
   });
 
+  test('icon survives publish, the sparse index and a search read', async () => {
+    // openspec/changes/module-icons D4 — the icon rides the same path
+    // `description` does: publish metadata → index entry → browse endpoints.
+    expect((await publish('homebridge', '1.0.0+1', 'valid-token', 'Bridge', '\u22c8')).status).toBe(
+      200,
+    );
+
+    const index = await fetch(`${baseUrl}/index/ho/me/homebridge`);
+    expect(index.status).toBe(200);
+    const line = JSON.parse((await index.text()).trim()) as { icon?: string };
+    expect(line.icon).toBe('\u22c8');
+
+    const res = await fetch(`${baseUrl}/api/v1/modules`);
+    const body = (await res.json()) as { modules: Array<{ name: string; icon?: string }> };
+    expect(body.modules.find((m) => m.name === 'homebridge')?.icon).toBe('\u22c8');
+
+    const detail = await fetch(`${baseUrl}/api/v1/modules/homebridge`);
+    expect(((await detail.json()) as { icon?: string }).icon).toBe('\u22c8');
+  });
+
+  test('an entry published without an icon reads back as undefined, not a throw', async () => {
+    // The old-entry case D4 depends on: index lines written before the field
+    // existed carry no `icon`, and a consumer falls back rather than failing.
+    //
+    // This test passes with or without the icon feature, so it is NOT a gate on
+    // it — verified by running it against the pre-#1147 tree. It is here to
+    // catch a future change that makes a missing `icon` throw or coerce to '',
+    // which is what D4's fallback chain would break on. Do not count it as
+    // coverage of the capture path; that is the test above.
+    expect((await publish('homebridge', '1.0.0+1', 'valid-token')).status).toBe(200);
+
+    const res = await fetch(`${baseUrl}/api/v1/modules`);
+    const body = (await res.json()) as { modules: Array<{ name: string; icon?: string }> };
+    const found = body.modules.find((m) => m.name === 'homebridge');
+    expect(found).toBeTruthy();
+    expect(found?.icon).toBeUndefined();
+  });
+
+  test('a multi-character icon is dropped while a valid one beside it is kept', async () => {
+    // Publish metadata is arbitrary client JSON. The CLI refines the value at
+    // manifest-parse time; the server keeps the index from carrying a string
+    // that would blow out a fixed-width slot on the browse page.
+    //
+    // Both halves are asserted deliberately. Checking only that the bad value
+    // is absent would pass just as well if the capture path were deleted
+    // outright — the guard and the capture would cancel out and the test would
+    // stay green having lost the feature. The kept glyph is what stops that.
+    expect(
+      (await publish('homebridge', '1.0.0+1', 'valid-token', 'Bridge', 'not-a-glyph')).status,
+    ).toBe(200);
+    expect((await publish('caddy', '1.0.0+1', 'valid-token', 'Proxy', '\u25cd')).status).toBe(200);
+
+    const res = await fetch(`${baseUrl}/api/v1/modules`);
+    const body = (await res.json()) as { modules: Array<{ name: string; icon?: string }> };
+    expect(body.modules.find((m) => m.name === 'homebridge')?.icon).toBeUndefined();
+    expect(body.modules.find((m) => m.name === 'caddy')?.icon).toBe('\u25cd');
+  });
+
   test('total_downloads reflects actual download count, sort=downloads orders by it', async () => {
     // Publish two modules, hit one's download endpoint several times.
     // The search response should show those counts and sort=downloads
@@ -490,9 +548,15 @@ async function publish(
   vers: string,
   token: string,
   description?: string,
+  icon?: string,
 ): Promise<Response> {
   const meta = Buffer.from(
-    JSON.stringify({ name, vers, ...(description ? { description } : {}) }),
+    JSON.stringify({
+      name,
+      vers,
+      ...(description ? { description } : {}),
+      ...(icon ? { icon } : {}),
+    }),
     'utf-8',
   );
   const file = Buffer.from('fake netapp bytes');
@@ -769,3 +833,121 @@ describe('module-owner authorization (ce-1ch)', () => {
     expect(res.status).toBe(200);
   });
 });
+
+// ── sweep (reclaiming disk from superseded build revisions) ──────────────────
+
+describe('POST /api/v1/modules/sweep', () => {
+  function requestSweep(token: string, body: unknown = {}): Promise<Response> {
+    return fetch(`${baseUrl}/api/v1/modules/sweep`, {
+      method: 'POST',
+      headers: token ? { Authorization: token, 'Content-Type': 'application/json' } : {},
+      body: JSON.stringify(body),
+    });
+  }
+
+  test('no token is 401 — a sweep deletes, so it is admin-only', async () => {
+    const res = await requestSweep('');
+    expect(res.status).toBe(401);
+  });
+
+  test('a scoped (non-admin) token is 401', async () => {
+    const mint = await fetch(`${baseUrl}/api/v1/modules/tokens/mint`, {
+      method: 'POST',
+      headers: { Authorization: 'valid-token', 'Content-Type': 'application/json' },
+      body: JSON.stringify({ repo: 'celilo/homebridge', scope: 'homebridge' }),
+    });
+    const { token } = (await mint.json()) as { token: string };
+
+    const res = await requestSweep(token);
+    expect(res.status).toBe(401);
+  });
+
+  test('removes superseded revisions and leaves the download path working', async () => {
+    for (const rev of [1, 2, 3]) await publish('homebridge', `1.0.0+${rev}`, 'valid-token');
+
+    const res = await requestSweep('valid-token');
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ok: boolean; removedCount: number };
+    expect(body.ok).toBe(true);
+    expect(body.removedCount).toBe(2);
+
+    // The surviving revision downloads; a swept one is gone from BOTH the
+    // index and the store, so nothing advertises a 404.
+    expect((await fetch(`${baseUrl}/api/v1/modules/homebridge/1.0.0+3/download`)).status).toBe(200);
+    expect((await fetch(`${baseUrl}/api/v1/modules/homebridge/1.0.0+1/download`)).status).toBe(404);
+
+    const index = await fetch(`${baseUrl}/index/ho/me/homebridge`);
+    const versions = (await index.text())
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => (JSON.parse(line) as { vers: string }).vers);
+    expect(versions).toEqual(['1.0.0+3']);
+  });
+
+  test('dry_run reports the plan without deleting anything', async () => {
+    for (const rev of [1, 2]) await publish('homebridge', `1.0.0+${rev}`, 'valid-token');
+
+    const res = await requestSweep('valid-token', { dry_run: true });
+    const body = (await res.json()) as { removedCount: number; dryRun: boolean };
+    expect(body.removedCount).toBe(1);
+    expect(body.dryRun).toBe(true);
+    expect((await fetch(`${baseUrl}/api/v1/modules/homebridge/1.0.0+1/download`)).status).toBe(200);
+  });
+
+  test('rejects a keep_build_revisions that would delete a whole release', async () => {
+    const res = await requestSweep('valid-token', { keep_build_revisions: 0 });
+    expect(res.status).toBe(400);
+  });
+
+  test('honours a larger keep_build_revisions', async () => {
+    for (const rev of [1, 2, 3, 4]) await publish('homebridge', `1.0.0+${rev}`, 'valid-token');
+    const res = await requestSweep('valid-token', { keep_build_revisions: 2 });
+    const body = (await res.json()) as { removedCount: number };
+    expect(body.removedCount).toBe(2);
+  });
+
+  test('coexists with a module actually named "sweep"', async () => {
+    await publish('sweep', '1.0.0+1', 'valid-token');
+    const res = await requestSweep('valid-token');
+    expect(res.status).toBe(200);
+    // …and the module is still reachable by its own GET route.
+    expect((await fetch(`${baseUrl}/api/v1/modules/sweep`)).status).toBe(200);
+  });
+});
+
+describe('POST /api/v1/modules/sweep — a damaged store', () => {
+  function requestSweep(token: string, body: unknown = {}): Promise<Response> {
+    return fetch(`${baseUrl}/api/v1/modules/sweep`, {
+      method: 'POST',
+      headers: { Authorization: token, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  }
+
+  test('reclaims a half-written publish, freeing the version to be published again', async () => {
+    // handlePublish stores the package and appends the index with no rollback
+    // between them, so an ENOSPC or EACCES in the gap leaves an orphan. The
+    // immutability check reads the filesystem, so that version then cannot be
+    // published at all — this is the only repair path in the product.
+    await publish('homebridge', '1.0.0+1', 'valid-token');
+    const rmIndex = await fetch(`${baseUrl}/api/v1/modules/homebridge/1.0.0+1/yank`, {
+      method: 'DELETE',
+      headers: { Authorization: 'valid-token' },
+    });
+    expect(rmIndex.status).toBe(200);
+
+    // Simulate the crash: index line gone, payload left behind.
+    rmSync(join(dataDir, 'index'), { recursive: true, force: true });
+
+    const blocked = await publish('homebridge', '1.0.0+1', 'valid-token');
+    expect(blocked.status).toBe(409);
+
+    const swept = await requestSweep('valid-token');
+    const body = (await swept.json()) as { orphanCount: number };
+    expect(body.orphanCount).toBe(1);
+
+    // The version is publishable again.
+    const retry = await publish('homebridge', '1.0.0+1', 'valid-token');
+    expect(retry.status).toBe(200);
+  });
+});

package/registry-server/src/server.ts

@@ -10,6 +10,7 @@
  *   PUT  /api/v1/modules/new                             → publish (token auth)
  *   DELETE /api/v1/modules/{name}/{ver}/yank             → yank
  *   PUT  /api/v1/modules/{name}/{ver}/unyank             → unyank
+ *   POST /api/v1/modules/sweep                           → reclaim old revisions (admin)
  *
  * All routes can be prefixed with PATH_PREFIX (e.g. "/registry").
  *
@@ -34,6 +35,7 @@ import { ModuleOwnerStore, fileModuleOwnerPersistence } from './module-owner-sto
 import { type RateLimiter, clientIp, createRateLimiter } from './rate-limit';
 import { ScopedTokenStore, fileScopedTokenPersistence } from './scoped-token-store';
 import { type IndexEntry, RegistryStorage } from './storage';
+import { DEFAULT_KEEP_BUILD_REVISIONS, sweep } from './sweep';
 import { isValidName, isValidVersion, validateNameAndVersion } from './validation';
 
 /** Max total publish body size. Real modules are a few MB; 100MB is generous. */
@@ -313,6 +315,12 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
     // not provided we leave it undefined; the search endpoint falls
     // back to bootstrap data or empty.
     const description = typeof meta.description === 'string' ? meta.description : undefined;
+    // Icon likewise, but capped at one Unicode scalar. The CLI already refines
+    // it at manifest-parse time; this second check is here because the publish
+    // metadata is arbitrary client JSON and the value lands in a fixed-width
+    // slot on the browse page.
+    const icon =
+      typeof meta.icon === 'string' && [...meta.icon].length === 1 ? meta.icon : undefined;
 
     const validation = validateNameAndVersion(name, vers);
     if (!validation.ok) return err(validation.message);
@@ -339,12 +347,63 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
       cksum: `sha256:${cksum}`,
       yanked: false,
       description,
+      icon,
     });
 
     console.log(`[registry] published ${name}@${vers} (${fileLen} bytes, sha256:${cksum})`);
     return Response.json({ ok: true, name, vers });
   }
 
+  /**
+   * Reclaim disk from superseded build revisions (admin-only).
+   *
+   * The counterpart yank never was: yanking flips a boolean and frees nothing,
+   * so before this endpoint existed every revision ever published was retained
+   * forever and the store grew without bound until the disk filled.
+   *
+   * Runs IN the process that owns the store, so it cannot race a concurrent
+   * publish's index append. `dry_run` reports the same plan without touching
+   * anything — the safe way to see what a policy would do on a live store.
+   */
+  async function handleSweep(req: Request): Promise<Response> {
+    if (!(await authorizeAdminReq(req))) return unauthorized();
+
+    let body: { keep_build_revisions?: unknown; dry_run?: unknown } = {};
+    try {
+      const text = await req.text();
+      if (text.trim()) body = JSON.parse(text) as typeof body;
+    } catch {
+      return err('Invalid JSON body');
+    }
+
+    const requested = body.keep_build_revisions;
+    if (requested !== undefined && (!Number.isInteger(requested) || (requested as number) < 1)) {
+      return err('keep_build_revisions must be an integer >= 1');
+    }
+    const keepBuildRevisions = (requested as number | undefined) ?? DEFAULT_KEEP_BUILD_REVISIONS;
+    const dryRun = body.dry_run === true;
+
+    const report = sweep(storage, { keepBuildRevisions }, dryRun);
+    console.log(
+      `[registry] sweep${dryRun ? ' (dry run)' : ''} keep=${keepBuildRevisions}: ` +
+        `${report.removedCount} superseded + ${report.orphanCount} orphaned revision(s), ` +
+        `${Math.round(report.reclaimedBytes / 1024 / 1024)} MB`,
+    );
+    // Both of these mean the store is damaged, not merely untidy, and the sweep
+    // deliberately did not act on either. Say so where an operator will see it.
+    if (report.danglingCount > 0) {
+      console.warn(
+        `[registry] ${report.danglingCount} index line(s) have no package file — left in place; download 404s until republished`,
+      );
+    }
+    if (report.unreadable.length > 0) {
+      console.warn(
+        `[registry] skipped entirely (no package files at all — check the mount and DATA_DIR): ${report.unreadable.join(', ')}`,
+      );
+    }
+    return Response.json({ ok: true, ...report });
+  }
+
   function setYanked(name: string, version: string, yanked: boolean): Response {
     const entries = storage.readIndex(name);
     const entry = entries.find((e) => e.vers === version);
@@ -505,10 +564,15 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
           //      description capture and haven't been republished).
           const bootstrapEntry = bootstrap.get(name);
           const description = latest?.description ?? bootstrapEntry?.description ?? '';
+          // Icon follows the same order, but has no empty-string tier: absent
+          // means "this module declared none", and the consumer resolves it
+          // from its own table or a placeholder (module-icons D5).
+          const icon = latest?.icon ?? bootstrapEntry?.icon;
           return {
             name,
             max_version: latest?.vers ?? '0.0.0',
             description,
+            icon,
             total_downloads: storage.getDownloads(name),
           };
         });
@@ -551,6 +615,15 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
         return handleRevokeToken(req);
       }
 
+      // Reclaim disk from superseded build revisions (admin-only), grouped
+      // with the other admin endpoints. A module NAMED "sweep" is fine here:
+      // its metadata route is a GET, so the two never compete.
+      if (method === 'POST' && suffix === `${apiBase}/sweep`) {
+        const rl = rateLimitOrNull(req, srv);
+        if (rl) return rl;
+        return handleSweep(req);
+      }
+
       // Module-owner table management (admin-only — ce-1ch). Matched before the
       // generic `${apiBase}/{name}` handlers so a name of "owners" can't shadow
       // them.
@@ -588,9 +661,11 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
           const latest = entries.filter((v) => !v.yanked).at(-1) ?? entries.at(-1);
           const bootstrapEntry = resolveBootstrap().get(name);
           const description = latest?.description ?? bootstrapEntry?.description ?? '';
+          const icon = latest?.icon ?? bootstrapEntry?.icon;
           return Response.json({
             name,
             description,
+            icon,
             total_downloads: storage.getDownloads(name),
             versions: entries.map((v) => ({
               num: v.vers,

package/registry-server/src/storage.ts

@@ -8,7 +8,16 @@
  */
 
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { dirname, join } from 'node:path';
 
 export interface IndexEntry {
@@ -25,6 +34,14 @@ export interface IndexEntry {
    * step 0). Old index files without this field still parse cleanly.
    */
   description?: string;
+  /**
+   * One monochrome glyph from the module's `manifest.yml#icon`, captured at
+   * publish time. Optional for the same reason `description` is: entries
+   * written before the field existed have none, and a consumer reading one
+   * without it falls back to its own table rather than failing
+   * (openspec/changes/module-icons, D4).
+   */
+  icon?: string;
 }
 
 export interface ModuleVersion {
@@ -79,10 +96,28 @@ export class RegistryStorage {
     writeFileSync(path, `${JSON.stringify(entry)}\n`, { flag: 'a' });
   }
 
+  /**
+   * Replace a module's whole index file.
+   *
+   * Writes a sibling temp file and renames it over the original, which is
+   * atomic within a directory. A plain truncating write has two failure modes
+   * this avoids, and the sweep meets both: a crash mid-write leaves a half-
+   * index, and an ENOSPC leaves an EMPTY one — losing every version of the
+   * module. The sweep exists precisely because the disk filled up, so "the
+   * write fails for want of space" is its expected environment, not a corner.
+   * On failure the original file is untouched.
+   */
   updateIndex(name: string, entries: IndexEntry[]): void {
     const path = this.indexPath(name);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${entries.map((e) => JSON.stringify(e)).join('\n')}\n`);
+    const tmp = `${path}.tmp`;
+    try {
+      writeFileSync(tmp, `${entries.map((e) => JSON.stringify(e)).join('\n')}\n`);
+      renameSync(tmp, path);
+    } catch (err) {
+      rmSync(tmp, { force: true, recursive: true });
+      throw err;
+    }
   }
 
   storePackage(name: string, version: string, data: Buffer): string {
@@ -96,6 +131,45 @@ export class RegistryStorage {
     return existsSync(this.packagePath(name, version));
   }
 
+  /** Bytes on disk for one version's .netapp, or 0 when it is already gone. */
+  packageSize(name: string, version: string): number {
+    const path = this.packagePath(name, version);
+    if (!existsSync(path)) return 0;
+    return statSync(path).size;
+  }
+
+  /**
+   * Delete one version's payload directory (`modules/{name}/{version}/`).
+   * Idempotent: removing a version that is already gone is a no-op, so an
+   * interrupted sweep is safe to re-run.
+   */
+  removePackage(name: string, version: string): void {
+    rmSync(dirname(this.packagePath(name, version)), { recursive: true, force: true });
+  }
+
+  /**
+   * Every version with a payload directory on disk, whether or not the index
+   * still lists it. The sweep needs the on-DISK set, not the indexed one:
+   * removing an index line is what makes a version unreachable, and the file
+   * it leaves behind is exactly what has to be reclaimed afterwards.
+   */
+  storedVersions(name: string): string[] {
+    const dir = join(this.dataDir, 'modules', name);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  }
+
+  /** Module names with a payload directory, including any absent from the index. */
+  storedNames(): string[] {
+    const dir = join(this.dataDir, 'modules');
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  }
+
   readPackage(name: string, version: string): Buffer | null {
     const path = this.packagePath(name, version);
     return existsSync(path) ? readFileSync(path) : null;

package/registry-server/src/sweep.test.ts

@@ -0,0 +1,326 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RegistryStorage } from './storage';
+import { DEFAULT_KEEP_BUILD_REVISIONS, parseRevision, planModuleSweep, sweep } from './sweep';
+
+let dataDir: string;
+let storage: RegistryStorage;
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), 'celilo-registry-sweep-'));
+  storage = new RegistryStorage(dataDir);
+});
+
+afterEach(() => {
+  rmSync(dataDir, { recursive: true, force: true });
+});
+
+/** Publish a version through the same two calls the real publish path uses. */
+function publish(name: string, vers: string, sizeBytes = 32): void {
+  storage.storePackage(name, vers, Buffer.alloc(sizeBytes, 7));
+  storage.appendIndex({ name, vers, deps: [], cksum: `sha256:${vers}`, yanked: false });
+}
+
+/**
+ * THE invariant. A sweep that trims payloads without trimming index lines
+ * leaves the index advertising a version whose file is gone — search lists it
+ * and the download 404s. The reverse leaves unreachable bytes on the disk the
+ * sweep exists to reclaim. Both directions have to hold.
+ */
+function expectIndexAndPayloadsAgree(name: string): void {
+  const indexed = storage.readIndex(name).map((e) => e.vers);
+  const stored = storage.storedVersions(name).sort();
+  for (const vers of indexed) {
+    expect(storage.readPackage(name, vers)).not.toBeNull();
+  }
+  expect(stored).toEqual([...indexed].sort());
+}
+
+describe('parseRevision', () => {
+  test('splits a release from its build revision', () => {
+    expect(parseRevision('1.0.3+7')).toEqual({ release: '1.0.3', revision: 7 });
+  });
+
+  test('keeps a Debian epoch with the release', () => {
+    expect(parseRevision('2:1.0.0+1')).toEqual({ release: '2:1.0.0', revision: 1 });
+  });
+
+  test('returns null for a version with no build revision', () => {
+    expect(parseRevision('1.0.0')).toBeNull();
+  });
+});
+
+describe('planModuleSweep', () => {
+  const entry = (vers: string, yanked = false) => ({
+    name: 'm',
+    vers,
+    deps: [],
+    cksum: 'sha256:x',
+    yanked,
+  });
+
+  /**
+   * Plan against a store where every indexed version HAS its payload — the
+   * ordinary case. Passing an empty stored set instead would trip the
+   * unreadable guard, which is a different scenario with its own tests below.
+   */
+  const planWithPayloads = (entries: ReturnType<typeof entry>[], keepBuildRevisions: number) =>
+    planModuleSweep(
+      'm',
+      entries,
+      entries.map((e) => e.vers),
+      { keepBuildRevisions },
+    );
+
+  test('keeps the newest build revision of every release', () => {
+    const entries = [
+      entry('1.0.0+1'),
+      entry('1.0.0+2'),
+      entry('1.0.2+8'),
+      entry('1.0.2+9'),
+      entry('1.0.3+5'),
+      entry('1.0.3+6'),
+      entry('1.0.3+7'),
+    ];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep.map((e) => e.vers)).toEqual(['1.0.0+2', '1.0.2+9', '1.0.3+7']);
+    expect(plan.remove).toEqual(['1.0.0+1', '1.0.2+8', '1.0.3+5', '1.0.3+6']);
+  });
+
+  test('never removes the only revision of a release', () => {
+    const entries = [entry('0.9.0+2'), entry('1.0.0+1')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.remove).toEqual([]);
+  });
+
+  test('a module can never be swept out of existence', () => {
+    const entries = [entry('1.0.0+1')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep).toHaveLength(1);
+  });
+
+  test('keeps more revisions per release when asked', () => {
+    const entries = [entry('1.0.3+5'), entry('1.0.3+6'), entry('1.0.3+7')];
+    const plan = planWithPayloads(entries, 2);
+    expect(plan.keep.map((e) => e.vers)).toEqual(['1.0.3+6', '1.0.3+7']);
+  });
+
+  test('keepBuildRevisions below 1 is clamped — no policy deletes a whole release', () => {
+    // Needs MORE THAN ONE release to be a real check. With a single release
+    // the latest-line retention below masks a missing clamp; with two, an
+    // unclamped 0 wipes out every release except the last.
+    const entries = [entry('1.0.0+1'), entry('1.0.0+2'), entry('1.0.3+5'), entry('1.0.3+6')];
+    const plan = planWithPayloads(entries, 0);
+    expect(plan.keep.map((e) => e.vers)).toEqual(['1.0.0+2', '1.0.3+6']);
+  });
+
+  test('retains what latestVersion resolves to even when the index is out of order', () => {
+    // Last line wins for RegistryClient.latestVersion regardless of ordering,
+    // so a disordered index must not lose the version clients actually fetch.
+    const entries = [entry('1.0.3+7'), entry('1.0.3+6'), entry('1.0.3+5')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep.map((e) => e.vers)).toContain('1.0.3+5');
+    expect(plan.keep.map((e) => e.vers)).toContain('1.0.3+7');
+  });
+
+  test('retains the last NON-yanked line, which is what clients resolve to', () => {
+    const entries = [entry('1.0.3+5'), entry('1.0.3+6'), entry('1.0.3+7', true)];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep.map((e) => e.vers)).toContain('1.0.3+6');
+  });
+
+  test('keeps a version it cannot parse rather than deleting it', () => {
+    const entries = [entry('nonsense'), entry('1.0.0+1'), entry('1.0.0+2')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.remove).toEqual(['1.0.0+1']);
+  });
+
+  test('reports a payload with no index line as an orphan', () => {
+    const plan = planModuleSweep('m', [entry('1.0.0+2')], ['1.0.0+1', '1.0.0+2'], {
+      keepBuildRevisions: 1,
+    });
+    expect(plan.orphans).toEqual(['1.0.0+1']);
+  });
+});
+
+describe('sweep over a fixture store', () => {
+  test('index and payloads agree afterwards, and every release survives', () => {
+    for (const rev of [1, 2, 3, 4, 5]) publish('celilo-registry', `1.0.3+${rev}`);
+    for (const rev of [1, 2]) publish('celilo-registry', `1.0.2+${rev}`);
+    publish('forgejo', '2.1.0+1');
+
+    const report = sweep(storage, { keepBuildRevisions: DEFAULT_KEEP_BUILD_REVISIONS });
+
+    expect(report.removedCount).toBe(5);
+    expectIndexAndPayloadsAgree('celilo-registry');
+    expectIndexAndPayloadsAgree('forgejo');
+    // Original index order is preserved: the fixture published 1.0.3 before
+    // 1.0.2, and the sweep filters lines rather than re-sorting them.
+    expect(storage.readIndex('celilo-registry').map((e) => e.vers)).toEqual(['1.0.3+5', '1.0.2+2']);
+    expect(storage.readIndex('forgejo').map((e) => e.vers)).toEqual(['2.1.0+1']);
+  });
+
+  test('reclaims the bytes it says it reclaims', () => {
+    publish('m', '1.0.0+1', 4096);
+    publish('m', '1.0.0+2', 4096);
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+    expect(report.reclaimedBytes).toBe(4096);
+  });
+
+  test('a dry run changes nothing', () => {
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    const report = sweep(storage, { keepBuildRevisions: 1 }, true);
+
+    expect(report.removedCount).toBe(2);
+    expect(storage.readIndex('m')).toHaveLength(3);
+    expect(storage.storedVersions('m').sort()).toEqual(['1.0.0+1', '1.0.0+2', '1.0.0+3']);
+  });
+
+  test('is idempotent — a second sweep finds nothing to do', () => {
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    sweep(storage, { keepBuildRevisions: 1 });
+    const second = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(second.removedCount).toBe(0);
+    expect(second.orphanCount).toBe(0);
+    expect(second.reclaimedBytes).toBe(0);
+    expectIndexAndPayloadsAgree('m');
+  });
+
+  test('a sweep interrupted after the index rewrite self-heals on the next run', () => {
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    // The crash window: index trimmed, payloads not yet unlinked. The version
+    // is unlisted but still on disk — wasted bytes, not a broken registry.
+    storage.updateIndex('m', storage.readIndex('m').slice(-1));
+    expect(storage.storedVersions('m')).toHaveLength(3);
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.orphanCount).toBe(2);
+    expectIndexAndPayloadsAgree('m');
+  });
+
+  test('a version left unlisted stays downloadable until its payload goes', () => {
+    // Why index-first is the safe order: the download route reads the payload
+    // directly and never consults the index, so the window an interrupted
+    // sweep opens serves stale-but-valid bytes rather than 404ing.
+    publish('m', '1.0.0+1');
+    storage.updateIndex('m', []);
+    expect(storage.readPackage('m', '1.0.0+1')).not.toBeNull();
+  });
+
+  test('reclaims a half-written publish, which is what makes the version publishable again', () => {
+    // Both states below exist on the production registry, created 2026-08-22 by
+    // real failures: an ENOSPC that killed a run after storePackage, and an
+    // EACCES on appendIndex. handlePublish has no rollback between the two.
+    //
+    // The consequence is worse than wasted bytes: `packageExists` reads the
+    // FILESYSTEM, so the orphan makes its own version permanently
+    // unpublishable — "versions are immutable". Removing the orphan is the
+    // repair, and nothing else in the product performs it.
+    storage.storePackage('celilo-mgmt', '0.6.2+2', Buffer.alloc(2048, 1));
+    publish('celilo-mgmt', '0.6.1+1');
+    expect(storage.packageExists('celilo-mgmt', '0.6.2+2')).toBe(true);
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.orphanCount).toBe(1);
+    expect(storage.packageExists('celilo-mgmt', '0.6.2+2')).toBe(false);
+    expectIndexAndPayloadsAgree('celilo-mgmt');
+  });
+
+  test('REPORTS an index line with no payload and does not remove it', () => {
+    // The dangerous direction. Removing the line would actually repair the
+    // module — a dangling entry already 404s — but a missing payload is
+    // indistinguishable from an unreadable store, so it is reported only.
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    storage.removePackage('m', '1.0.0+1');
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.danglingCount).toBe(1);
+    expect(report.modules[0]?.dangling).toEqual(['1.0.0+1']);
+    // Still listed: the sweep reported it rather than acting on it.
+    expect(storage.readIndex('m').map((e) => e.vers)).toContain('1.0.0+1');
+  });
+
+  test('touches nothing when a module has index lines and no payloads at all', () => {
+    // An unmounted volume or a wrong DATA_DIR looks exactly like this. Acting
+    // on it would trim the index of a module whose files are merely
+    // unreachable.
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    for (const rev of [1, 2, 3]) storage.removePackage('m', `1.0.0+${rev}`);
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.unreadable).toEqual(['m']);
+    expect(report.removedCount).toBe(0);
+    expect(storage.readIndex('m')).toHaveLength(3);
+  });
+
+  test('a dangling entry does not stop the rest of the sweep', () => {
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    publish('m', '1.0.0+3');
+    storage.removePackage('m', '1.0.0+1');
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.danglingCount).toBe(1);
+    // 1.0.0+2 is superseded and still had its payload, so it is swept normally.
+    expect(report.removedCount).toBe(1);
+    expect(storage.readIndex('m').map((e) => e.vers)).toEqual(['1.0.0+1', '1.0.0+3']);
+  });
+
+  test('never sweeps the last SERVABLE version because a newer line is dangling', () => {
+    // The failure this guards: retention computed over every index line lets a
+    // dangling NEWEST entry satisfy both the per-release rule and the
+    // latest-line rule, so every servable older version reads as superseded.
+    // The module ends up listed, with one index line, and undownloadable.
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    publish('m', '1.0.0+3');
+    storage.removePackage('m', '1.0.0+3'); // the newest line is now dangling
+
+    sweep(storage, { keepBuildRevisions: 1 });
+
+    // Something is still downloadable, which is the whole point.
+    const servable = storage
+      .readIndex('m')
+      .map((e) => e.vers)
+      .filter((v) => storage.packageExists('m', v));
+    expect(servable.length).toBeGreaterThan(0);
+    expect(servable).toContain('1.0.0+2');
+  });
+
+  test('an empty store sweeps cleanly', () => {
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+    expect(report.removedCount).toBe(0);
+    expect(report.modules).toEqual([]);
+  });
+});
+
+describe('updateIndex atomicity', () => {
+  test('leaves no temp file behind', () => {
+    publish('m', '1.0.0+1');
+    storage.updateIndex('m', storage.readIndex('m'));
+    expect(existsSync(`${storage.indexPath('m')}.tmp`)).toBe(false);
+  });
+
+  test('a write that cannot land leaves the original index intact', () => {
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    const before = storage.readIndex('m');
+    // Block the temp path so the new content cannot be written. A truncating
+    // in-place write ignores the obstruction and replaces the index anyway;
+    // the rename path fails with the original still on disk. This stands in
+    // for the failure that actually matters — ENOSPC on the full disk this
+    // sweep exists to relieve — which needs an fs seam to reproduce directly.
+    mkdirSync(`${storage.indexPath('m')}.tmp`, { recursive: true });
+    expect(() => storage.updateIndex('m', before.slice(0, 1))).toThrow();
+    expect(storage.readIndex('m')).toEqual(before);
+  });
+});

package/registry-server/src/sweep.ts

@@ -0,0 +1,289 @@
+/**
+ * Reclaiming disk from superseded build revisions.
+ *
+ * The registry had no delete path at all: `yank` sets a boolean in the index
+ * and frees nothing, so every revision ever published was retained forever.
+ * A `+N` build revision is auto-assigned on every publish, so the store grew
+ * with every release until the disk filled and the release pipeline stopped.
+ *
+ * ── What the policy keeps, and why it cannot break a fetch ──
+ *
+ * A version is `X.Y.Z+N`: a released semver plus a build revision. The bloat
+ * is the rebuilds, not the releases — a module embedding compiled binaries
+ * republished twenty times carries twenty ~73 MB payloads of one release.
+ *
+ * So the sweep keeps the newest `keepBuildRevisions` of EVERY release and
+ * drops the rest. No release ever disappears, which is what makes the safety
+ * argument checkable rather than a judgement call:
+ *
+ *   - The only version a celilo client can ask for is the one
+ *     `RegistryClient.latestVersion` picks — the last non-yanked line in the
+ *     index. There is no `--version` flag, no lockfile, and `IndexEntry.deps`
+ *     is always `[]`, so nothing pins a specific revision.
+ *   - {@link planModuleSweep} retains that line explicitly, on top of the
+ *     per-release rule, so the property holds even for an index whose lines
+ *     are out of publish order.
+ *   - Every release keeps a downloadable payload, so an operator rolling back
+ *     to an older release still can.
+ *
+ * ── Ordering, and why it is index-first ──
+ *
+ * The download route reads the payload file directly and never consults the
+ * index. That asymmetry decides the order:
+ *
+ *   - index line first, then payload — the window is "unlisted but still
+ *     served". Nothing 404s. A crash here leaves an orphan payload, which
+ *     wastes the disk we are reclaiming but is otherwise correct.
+ *   - payload first, then index — the window is "listed but 404s", an
+ *     actively wrong registry. A crash here leaves it that way.
+ *
+ * So: index first. The orphan a crash leaves behind is then reclaimed by the
+ * NEXT run, which is what makes the sweep idempotent and safe to interrupt.
+ * The orphan pass runs FIRST for a second reason: it is pure unlink and needs
+ * no free space, so it can still make progress on a disk with nothing left to
+ * write with — the state that produced this code.
+ */
+
+import type { IndexEntry, RegistryStorage } from './storage';
+
+export interface SweepPolicy {
+  /**
+   * Build revisions to keep per released semver. Must be >= 1 — keeping zero
+   * would delete a whole release, which this policy never does.
+   */
+  keepBuildRevisions: number;
+}
+
+export const DEFAULT_KEEP_BUILD_REVISIONS = 1;
+
+export interface ModuleSweepPlan {
+  name: string;
+  /** Index entries to retain, in their original order. */
+  keep: IndexEntry[];
+  /** Versions whose index line and payload both go. */
+  remove: string[];
+  /**
+   * Payloads on disk with no index line. Unreachable by search, and the
+   * publisher's immutability check still sees them — `packageExists` reads the
+   * FILESYSTEM, so an orphan makes its version unpublishable forever with no
+   * repair path anywhere else in the product. Safe to delete, and deleting it
+   * IS the repair.
+   */
+  orphans: string[];
+  /**
+   * Index lines whose payload is missing. REPORTED, NEVER REMOVED.
+   *
+   * This is the direction the sweep must never create, and the reason it takes
+   * the index line before the payload. Removing the line would in fact repair
+   * the module — a dangling entry already 404s on download, and dropping it
+   * makes `latestVersion` resolve to a version that can actually be served.
+   * It is left alone anyway, because a missing payload and an unreadable store
+   * are indistinguishable from here: an unmounted volume or a wrong DATA_DIR
+   * makes every payload look absent, and an auto-remove would then delete the
+   * whole index. Reporting costs nothing and cannot destroy anything.
+   */
+  dangling: string[];
+  /**
+   * The module's index lists versions and NOT ONE has a payload on disk. That
+   * is a broken or unmounted store rather than N independent losses, so the
+   * sweep does nothing at all to this module — see {@link ModuleSweepPlan.dangling}.
+   */
+  unreadable: boolean;
+}
+
+export interface SweepReport {
+  modules: Array<{
+    name: string;
+    removed: string[];
+    orphans: string[];
+    dangling: string[];
+    bytes: number;
+  }>;
+  removedCount: number;
+  orphanCount: number;
+  /** Index lines with no payload. Reported for a human; never acted on. */
+  danglingCount: number;
+  /** Modules skipped entirely because their whole payload set is missing. */
+  unreadable: string[];
+  reclaimedBytes: number;
+  dryRun: boolean;
+}
+
+/**
+ * Split `X.Y.Z+N` (or `E:X.Y.Z+N`) into the release it belongs to and its
+ * build revision. Returns null for anything that does not parse — the caller
+ * treats that as "keep", because a version the sweep cannot reason about is
+ * not one it should delete.
+ */
+export function parseRevision(vers: string): { release: string; revision: number } | null {
+  const plus = vers.lastIndexOf('+');
+  if (plus <= 0) return null;
+  const release = vers.slice(0, plus);
+  const revision = Number(vers.slice(plus + 1));
+  if (!Number.isInteger(revision) || revision < 0) return null;
+  return { release, revision };
+}
+
+/**
+ * Decide what one module keeps. Pure — no filesystem, no storage.
+ *
+ * `storedVersions` is what is on DISK, which is deliberately not the same set
+ * as `entries`: a previous interrupted run can leave a payload whose index
+ * line is already gone, and reclaiming it is the whole reason this takes both.
+ */
+export function planModuleSweep(
+  name: string,
+  entries: IndexEntry[],
+  storedVersions: string[],
+  policy: SweepPolicy,
+): ModuleSweepPlan {
+  const keepBuildRevisions = Math.max(1, Math.trunc(policy.keepBuildRevisions));
+
+  const stored = new Set(storedVersions);
+  const dangling = entries.filter((e) => !stored.has(e.vers)).map((e) => e.vers);
+
+  // Every listed version missing its payload is one broken store, not N
+  // independent losses. Touch nothing.
+  if (entries.length > 0 && dangling.length === entries.length) {
+    return { name, keep: entries, remove: [], orphans: [], dangling, unreadable: true };
+  }
+
+  /**
+   * Retention is computed over the SERVABLE entries only — the ones whose
+   * payload is actually there.
+   *
+   * Doing it over every index line is subtly wrong in a way that bites exactly
+   * when the store is already damaged. If a module's NEWEST line is dangling,
+   * that line satisfies both the per-release rule and the latest-line rule, so
+   * every older version — the servable ones — becomes "superseded" and is
+   * swept. The module is then listed, has one index line, and cannot be
+   * downloaded at all. The sweep would not have created the dangling entry,
+   * but it would have removed the last thing that still worked.
+   */
+  const servable = entries.filter((e) => stored.has(e.vers));
+
+  const retained = new Set<string>();
+
+  // The newest `keepBuildRevisions` of each release.
+  const byRelease = new Map<string, Array<{ vers: string; revision: number }>>();
+  for (const entry of servable) {
+    const parsed = parseRevision(entry.vers);
+    if (!parsed) {
+      // Unparseable — never a publish this server accepted, so it is hand-
+      // written state. Keep it and move on.
+      retained.add(entry.vers);
+      continue;
+    }
+    const group = byRelease.get(parsed.release) ?? [];
+    group.push({ vers: entry.vers, revision: parsed.revision });
+    byRelease.set(parsed.release, group);
+  }
+  for (const group of byRelease.values()) {
+    group.sort((a, b) => b.revision - a.revision);
+    for (const { vers } of group.slice(0, keepBuildRevisions)) retained.add(vers);
+  }
+
+  // What every client actually resolves to, retained explicitly rather than
+  // inferred from the rule above. The rule already covers it for an index in
+  // publish order; stating it means a disordered or hand-edited index cannot
+  // turn into an unfetchable module.
+  const lastServable = servable.at(-1);
+  if (lastServable) retained.add(lastServable.vers);
+  const lastUnyanked = [...servable].reverse().find((e) => !e.yanked);
+  if (lastUnyanked) retained.add(lastUnyanked.vers);
+
+  // Only ever removes something it can see. A dangling line is left in the
+  // index untouched and reported instead.
+  const remove = servable.filter((e) => !retained.has(e.vers)).map((e) => e.vers);
+  const removing = new Set(remove);
+  const indexed = new Set(entries.map((e) => e.vers));
+
+  return {
+    name,
+    keep: entries.filter((e) => !removing.has(e.vers)),
+    remove,
+    orphans: storedVersions.filter((v) => !indexed.has(v)),
+    dangling,
+    unreadable: false,
+  };
+}
+
+/**
+ * Apply one module's plan. Orphans first (needs no free space), then the
+ * index rewrite, then the payloads the rewrite just unlisted.
+ */
+function applyModuleSweep(
+  storage: RegistryStorage,
+  plan: ModuleSweepPlan,
+  dryRun: boolean,
+): number {
+  let bytes = 0;
+
+  for (const version of plan.orphans) {
+    bytes += storage.packageSize(plan.name, version);
+    if (!dryRun) storage.removePackage(plan.name, version);
+  }
+
+  for (const version of plan.remove) {
+    bytes += storage.packageSize(plan.name, version);
+  }
+
+  if (plan.remove.length > 0 && !dryRun) {
+    storage.updateIndex(plan.name, plan.keep);
+    for (const version of plan.remove) storage.removePackage(plan.name, version);
+  }
+
+  return bytes;
+}
+
+/** Sweep every module in the store. */
+export function sweep(storage: RegistryStorage, policy: SweepPolicy, dryRun = false): SweepReport {
+  const modules: SweepReport['modules'] = [];
+  let removedCount = 0;
+  let orphanCount = 0;
+  let reclaimedBytes = 0;
+
+  const unreadable: string[] = [];
+  let danglingCount = 0;
+
+  for (const name of storage.storedNames()) {
+    const plan = planModuleSweep(
+      name,
+      storage.readIndex(name),
+      storage.storedVersions(name),
+      policy,
+    );
+
+    if (plan.unreadable) {
+      unreadable.push(name);
+      continue;
+    }
+
+    danglingCount += plan.dangling.length;
+    if (plan.remove.length === 0 && plan.orphans.length === 0 && plan.dangling.length === 0) {
+      continue;
+    }
+
+    const bytes = applyModuleSweep(storage, plan, dryRun);
+    modules.push({
+      name,
+      removed: plan.remove,
+      orphans: plan.orphans,
+      dangling: plan.dangling,
+      bytes,
+    });
+    removedCount += plan.remove.length;
+    orphanCount += plan.orphans.length;
+    reclaimedBytes += bytes;
+  }
+
+  return {
+    modules,
+    removedCount,
+    orphanCount,
+    danglingCount,
+    unreadable,
+    reclaimedBytes,
+    dryRun,
+  };
+}

package/scripts/consumer-paths-changed.ts

@@ -22,6 +22,9 @@
 export const CONSUMER_PATHS = [
   'packages/e2e/**',
   'packages/registry-server/**',
+  // The smoke test IS this gate's body — the only place publishModule and
+  // friends run in the consumer install shape (celilo#1142).
+  'e2e/tests/smoke.test.ts',
   // The publish driver (moved from the dead apps/celilo/scripts/publish.ts).
   'apps/celilo/src/cli/commands/publish/**',
   'scripts/publish.ts',

package/src/address-plan.test.ts

@@ -50,6 +50,25 @@ const SCANNED_PATHS = ['packages/e2e', 'e2e/tests', 'modules/*/e2e'];
  */
 const EXCLUDED = [/^packages\/e2e\/CHANGELOG\.md$/, /address-plan\.test\.ts$/];
 
+/**
+ * A single LINE may exempt itself with `#539-ok: <reason>`.
+ *
+ * There is one legitimate reason to write a banned prefix: enumerating an
+ * RFC 1918 block as a CLASS, which any correct private-address predicate must
+ * do. `192.168.` is both the operator's LAN (banned) and 192.168.0.0/16
+ * (unavoidable), and RETIRED_PREFIXES cannot tell them apart. The tell that
+ * this is the prefix list's blind spot rather than a real judgement: `10.` sits
+ * beside `192.168.` in exactly such a predicate and escapes only because `10.`
+ * was never added to the list.
+ *
+ * Deliberately per-line and not per-file. Excluding a file would blind the gate
+ * to every OTHER address in it, which is how a suppression becomes the next
+ * leak. The reason is required — a marker with nothing after the colon does not
+ * match, because an exemption that names only a line number is the next
+ * reader's mystery.
+ */
+const INLINE_EXEMPTION = /#539-ok:\s*\S/;
+
 function grepRetired(): string[] {
   const pattern = RETIRED_PREFIXES.map(toPattern).join('|');
   let out = '';
@@ -66,7 +85,8 @@ function grepRetired(): string[] {
   return out
     .split('\n')
     .filter(Boolean)
-    .filter((line) => !EXCLUDED.some((re) => re.test(line.split(':')[0])));
+    .filter((line) => !EXCLUDED.some((re) => re.test(line.split(':')[0] as string)))
+    .filter((line) => !INLINE_EXEMPTION.test(line));
 }
 
 describe('simulated address plan (#539)', () => {

package/src/container-manager.ts

@@ -1,5 +1,5 @@
 import { type ExecSyncOptions, execSync, spawn } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
@@ -10,6 +10,7 @@ import {
   firewallZoneLegs,
   generateTestComposeYaml,
   getAllMachines,
+  registryUploadsHostDir,
 } from './docker-compose-generator';
 import { explainBuildFailure } from './doctor';
 import { type ModuleHost, parseModuleHost } from './module-host';
@@ -1005,12 +1006,19 @@ function buildNetworkHandle(
       }
 
       try {
-        // Copy directly into the registry container's /uploads dir.
-        // The registry rebuilds its index on every request, so no HTTP handshake needed.
-        run(
-          `docker compose -f ${SHARED_COMPOSE_FILE} -p ${SHARED_PROJECT_NAME} cp ${JSON.stringify(netappPath)} registry:/uploads/${moduleId}.netapp`,
-          { cwd: composeDir, timeout: 120_000 },
-        );
+        // Write HOST-side into the dir bound at the registry's /uploads. The
+        // registry rescans that dir on every request, so it needs no HTTP
+        // handshake and no restart.
+        //
+        // Deliberately not a `docker compose cp` into the container: /uploads
+        // is a READ-ONLY bind in a consumer install, so the container write
+        // failed for every npm-installed consumer while passing forever in the
+        // monorepo, where the same path is not a mount at all (celilo#1142).
+        // registryUploadsHostDir() is the same function the compose generator
+        // builds the mount from, so the two cannot drift apart again.
+        const uploadsDir = registryUploadsHostDir();
+        mkdirSync(uploadsDir, { recursive: true });
+        copyFileSync(netappPath, join(uploadsDir, `${moduleId}.netapp`));
       } finally {
         if (cleanup)
           try {

package/src/docker-compose-generator.ts

@@ -1,5 +1,5 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { stringify } from 'yaml';
 import { normalizeObservers, observerEnv, observerPlacement } from './observer';
 import { PROXMOX_SIM_IP, SIMULATOR_IPS } from './simulator-ips';
@@ -13,32 +13,76 @@ import {
   zoneIp,
 } from './types';
 
+const PACKAGE_DIR = join(import.meta.dir, '..');
+
+/**
+ * Is this @celilo/e2e running from the monorepo, or from an npm install?
+ *
+ * `<pkgDir>/../../modules` is `<repo>/modules` in the monorepo and
+ * `<consumer>/node_modules/modules` (nonexistent) in a consumer install.
+ */
+function isMonorepoInstall(): boolean {
+  return existsSync(join(PACKAGE_DIR, '..', '..', 'modules'));
+}
+
 /**
- * Volumes for the registry container. Picks between source-bootstrap and
- * uploads-bootstrap based on where the @celilo/e2e package lives:
+ * The host dir bound read-only at the registry's `/uploads` — and therefore
+ * the dir `publishModule` writes a `.netapp` into. The registry rescans it on
+ * every request, so a host-side write is picked up with no container write and
+ * no HTTP handshake.
+ *
+ * Both install shapes bind one. They differ only in WHICH, because they differ
+ * in where standard modules come from:
+ *
+ * - **Monorepo dev** — modules are served live from `/modules`
+ *   (`../../modules`, BOOTSTRAP_MODULES_DIR mode), so edits to a module's
+ *   source flow through without a manual repack. `/uploads` is therefore a
+ *   dedicated drop-zone, emptied on every shared-infra start (see
+ *   `prepareRegistryDropZone`) — a leftover `.netapp` would shadow live source.
  *
- * - **Monorepo dev** — `../../modules` from the compose file (which lives
- *   in `packages/e2e/`) resolves to `<repo>/modules`. The registry runs
- *   in BOOTSTRAP_MODULES_DIR mode and packs source modules on the fly,
- *   so edits to a module's source flow through without manual repack.
+ * - **npm-installed consumer** (lunacycle and friends) — `../../modules` does
+ *   not exist, so there is no source to serve. `/uploads` IS the netapp cache
+ *   `cele2e build-infra` fills from the public registry (see
+ *   stageNetappsFromRegistry in cli/build.ts), and a published module lands
+ *   beside the standard ones. Consumers vendor nothing.
  *
- * - **npm-installed consumer** (lunacycle and friends) — `../../modules`
- *   would resolve to `<consumer>/node_modules/modules`, which doesn't
- *   exist. Docker fails the mount with "permission denied" trying to
- *   create that path. Instead we bind the local `./netapps/` dir to
- *   `/uploads`, and the registry's scanUploadsDir picks up the .netapp
- *   files. That dir is populated at `cele2e build-infra` time by fetching
- *   the standard-module netapps from the public registry (see
- *   stageNetappsFromRegistry in cli/build.ts) — consumers vendor nothing.
+ * Read this through `registryUploadsHostDir()` rather than re-deriving it.
+ * publishModule used to `docker cp` into the container's `/uploads` instead,
+ * which works only where that path is NOT a mount — so it passed forever in
+ * the monorepo and failed for every consumer against the read-only bind
+ * (celilo#1142). One function now decides the mount and the write target
+ * together, so they cannot disagree again.
+ */
+export function registryUploadsHostDir(): string {
+  return join(PACKAGE_DIR, isMonorepoInstall() ? 'uploads' : 'netapps');
+}
+
+/**
+ * Make the drop-zone ready for a shared-infra bring-up.
  *
- * Detection: check whether the would-be monorepo modules dir is real.
- * `import.meta.dir` is `<pkgDir>/src/`, so `../../../modules` from there
- * is `<repo>/modules` in the monorepo and `<consumer>/node_modules/modules`
- * (nonexistent) in a consumer install.
+ * Creates it: Docker silently creates a MISSING bind source as an empty
+ * root-owned directory, which the host then cannot write into.
+ *
+ * Empties it, but only in the monorepo, where `/uploads` is dedicated — a
+ * `.netapp` left by a previous run would shadow the live module source it was
+ * packed from. In a consumer install the same dir IS the build-infra netapp
+ * cache, so clearing it would delete every standard module. (Before
+ * celilo#1142 published netapps lived in the registry's container layer and
+ * died with the container, so starting empty is the behaviour being kept, not
+ * a new one.)
  */
+export function prepareRegistryDropZone(): void {
+  const dir = registryUploadsHostDir();
+  mkdirSync(dir, { recursive: true });
+  if (!isMonorepoInstall()) return;
+  for (const file of readdirSync(dir)) {
+    if (file.endsWith('.netapp')) rmSync(join(dir, file), { force: true });
+  }
+}
+
 function getRegistryVolumes(): string[] {
-  const monorepoModules = join(import.meta.dir, '..', '..', '..', 'modules');
-  return existsSync(monorepoModules) ? ['../../modules:/modules:ro'] : ['./netapps:/uploads:ro'];
+  const uploads = `./${basename(registryUploadsHostDir())}:/uploads:ro`;
+  return isMonorepoInstall() ? ['../../modules:/modules:ro', uploads] : [uploads];
 }
 
 const NETWORK_DRIVER_OPTS = {

package/src/shared-infra.ts

@@ -17,6 +17,7 @@ import {
   SHARED_NETWORKS,
   SHARED_PROJECT_NAME,
   generateSharedInfraYaml,
+  prepareRegistryDropZone,
 } from './docker-compose-generator';
 import { ensureRegistryServerBundle, ensureTerraformFakeBundle } from './registry-bundle';
 
@@ -161,6 +162,11 @@ export async function ensureSharedInfra(): Promise<void> {
   const yaml = generateSharedInfraYaml();
   writeFileSync(join(e2eDir, SHARED_COMPOSE_FILE), yaml);
 
+  // The registry's /uploads bind source must exist before `up` (a missing
+  // bind source becomes an empty root-owned dir), and in the monorepo it
+  // starts empty so no stale .netapp shadows live module source.
+  prepareRegistryDropZone();
+
   // Seed the live DNS zone files from their templates BEFORE the compose
   // mounts them. config/dns/{iamtheinternet.org,example.net}.zone are
   // gitignored runtime state (scrubDnsZones rewrites them per-test); on a