@specific.dev/spectest 0.74.0 → 0.76.0

package/dist/daemon.js

@@ -35,7 +35,7 @@ import { isMobileApp, openPersistentMobile } from "./mobile.js";
 import { buildArgFlags, buildContentKey as computeBuildContentKey, imageTag, isGeneratedDockerignore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
-import { executedSteps, summarizeBuildKit } from "./harness/buildkit-progress.js";
+import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
@@ -507,23 +507,14 @@ async function ensureLocalBuildkitd() {
     }
     // eslint-disable-next-line no-console
     console.log(`[build] building in this VM against the image cache (root ${paths.root}, layers ${paths.layers})`);
-    const union = await ensureBuildkitCacheUnion(paths);
-    if (union) {
-        // One directory for both flags: the merged cache on the layers disk
-        // seen through this lineage's own exports on the root. See
-        // `BUILDKIT_CACHE_UNION` for why the exporter needs the union.
-        _localCacheDir = union;
-        _localCacheImports = [union];
-    }
-    else {
-        // Imports come from the merged cache on the read-only layers disk and
-        // from this lineage's own exports on the root; exports go to the root,
-        // where the merge picks them up (image_cache/merge.rs). Every cold
-        // build re-exports every blob this way, which is the cost the union
-        // removes.
-        _localCacheDir = `${state}/${BUILDKIT_CACHE_DIR}`;
-        _localCacheImports = [`${paths.layers}/${BUILDKIT_CACHE_DIR}`, `${state}/${BUILDKIT_CACHE_DIR}`];
-    }
+    // The cache directory union is for the project's OWN BuildKit (the
+    // `/services` docs page tells it to mount `BUILDKIT_CACHE_UNION`).
+    // The harness's builds no longer touch it: their cache is the
+    // daemon's own state, which lives on the root disk and rides the
+    // base root into the next cold build (CONTAINER_STORE.md §20), so a
+    // hit is a snapshot that already exists — no tar blob to unpack
+    // before the first uncached step, no export pass after a miss.
+    await ensureBuildkitCacheUnion(paths);
     _localBuilder = true;
     return true;
 }
@@ -589,11 +580,6 @@ async function ensureBuildkitCacheUnion(paths) {
     }
     return BUILDKIT_CACHE_UNION;
 }
-/** The exported-cache directory on the cache disk, once the in-VM builder is up. */
-let _localCacheDir = null;
-/** The cache directories a build imports from: the merged one on the
- *  layers disk, then this lineage's own exports. */
-let _localCacheImports = [];
 /**
  * A reference as containerd names it. buildx's `-t` on a remote builder
  * stores an unqualified name (`probe:bx`) that dockerd then cannot
@@ -1092,54 +1078,31 @@ async function runServiceBuild(name, image, tag) {
         const useBuildKit = useLocal || (await hasBuildx());
         const buildEnv = {};
         let buildArgs;
-        // The `--cache-to` flag, held back for a second pass that runs only
-        // when the first one executed a step (see below). Null off the in-VM
-        // builder.
-        let cacheExport = null;
         // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
-        // so every builder — host buildkitd, in-VM BuildKit, legacy — takes it.
+        // so every builder — in-VM BuildKit, dockerd's own, legacy — takes it.
         const argFlags = buildArgFlags(image.buildArgs);
-        if (useLocal && _localCacheDir) {
+        if (useLocal) {
             // The in-VM builder is BuildKit's containerd worker on this VM's
             // own image store (CONTAINER_STORE.md): the output is an image
             // record in dockerd's namespace, unpacked, so there is no `--load`
-            // and nothing crosses a socket. The cache directory on the image cache
-            // disk is what outlives the VM; `mode=max` keeps every
-            // intermediate layer, uncompressed so an import never inflates,
-            // and one tag per service so exports do not replace each other.
-            const cacheTag = name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
-            cacheExport = [
-                "--cache-to",
-                `type=local,dest=${_localCacheDir},mode=max,compression=uncompressed,force-compression=true,tag=${cacheTag}`,
-            ];
-            // LANDMINE: the local cache importer reads the `latest` entry of
-            // the directory's index unless told otherwise, and the exporter
-            // below writes this service's entry under `tag=<service>`. An
-            // import without the same tag misses every time and every
-            // `RUN` re-executes on a seeded cache (seen on the first deploy,
-            // 2026-09-05: the disk carried the blobs, the build used none).
+            // and nothing crosses a socket. No `--cache-from` and no
+            // `--cache-to` either, since 2026-09-07 (§20): the daemon's own
+            // cache database is on the same disk as the snapshots it names
+            // and rides the base root into the next cold build, so a cached
+            // step is a snapshot that already exists. The exported directory
+            // did the same job through tar blobs, at the price of unpacking
+            // every cached parent before the first uncached step (11–79 s for
+            // one `COPY` on Specific's dashboard) and a second full pass to
+            // export after every miss.
             buildArgs = [
                 "buildx", "build",
                 "--builder", LOCAL_BUILDER_NAME,
                 "--progress=plain",
                 "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
-                ..._localCacheImports.flatMap((src) => ["--cache-from", `type=local,src=${src},tag=${cacheTag}`]),
                 ...argFlags,
                 "-f", dfPath, WORKSPACE,
             ];
         }
-        else if (useLocal) {
-            // The daemon came up but reported no cache directory: build on it
-            // and `--load` the result into dockerd.
-            buildArgs = [
-                "buildx", "build",
-                "--builder", LOCAL_BUILDER_NAME,
-                "--load",
-                "--progress=plain",
-                ...argFlags,
-                "-t", tag, "-f", dfPath, WORKSPACE,
-            ];
-        }
         else if (useBuildKit) {
             buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
             buildEnv.DOCKER_BUILDKIT = "1";
@@ -1174,27 +1137,6 @@ async function runServiceBuild(name, image, tag) {
         if (build.code !== 0) {
             return { ok: false, log };
         }
-        // Export the cache only when there is something new to export. A
-        // `mode=max` export costs ~3 s per service even when every blob is
-        // already in the destination (measured 2026-09-06, api: 2.2–3.0 s
-        // for the cached build alone, 4.9–7.5 s with the export), and a cold
-        // start of a cached project is nothing but such builds. When a step
-        // did run, the second pass is that same build fully cached from the
-        // daemon's own state plus the export — seconds on top of a build
-        // that took tens of them. Best-effort: the image is already in the
-        // store, so a failed export is a slower next cold start, not a
-        // failed service.
-        if (cacheExport) {
-            const ran = executedSteps(build.stderr);
-            if (ran.length > 0) {
-                progressService(name, { status: "building", detail: `exporting cache (${ran.length} step(s) ran)` });
-                const exported = await shxStream("docker", [...buildArgs, ...cacheExport], 1_800_000, buildEnv, () => { });
-                if (exported.code !== 0) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`[build] ${name}: cache export failed; the next cold start rebuilds it:\n${exported.stderr.trim().slice(-2000)}`);
-                }
-            }
-        }
         if (useBuildKit) {
             // Keep only the slowest dozen steps ≥1s — enough to profile, small
             // enough to ride back in the /bootstrap response and the journal.
@@ -3015,31 +2957,22 @@ async function bootstrapInner() {
     // image is pulled and whose deps are up starts immediately; it never sits
     // at "image ready" waiting for an unrelated slow build elsewhere.
     //
-    // Prep concurrency: registry pulls always run in parallel (network-bound,
-    // low VM RAM). Dockerfile builds run inside the VM, and two or more
-    // concurrent builds routinely OOM a single VM on monorepos with parallel
-    // pnpm/npm installs (each install fans out to ~16 fetchers + lifecycle
-    // workers, ~70 MB/process), so builds serialize behind a FIFO chain —
-    // but only the builds; pulls and starts run freely alongside them.
+    // Prep concurrency: everything at once. Registry pulls are
+    // network-bound and cheap in RAM. Dockerfile builds all go to the one
+    // in-VM buildkitd, whose `max-parallelism` (all but one vCPU,
+    // `base.rs::BUILDKITD_UP_SH`) caps the steps in flight across every
+    // build it holds, and whose steps run under a cgroup with a memory
+    // ceiling — so a fully cached build finishes at once while a miss is
+    // still running, and two installs that fan out together kill a step,
+    // never the VM. Until 2026-09-07 builds queued behind one FIFO chain
+    // here, the harness's own guard against that OOM (each install fans
+    // out to ~16 fetchers + lifecycle workers, ~70 MB/process): a service
+    // whose build was entirely cached then waited the whole length of a
+    // sibling's miss, 276 s for 4.5 s of work on Specific's `cli`.
     const tags = new Map();
-    const builds = services.filter((s) => s.image.type === "dockerfile");
-    const buildsRunHostSide = false;
-    // A promise chain is a fair FIFO mutex: when builds run in-VM, each build
-    // waits for the previous to settle. Pulls and host-side builds bypass it.
-    let inVmBuildChain = Promise.resolve();
-    const prepImage = (svc) => {
-        // Bootstrap is the only dedup scope: all its builds share one
-        // /workspace generation (see prepareServiceImage).
-        const run = () => prepareServiceImage(svc, { dedup: true });
-        if (svc.image.type === "dockerfile" && !buildsRunHostSide) {
-            const next = inVmBuildChain.then(run, run);
-            // Keep the chain moving even if a build throws; the chain itself never
-            // rejects (the per-service prep promise below is what surfaces errors).
-            inVmBuildChain = next.then(() => undefined, () => undefined);
-            return next;
-        }
-        return run();
-    };
+    // Bootstrap is the only dedup scope: all its builds share one
+    // /workspace generation (see prepareServiceImage).
+    const prepImage = (svc) => prepareServiceImage(svc, { dedup: true });
     const prep = new Map();
     for (const svc of services) {
         const p = (async () => {

package/dist/harness/buildkit-progress.d.ts

@@ -39,11 +39,12 @@ export declare function summarizeBuildKit(out: string): BuildStep[];
  * The Dockerfile steps a build actually ran — the ones a cache export
  * would have something new to record.
  *
- * A fully cached build still has to export its cache today, and that
- * export costs ~3 s per service in `mode=max` even when every blob is
- * already in the destination (measured 2026-09-06: 2.2–3.0 s for the
- * build, 4.9–7.5 s with the export). So the harness builds without
- * `--cache-to` first and exports only when this says something ran.
+ * Between SDK 0.75.0 and 0.76.0 this gated the harness's cache export
+ * (a `mode=max` export cost ~3 s per service with nothing to write,
+ * measured 2026-09-06). The harness exports nothing since its cache is
+ * the daemon's own state (CONTAINER_STORE.md §20); the reading stays,
+ * since it is the one machine-readable answer to "did this build run
+ * anything".
  *
  * What counts: a bracketed stage step (`[builder 3/6] RUN …`) that ended
  * in `DONE` rather than `CACHED`. What does not: BuildKit's own

package/dist/harness/buildkit-progress.js

@@ -68,11 +68,12 @@ export function summarizeBuildKit(out) {
  * The Dockerfile steps a build actually ran — the ones a cache export
  * would have something new to record.
  *
- * A fully cached build still has to export its cache today, and that
- * export costs ~3 s per service in `mode=max` even when every blob is
- * already in the destination (measured 2026-09-06: 2.2–3.0 s for the
- * build, 4.9–7.5 s with the export). So the harness builds without
- * `--cache-to` first and exports only when this says something ran.
+ * Between SDK 0.75.0 and 0.76.0 this gated the harness's cache export
+ * (a `mode=max` export cost ~3 s per service with nothing to write,
+ * measured 2026-09-06). The harness exports nothing since its cache is
+ * the daemon's own state (CONTAINER_STORE.md §20); the reading stays,
+ * since it is the one machine-readable answer to "did this build run
+ * anything".
  *
  * What counts: a bracketed stage step (`[builder 3/6] RUN …`) that ended
  * in `DONE` rather than `CACHED`. What does not: BuildKit's own

package/dist/harness/image-cache.d.ts

@@ -45,17 +45,35 @@ export declare const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
  * One directory that is both: an overlayfs with the layers disk's cache
  * directory as the read-only lower and the root disk's as the upper,
  * mounted here by the harness when the in-VM builder comes up
- * (`daemon.ts::ensureBuildkitCacheUnion`). A build imports from it and
- * exports to it. BuildKit's local exporter skips a blob its destination
- * already holds, and through the union every merged blob is already
- * there — so a fully cached build exports its index and manifest and
- * nothing else, where a fresh directory on the root cost it every
- * uncompressed layer again (1.1 GB and 20 s for one service, measured
- * 2026-09-06). New layers land in the upper, which is exactly the
- * directory the merge read before. A user-run BuildKit mounts this one
- * path for both of its cache flags.
+ * (`daemon.ts::ensureBuildkitCacheUnion`). It is for the PROJECT'S OWN
+ * BuildKit — the `/services` docs page tells it to mount this one path
+ * for both of its cache flags. BuildKit's local exporter skips a blob its
+ * destination already holds, and through the union every merged blob is
+ * already there, so a fully cached build exports its index and manifest
+ * and nothing else (a fresh directory on the root cost every
+ * uncompressed layer again, 1.1 GB and 20 s for one service, measured
+ * 2026-09-06). New layers land in the upper, which the merge reads.
+ *
+ * The harness's own service builds used it too until SDK 0.76.0; since
+ * then their cache is the in-VM daemon's own state, which lives on the
+ * root disk and rides the base root into the next cold build
+ * (CONTAINER_STORE.md §20).
  */
 export declare const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
+/**
+ * The prefix the docs reserve for spectest in that directory's one flat
+ * tag namespace. The harness tagged its service builds under it from
+ * SDK 0.75.0 to 0.76.0, after Specific's `nginx-mod` service tagged its
+ * own `buildctl` cache `nginx-mod` and the two overwrote each other on
+ * alternate boots (2026-09-06); the harness writes no tags now, and the
+ * prefix stays reserved so nothing a project names can ever collide
+ * with something spectest writes there later.
+ */
+export declare const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
+/** The tag a service's Dockerfile build would carry under the reserved
+ *  prefix: the service name, lowercased with anything outside `[a-z0-9-]`
+ *  folded to `-`. Unused by the harness since SDK 0.76.0. */
+export declare function buildkitCacheTag(service: string): string;
 /** The cache's paths, or `null` when this VM carries none.
  *  `SPECTEST_IMAGE_CACHE_MANIFEST` points a test at another file. */
 export declare function imageCachePathsSync(manifest?: string): ImageCachePaths | null;

package/dist/harness/image-cache.js

@@ -39,17 +39,37 @@ export const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
  * One directory that is both: an overlayfs with the layers disk's cache
  * directory as the read-only lower and the root disk's as the upper,
  * mounted here by the harness when the in-VM builder comes up
- * (`daemon.ts::ensureBuildkitCacheUnion`). A build imports from it and
- * exports to it. BuildKit's local exporter skips a blob its destination
- * already holds, and through the union every merged blob is already
- * there — so a fully cached build exports its index and manifest and
- * nothing else, where a fresh directory on the root cost it every
- * uncompressed layer again (1.1 GB and 20 s for one service, measured
- * 2026-09-06). New layers land in the upper, which is exactly the
- * directory the merge read before. A user-run BuildKit mounts this one
- * path for both of its cache flags.
+ * (`daemon.ts::ensureBuildkitCacheUnion`). It is for the PROJECT'S OWN
+ * BuildKit — the `/services` docs page tells it to mount this one path
+ * for both of its cache flags. BuildKit's local exporter skips a blob its
+ * destination already holds, and through the union every merged blob is
+ * already there, so a fully cached build exports its index and manifest
+ * and nothing else (a fresh directory on the root cost every
+ * uncompressed layer again, 1.1 GB and 20 s for one service, measured
+ * 2026-09-06). New layers land in the upper, which the merge reads.
+ *
+ * The harness's own service builds used it too until SDK 0.76.0; since
+ * then their cache is the in-VM daemon's own state, which lives on the
+ * root disk and rides the base root into the next cold build
+ * (CONTAINER_STORE.md §20).
  */
 export const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
+/**
+ * The prefix the docs reserve for spectest in that directory's one flat
+ * tag namespace. The harness tagged its service builds under it from
+ * SDK 0.75.0 to 0.76.0, after Specific's `nginx-mod` service tagged its
+ * own `buildctl` cache `nginx-mod` and the two overwrote each other on
+ * alternate boots (2026-09-06); the harness writes no tags now, and the
+ * prefix stays reserved so nothing a project names can ever collide
+ * with something spectest writes there later.
+ */
+export const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
+/** The tag a service's Dockerfile build would carry under the reserved
+ *  prefix: the service name, lowercased with anything outside `[a-z0-9-]`
+ *  folded to `-`. Unused by the harness since SDK 0.76.0. */
+export function buildkitCacheTag(service) {
+    return `${BUILDKIT_CACHE_TAG_PREFIX}${service.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}`;
+}
 function parse(raw) {
     const parsed = JSON.parse(raw);
     const root = (parsed.disks ?? []).find((d) => d.role === "root" && d.path)?.path;

package/package.json

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

package/src/daemon.ts

@@ -83,7 +83,7 @@ import {
   type CaseMeta,
   type GroupMeta,
 } from "./harness/catalogue.js";
-import { executedSteps, summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
+import { summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import {
   resolveHostPath as resolveVolumeHostPath,
@@ -787,22 +787,14 @@ async function ensureLocalBuildkitd(): Promise<boolean> {
   }
   // eslint-disable-next-line no-console
   console.log(`[build] building in this VM against the image cache (root ${paths.root}, layers ${paths.layers})`);
-  const union = await ensureBuildkitCacheUnion(paths);
-  if (union) {
-    // One directory for both flags: the merged cache on the layers disk
-    // seen through this lineage's own exports on the root. See
-    // `BUILDKIT_CACHE_UNION` for why the exporter needs the union.
-    _localCacheDir = union;
-    _localCacheImports = [union];
-  } else {
-    // Imports come from the merged cache on the read-only layers disk and
-    // from this lineage's own exports on the root; exports go to the root,
-    // where the merge picks them up (image_cache/merge.rs). Every cold
-    // build re-exports every blob this way, which is the cost the union
-    // removes.
-    _localCacheDir = `${state}/${BUILDKIT_CACHE_DIR}`;
-    _localCacheImports = [`${paths.layers}/${BUILDKIT_CACHE_DIR}`, `${state}/${BUILDKIT_CACHE_DIR}`];
-  }
+  // The cache directory union is for the project's OWN BuildKit (the
+  // `/services` docs page tells it to mount `BUILDKIT_CACHE_UNION`).
+  // The harness's builds no longer touch it: their cache is the
+  // daemon's own state, which lives on the root disk and rides the
+  // base root into the next cold build (CONTAINER_STORE.md §20), so a
+  // hit is a snapshot that already exists — no tar blob to unpack
+  // before the first uncached step, no export pass after a miss.
+  await ensureBuildkitCacheUnion(paths);
   _localBuilder = true;
   return true;
 }
@@ -874,11 +866,6 @@ async function ensureBuildkitCacheUnion(paths: ImageCachePaths): Promise<string
   }
   return BUILDKIT_CACHE_UNION;
 }
-/** The exported-cache directory on the cache disk, once the in-VM builder is up. */
-let _localCacheDir: string | null = null;
-/** The cache directories a build imports from: the merged one on the
- *  layers disk, then this lineage's own exports. */
-let _localCacheImports: string[] = [];
 /**
  * A reference as containerd names it. buildx's `-t` on a remote builder
  * stores an unqualified name (`probe:bx`) that dockerd then cannot
@@ -1441,52 +1428,30 @@ async function runServiceBuild(
     const useBuildKit = useLocal || (await hasBuildx());
     const buildEnv: Record<string, string> = {};
     let buildArgs: string[];
-    // The `--cache-to` flag, held back for a second pass that runs only
-    // when the first one executed a step (see below). Null off the in-VM
-    // builder.
-    let cacheExport: string[] | null = null;
     // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
-    // so every builder — host buildkitd, in-VM BuildKit, legacy — takes it.
+    // so every builder — in-VM BuildKit, dockerd's own, legacy — takes it.
     const argFlags = buildArgFlags(image.buildArgs);
-    if (useLocal && _localCacheDir) {
+    if (useLocal) {
       // The in-VM builder is BuildKit's containerd worker on this VM's
       // own image store (CONTAINER_STORE.md): the output is an image
       // record in dockerd's namespace, unpacked, so there is no `--load`
-      // and nothing crosses a socket. The cache directory on the image cache
-      // disk is what outlives the VM; `mode=max` keeps every
-      // intermediate layer, uncompressed so an import never inflates,
-      // and one tag per service so exports do not replace each other.
-      const cacheTag = name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
-      cacheExport = [
-        "--cache-to",
-        `type=local,dest=${_localCacheDir},mode=max,compression=uncompressed,force-compression=true,tag=${cacheTag}`,
-      ];
-      // LANDMINE: the local cache importer reads the `latest` entry of
-      // the directory's index unless told otherwise, and the exporter
-      // below writes this service's entry under `tag=<service>`. An
-      // import without the same tag misses every time and every
-      // `RUN` re-executes on a seeded cache (seen on the first deploy,
-      // 2026-09-05: the disk carried the blobs, the build used none).
+      // and nothing crosses a socket. No `--cache-from` and no
+      // `--cache-to` either, since 2026-09-07 (§20): the daemon's own
+      // cache database is on the same disk as the snapshots it names
+      // and rides the base root into the next cold build, so a cached
+      // step is a snapshot that already exists. The exported directory
+      // did the same job through tar blobs, at the price of unpacking
+      // every cached parent before the first uncached step (11–79 s for
+      // one `COPY` on Specific's dashboard) and a second full pass to
+      // export after every miss.
       buildArgs = [
         "buildx", "build",
         "--builder", LOCAL_BUILDER_NAME,
         "--progress=plain",
         "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
-        ..._localCacheImports.flatMap((src) => ["--cache-from", `type=local,src=${src},tag=${cacheTag}`]),
         ...argFlags,
         "-f", dfPath, WORKSPACE,
       ];
-    } else if (useLocal) {
-      // The daemon came up but reported no cache directory: build on it
-      // and `--load` the result into dockerd.
-      buildArgs = [
-        "buildx", "build",
-        "--builder", LOCAL_BUILDER_NAME,
-        "--load",
-        "--progress=plain",
-        ...argFlags,
-        "-t", tag, "-f", dfPath, WORKSPACE,
-      ];
     } else if (useBuildKit) {
       buildArgs = ["build", ...argFlags, "-t", tag, "-f", dfPath, "--progress=plain", WORKSPACE];
       buildEnv.DOCKER_BUILDKIT = "1";
@@ -1520,27 +1485,6 @@ async function runServiceBuild(
     if (build.code !== 0) {
       return { ok: false, log };
     }
-    // Export the cache only when there is something new to export. A
-    // `mode=max` export costs ~3 s per service even when every blob is
-    // already in the destination (measured 2026-09-06, api: 2.2–3.0 s
-    // for the cached build alone, 4.9–7.5 s with the export), and a cold
-    // start of a cached project is nothing but such builds. When a step
-    // did run, the second pass is that same build fully cached from the
-    // daemon's own state plus the export — seconds on top of a build
-    // that took tens of them. Best-effort: the image is already in the
-    // store, so a failed export is a slower next cold start, not a
-    // failed service.
-    if (cacheExport) {
-      const ran = executedSteps(build.stderr);
-      if (ran.length > 0) {
-        progressService(name, { status: "building", detail: `exporting cache (${ran.length} step(s) ran)` });
-        const exported = await shxStream("docker", [...buildArgs, ...cacheExport], 1_800_000, buildEnv, () => {});
-        if (exported.code !== 0) {
-          // eslint-disable-next-line no-console
-          console.warn(`[build] ${name}: cache export failed; the next cold start rebuilds it:\n${exported.stderr.trim().slice(-2000)}`);
-        }
-      }
-    }
     if (useBuildKit) {
       // Keep only the slowest dozen steps ≥1s — enough to profile, small
       // enough to ride back in the /bootstrap response and the journal.
@@ -3577,36 +3521,23 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
   // image is pulled and whose deps are up starts immediately; it never sits
   // at "image ready" waiting for an unrelated slow build elsewhere.
   //
-  // Prep concurrency: registry pulls always run in parallel (network-bound,
-  // low VM RAM). Dockerfile builds run inside the VM, and two or more
-  // concurrent builds routinely OOM a single VM on monorepos with parallel
-  // pnpm/npm installs (each install fans out to ~16 fetchers + lifecycle
-  // workers, ~70 MB/process), so builds serialize behind a FIFO chain —
-  // but only the builds; pulls and starts run freely alongside them.
+  // Prep concurrency: everything at once. Registry pulls are
+  // network-bound and cheap in RAM. Dockerfile builds all go to the one
+  // in-VM buildkitd, whose `max-parallelism` (all but one vCPU,
+  // `base.rs::BUILDKITD_UP_SH`) caps the steps in flight across every
+  // build it holds, and whose steps run under a cgroup with a memory
+  // ceiling — so a fully cached build finishes at once while a miss is
+  // still running, and two installs that fan out together kill a step,
+  // never the VM. Until 2026-09-07 builds queued behind one FIFO chain
+  // here, the harness's own guard against that OOM (each install fans
+  // out to ~16 fetchers + lifecycle workers, ~70 MB/process): a service
+  // whose build was entirely cached then waited the whole length of a
+  // sibling's miss, 276 s for 4.5 s of work on Specific's `cli`.
   const tags = new Map<string, string>();
-  const builds = services.filter((s) => s.image.type === "dockerfile");
-  const buildsRunHostSide = false;
-  // A promise chain is a fair FIFO mutex: when builds run in-VM, each build
-  // waits for the previous to settle. Pulls and host-side builds bypass it.
-  let inVmBuildChain: Promise<unknown> = Promise.resolve();
-  const prepImage = (
-    svc: NamedService,
-  ): Promise<{ tag: string; buildSteps?: BuildStep[] }> => {
-    // Bootstrap is the only dedup scope: all its builds share one
-    // /workspace generation (see prepareServiceImage).
-    const run = () => prepareServiceImage(svc, { dedup: true });
-    if (svc.image.type === "dockerfile" && !buildsRunHostSide) {
-      const next = inVmBuildChain.then(run, run);
-      // Keep the chain moving even if a build throws; the chain itself never
-      // rejects (the per-service prep promise below is what surfaces errors).
-      inVmBuildChain = next.then(
-        () => undefined,
-        () => undefined,
-      );
-      return next;
-    }
-    return run();
-  };
+  // Bootstrap is the only dedup scope: all its builds share one
+  // /workspace generation (see prepareServiceImage).
+  const prepImage = (svc: NamedService): Promise<{ tag: string; buildSteps?: BuildStep[] }> =>
+    prepareServiceImage(svc, { dedup: true });
   const prep = new Map<string, Promise<void>>();
   for (const svc of services) {
     const p = (async () => {

package/src/harness/buildkit-progress.ts

@@ -77,11 +77,12 @@ export function summarizeBuildKit(out: string): BuildStep[] {
  * The Dockerfile steps a build actually ran — the ones a cache export
  * would have something new to record.
  *
- * A fully cached build still has to export its cache today, and that
- * export costs ~3 s per service in `mode=max` even when every blob is
- * already in the destination (measured 2026-09-06: 2.2–3.0 s for the
- * build, 4.9–7.5 s with the export). So the harness builds without
- * `--cache-to` first and exports only when this says something ran.
+ * Between SDK 0.75.0 and 0.76.0 this gated the harness's cache export
+ * (a `mode=max` export cost ~3 s per service with nothing to write,
+ * measured 2026-09-06). The harness exports nothing since its cache is
+ * the daemon's own state (CONTAINER_STORE.md §20); the reading stays,
+ * since it is the one machine-readable answer to "did this build run
+ * anything".
  *
  * What counts: a bracketed stage step (`[builder 3/6] RUN …`) that ended
  * in `DONE` rather than `CACHED`. What does not: BuildKit's own

package/src/harness/image-cache.test.ts

@@ -28,7 +28,7 @@ describe("isOnImageCache", () => {
   });
 });
 
-import { mergeCacheIndex, type OciIndex } from "./image-cache";
+import { BUILDKIT_CACHE_TAG_PREFIX, buildkitCacheTag, mergeCacheIndex, type OciIndex } from "./image-cache";
 
 const entry = (tag: string, hex: string) => ({ mediaType: "application/vnd.oci.image.manifest.v1+json", digest: `sha256:${hex}`, size: 1, annotations: { "org.opencontainers.image.ref.name": tag } });
 
@@ -62,4 +62,20 @@ describe("mergeCacheIndex", () => {
     const out = mergeCacheIndex(lower, upper, () => true);
     expect(out.manifests.map((m) => m.annotations?.["org.opencontainers.image.ref.name"])).toEqual(["api", "cli", "worker"]);
   });
+
+  /** The directory is one tag namespace shared with the project's own
+   *  BuildKit. The harness's tags are prefixed so a project tag named after
+   *  the same service sits beside it instead of replacing it. */
+  test("a project's tag and the harness's tag for the same service both survive", () => {
+    const both: OciIndex = { schemaVersion: 2, manifests: [entry("nginx-mod", "p1"), entry(buildkitCacheTag("nginx-mod"), "h1")] };
+    const out = mergeCacheIndex(both, null, () => false);
+    expect(out.manifests.map((m) => m.digest)).toEqual(["sha256:p1", "sha256:h1"]);
+  });
+});
+
+describe("buildkitCacheTag", () => {
+  test("the reserved prefix plus the normalised service name", () => {
+    expect(buildkitCacheTag("nginx-mod")).toBe(`${BUILDKIT_CACHE_TAG_PREFIX}nginx-mod`);
+    expect(buildkitCacheTag("Api_v2")).toBe("spectest/service/api-v2");
+  });
 });

package/src/harness/image-cache.ts

@@ -54,18 +54,40 @@ export const BUILDKIT_CACHE_DIR = "spectest-buildkit-cache";
  * One directory that is both: an overlayfs with the layers disk's cache
  * directory as the read-only lower and the root disk's as the upper,
  * mounted here by the harness when the in-VM builder comes up
- * (`daemon.ts::ensureBuildkitCacheUnion`). A build imports from it and
- * exports to it. BuildKit's local exporter skips a blob its destination
- * already holds, and through the union every merged blob is already
- * there — so a fully cached build exports its index and manifest and
- * nothing else, where a fresh directory on the root cost it every
- * uncompressed layer again (1.1 GB and 20 s for one service, measured
- * 2026-09-06). New layers land in the upper, which is exactly the
- * directory the merge read before. A user-run BuildKit mounts this one
- * path for both of its cache flags.
+ * (`daemon.ts::ensureBuildkitCacheUnion`). It is for the PROJECT'S OWN
+ * BuildKit — the `/services` docs page tells it to mount this one path
+ * for both of its cache flags. BuildKit's local exporter skips a blob its
+ * destination already holds, and through the union every merged blob is
+ * already there, so a fully cached build exports its index and manifest
+ * and nothing else (a fresh directory on the root cost every
+ * uncompressed layer again, 1.1 GB and 20 s for one service, measured
+ * 2026-09-06). New layers land in the upper, which the merge reads.
+ *
+ * The harness's own service builds used it too until SDK 0.76.0; since
+ * then their cache is the in-VM daemon's own state, which lives on the
+ * root disk and rides the base root into the next cold build
+ * (CONTAINER_STORE.md §20).
  */
 export const BUILDKIT_CACHE_UNION = "/var/lib/spectest-buildkit-cache";
 
+/**
+ * The prefix the docs reserve for spectest in that directory's one flat
+ * tag namespace. The harness tagged its service builds under it from
+ * SDK 0.75.0 to 0.76.0, after Specific's `nginx-mod` service tagged its
+ * own `buildctl` cache `nginx-mod` and the two overwrote each other on
+ * alternate boots (2026-09-06); the harness writes no tags now, and the
+ * prefix stays reserved so nothing a project names can ever collide
+ * with something spectest writes there later.
+ */
+export const BUILDKIT_CACHE_TAG_PREFIX = "spectest/service/";
+
+/** The tag a service's Dockerfile build would carry under the reserved
+ *  prefix: the service name, lowercased with anything outside `[a-z0-9-]`
+ *  folded to `-`. Unused by the harness since SDK 0.76.0. */
+export function buildkitCacheTag(service: string): string {
+  return `${BUILDKIT_CACHE_TAG_PREFIX}${service.replace(/[^a-z0-9-]/gi, "-").toLowerCase()}`;
+}
+
 function parse(raw: string): ImageCachePaths | null {
   const parsed = JSON.parse(raw) as { disks?: { role?: string; path?: string }[] };
   const root = (parsed.disks ?? []).find((d) => d.role === "root" && d.path)?.path;