@specific.dev/spectest 0.75.0 → 0.76.1

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";
@@ -50,7 +50,7 @@ import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectC
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
 import { startTlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
-import { BUILDKIT_CACHE_DIR, BUILDKIT_CACHE_UNION, buildkitCacheTag, IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache, mergeCacheIndex, } from "./harness/image-cache.js";
+import { BUILDKIT_CACHE_DIR, BUILDKIT_CACHE_UNION, IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache, mergeCacheIndex, } from "./harness/image-cache.js";
 import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
 import { conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
@@ -459,6 +459,16 @@ const BUILDKITD_UP_PATH = "/usr/local/bin/spectest-buildkitd-up";
 async function imageCachePaths() {
     return imageCachePathsSync(IMAGE_CACHE_MANIFEST);
 }
+/**
+ * The bring-up, once. A promise and not a flag: every build of a
+ * bootstrap calls this at the same time now that builds go in together,
+ * and a flag set to "not yet" while the first caller waits for buildkitd
+ * sent every other build to dockerd's own builder — which cannot build
+ * on the erofs store at all (`lease does not exist`), so Specific's
+ * first three cold builds on SDK 0.76.0 failed inside ten seconds
+ * (2026-09-07). Sharing the promise makes every caller wait for the one
+ * bring-up and read its one answer.
+ */
 let _localBuilder;
 /**
  * Start buildkitd inside this VM with its state on the cache disk, and
@@ -469,10 +479,11 @@ let _localBuilder;
  * best-effort: a daemon that will not start falls back to the shared host
  * one, which is a slower build and not a failed one.
  */
-async function ensureLocalBuildkitd() {
-    if (_localBuilder !== undefined)
-        return _localBuilder;
-    _localBuilder = false;
+function ensureLocalBuildkitd() {
+    _localBuilder ??= bringUpLocalBuildkitd();
+    return _localBuilder;
+}
+async function bringUpLocalBuildkitd() {
     const paths = await imageCachePaths();
     if (!paths)
         return false;
@@ -507,24 +518,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}`];
-    }
-    _localBuilder = true;
+    // 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);
     return true;
 }
 /**
@@ -589,11 +590,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,62 +1088,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.
-            // The tag carries the `spectest/service/` prefix because the
-            // directory is one flat tag namespace the project's own BuildKit
-            // writes into too (the docs tell it to mount this path): tags merge
-            // newest-wins with no warning anywhere, and a project naturally tags
-            // a build after the thing it builds, which is also what its service
-            // is named. Specific's `nginx-mod` service tagged its own buildctl
-            // cache `nginx-mod` and the two overwrote each other on alternate
-            // boots (reported 2026-09-06). The prefix is reserved in the docs.
-            const cacheTag = buildkitCacheTag(name);
-            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";
@@ -1182,27 +1147,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.
@@ -3023,31 +2967,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,33 +45,34 @@ 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 under which the harness tags its own exports in that
- * directory. It is one flat tag namespace shared with the project's own
- * BuildKit (the `/services` docs page tells it to mount the union), tags
- * merge newest-wins with no warning, and a project naturally tags a build
- * after the thing it builds — which is what its spectest service is named
- * too. So the harness's tags live under a prefix no project would choose,
- * and the docs reserve it. Reported by Specific 2026-09-06: a service
- * `nginx-mod` running `buildctl` tagged its cache `nginx-mod`, and it and
- * the harness's image build for that very container overwrote each other
- * on alternate boots.
+ * 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 BuildKit cache tag for a service's Dockerfile build: the prefix plus
- *  the service name, lowercased with anything outside `[a-z0-9-]` folded
- *  to `-`. */
+/** 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. */

package/dist/harness/image-cache.js

@@ -39,33 +39,34 @@ 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 under which the harness tags its own exports in that
- * directory. It is one flat tag namespace shared with the project's own
- * BuildKit (the `/services` docs page tells it to mount the union), tags
- * merge newest-wins with no warning, and a project naturally tags a build
- * after the thing it builds — which is what its spectest service is named
- * too. So the harness's tags live under a prefix no project would choose,
- * and the docs reserve it. Reported by Specific 2026-09-06: a service
- * `nginx-mod` running `buildctl` tagged its cache `nginx-mod`, and it and
- * the harness's image build for that very container overwrote each other
- * on alternate boots.
+ * 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 BuildKit cache tag for a service's Dockerfile build: the prefix plus
- *  the service name, lowercased with anything outside `[a-z0-9-]` folded
- *  to `-`. */
+/** 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()}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.75.0",
+  "version": "0.76.1",
   "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,
@@ -138,7 +138,6 @@ import { runContainerArgs } from "./harness/container-run.js";
 import {
   BUILDKIT_CACHE_DIR,
   BUILDKIT_CACHE_UNION,
-  buildkitCacheTag,
   IMAGE_CACHE_MANIFEST,
   imageCachePathsSync,
   isOnImageCache,
@@ -737,7 +736,17 @@ async function imageCachePaths(): Promise<ImageCachePaths | null> {
   return imageCachePathsSync(IMAGE_CACHE_MANIFEST);
 }
 
-let _localBuilder: boolean | undefined;
+/**
+ * The bring-up, once. A promise and not a flag: every build of a
+ * bootstrap calls this at the same time now that builds go in together,
+ * and a flag set to "not yet" while the first caller waits for buildkitd
+ * sent every other build to dockerd's own builder — which cannot build
+ * on the erofs store at all (`lease does not exist`), so Specific's
+ * first three cold builds on SDK 0.76.0 failed inside ten seconds
+ * (2026-09-07). Sharing the promise makes every caller wait for the one
+ * bring-up and read its one answer.
+ */
+let _localBuilder: Promise<boolean> | undefined;
 /**
  * Start buildkitd inside this VM with its state on the cache disk, and
  * register it as a buildx `remote` builder.
@@ -747,9 +756,12 @@ let _localBuilder: boolean | undefined;
  * best-effort: a daemon that will not start falls back to the shared host
  * one, which is a slower build and not a failed one.
  */
-async function ensureLocalBuildkitd(): Promise<boolean> {
-  if (_localBuilder !== undefined) return _localBuilder;
-  _localBuilder = false;
+function ensureLocalBuildkitd(): Promise<boolean> {
+  _localBuilder ??= bringUpLocalBuildkitd();
+  return _localBuilder;
+}
+
+async function bringUpLocalBuildkitd(): Promise<boolean> {
   const paths = await imageCachePaths();
   if (!paths) return false;
   const state = paths.root;
@@ -788,23 +800,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}`];
-  }
-  _localBuilder = true;
+  // 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);
   return true;
 }
 
@@ -875,11 +878,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
@@ -1442,60 +1440,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.
-      // The tag carries the `spectest/service/` prefix because the
-      // directory is one flat tag namespace the project's own BuildKit
-      // writes into too (the docs tell it to mount this path): tags merge
-      // newest-wins with no warning anywhere, and a project naturally tags
-      // a build after the thing it builds, which is also what its service
-      // is named. Specific's `nginx-mod` service tagged its own buildctl
-      // cache `nginx-mod` and the two overwrote each other on alternate
-      // boots (reported 2026-09-06). The prefix is reserved in the docs.
-      const cacheTag = buildkitCacheTag(name);
-      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";
@@ -1529,27 +1497,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.
@@ -3586,36 +3533,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.ts

@@ -54,35 +54,36 @@ 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 under which the harness tags its own exports in that
- * directory. It is one flat tag namespace shared with the project's own
- * BuildKit (the `/services` docs page tells it to mount the union), tags
- * merge newest-wins with no warning, and a project naturally tags a build
- * after the thing it builds — which is what its spectest service is named
- * too. So the harness's tags live under a prefix no project would choose,
- * and the docs reserve it. Reported by Specific 2026-09-06: a service
- * `nginx-mod` running `buildctl` tagged its cache `nginx-mod`, and it and
- * the harness's image build for that very container overwrote each other
- * on alternate boots.
+ * 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 BuildKit cache tag for a service's Dockerfile build: the prefix plus
- *  the service name, lowercased with anything outside `[a-z0-9-]` folded
- *  to `-`. */
+/** 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()}`;
 }