@specific.dev/spectest 0.73.1 → 0.75.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 { summarizeBuildKit } from "./harness/buildkit-progress.js";
+import { executedSteps, 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 { IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache } from "./harness/image-cache.js";
+import { BUILDKIT_CACHE_DIR, BUILDKIT_CACHE_UNION, buildkitCacheTag, 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";
@@ -507,14 +507,88 @@ 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})`);
-    // 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).
-    _localCacheDir = `${state}/spectest-buildkit-cache`;
-    _localCacheImports = [`${paths.layers}/spectest-buildkit-cache`, `${state}/spectest-buildkit-cache`];
+    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;
     return true;
 }
+/**
+ * Mount the BuildKit cache union (`BUILDKIT_CACHE_UNION`): overlayfs with
+ * the layers disk's cache directory as the lower and the root disk's as
+ * the upper, so one path serves `--cache-from` and `--cache-to`.
+ *
+ * Idempotent — a delta restore restarts the harness on a guest that
+ * still has the mount. Returns null, and the caller keeps the two-directory
+ * scheme, when the lower does not exist yet (a volume that has never
+ * been merged has no cache directory on its layers disk) or the mount is
+ * refused; the build is then slower, never failed. The work directory
+ * has to share a filesystem with the upper, so it lives on the root disk
+ * beside it; the merge reads neither it nor anything but the upper.
+ */
+async function ensureBuildkitCacheUnion(paths) {
+    const lower = `${paths.layers}/${BUILDKIT_CACHE_DIR}`;
+    const upper = `${paths.root}/${BUILDKIT_CACHE_DIR}`;
+    const work = `${paths.root}/spectest-buildkit-work`;
+    if (!existsSync(lower)) {
+        // eslint-disable-next-line no-console
+        console.log(`[build] no merged BuildKit cache on the layers disk yet; exporting to the root directly`);
+        return null;
+    }
+    // overlayfs shows the upper's `index.json` INSTEAD of the lower's, so
+    // an index on the root (a lineage's exports, or one left behind with
+    // its blobs gone) would hide every merged tag and, naming manifests
+    // that are not there, make BuildKit skip the import altogether. Write
+    // the union of the two into the upper first (`mergeCacheIndex`), and
+    // say what each side held so a miss can be read off the boot log.
+    try {
+        const readIndex = (dir) => existsSync(`${dir}/index.json`) ? JSON.parse(readFileSync(`${dir}/index.json`, "utf8")) : null;
+        const lowerIdx = readIndex(lower);
+        const upperIdx = readIndex(upper);
+        if (upperIdx && lowerIdx) {
+            const merged = mergeCacheIndex(lowerIdx, upperIdx, (hex) => existsSync(`${upper}/blobs/sha256/${hex}`));
+            await fs.mkdir(upper, { recursive: true });
+            await fs.writeFile(`${upper}/index.json`, JSON.stringify(merged));
+            await fs.writeFile(`${upper}/oci-layout`, JSON.stringify({ imageLayoutVersion: "1.0.0" }));
+            // eslint-disable-next-line no-console
+            console.log(`[build] BuildKit cache union: ${lowerIdx.manifests.length} tag(s) from the merged cache, ${upperIdx.manifests.length} on this root, ${merged.manifests.length} after the merge`);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.log(`[build] BuildKit cache union: ${lowerIdx?.manifests.length ?? 0} tag(s) from the merged cache, none on this root`);
+        }
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn(`[build] could not reconcile the BuildKit cache indexes (${err}); the union shows the root's`);
+    }
+    const r = await shx("/bin/sh", [
+        "-c",
+        `mkdir -p "${BUILDKIT_CACHE_UNION}" "${upper}" "${work}" && ` +
+            `{ mountpoint -q "${BUILDKIT_CACHE_UNION}" || ` +
+            `mount -t overlay overlay -o "lowerdir=${lower},upperdir=${upper},workdir=${work}" "${BUILDKIT_CACHE_UNION}"; }`,
+    ], 60_000);
+    if (r.code !== 0) {
+        // eslint-disable-next-line no-console
+        console.warn(`[build] could not mount the BuildKit cache union; exporting to the root directly:\n${(r.stderr || r.stdout).trim()}`);
+        return null;
+    }
+    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
@@ -1018,6 +1092,10 @@ 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.
         const argFlags = buildArgFlags(image.buildArgs);
@@ -1029,7 +1107,19 @@ async function runServiceBuild(name, image, tag) {
             // 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();
+            // 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
@@ -1042,7 +1132,6 @@ async function runServiceBuild(name, image, tag) {
                 "--progress=plain",
                 "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
                 ..._localCacheImports.flatMap((src) => ["--cache-from", `type=local,src=${src},tag=${cacheTag}`]),
-                "--cache-to", `type=local,dest=${_localCacheDir},mode=max,compression=uncompressed,force-compression=true,tag=${cacheTag}`,
                 ...argFlags,
                 "-f", dfPath, WORKSPACE,
             ];
@@ -1093,6 +1182,27 @@ 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.

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

@@ -35,3 +35,21 @@ export interface BuildStep {
  * omitting it makes a fully-cached build look like it did nothing.
  */
 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.
+ *
+ * What counts: a bracketed stage step (`[builder 3/6] RUN …`) that ended
+ * in `DONE` rather than `CACHED`. What does not: BuildKit's own
+ * `[internal]`/`[auth]` bookkeeping, which is never cached and never a
+ * layer, and a `FROM` step that finished in the blink it takes to find
+ * the base image locally — a pulled base takes seconds and does count,
+ * since the export records its layers too.
+ */
+export declare function executedSteps(out: string): string[];

package/dist/harness/buildkit-progress.js

@@ -64,3 +64,57 @@ export function summarizeBuildKit(out) {
     }
     return steps.sort((a, b) => b.secs - a.secs);
 }
+/**
+ * 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.
+ *
+ * What counts: a bracketed stage step (`[builder 3/6] RUN …`) that ended
+ * in `DONE` rather than `CACHED`. What does not: BuildKit's own
+ * `[internal]`/`[auth]` bookkeeping, which is never cached and never a
+ * layer, and a `FROM` step that finished in the blink it takes to find
+ * the base image locally — a pulled base takes seconds and does count,
+ * since the export records its layers too.
+ */
+export function executedSteps(out) {
+    const names = new Map();
+    const stages = new Map();
+    const secs = new Map();
+    const cached = new Set();
+    for (const line of out.split("\n")) {
+        let m = line.match(/^#(\d+)\s+\[([^\]]*)\]\s+(.+)$/);
+        if (m) {
+            const id = `#${m[1]}`;
+            if (!names.has(id)) {
+                names.set(id, m[3].trim().slice(0, MAX_NAME));
+                stages.set(id, m[2].trim());
+            }
+            continue;
+        }
+        m = line.match(/^#(\d+)\s+DONE\s+([\d.]+)s/);
+        if (m) {
+            secs.set(`#${m[1]}`, parseFloat(m[2]));
+            continue;
+        }
+        m = line.match(/^#(\d+)\s+CACHED/);
+        if (m)
+            cached.add(`#${m[1]}`);
+    }
+    const ran = [];
+    for (const [id, name] of names) {
+        if (cached.has(id))
+            continue;
+        const stage = stages.get(id) ?? "";
+        if (stage === "internal" || stage === "auth")
+            continue;
+        if (/^FROM\s/.test(name) && (secs.get(id) ?? 0) < 0.5)
+            continue;
+        ran.push(name);
+    }
+    return ran;
+}

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

@@ -35,6 +35,44 @@ export declare const MKFS_EROFS_PATH = "/usr/local/bin/mkfs.erofs";
 /** The guest's adopt helper (`base.rs::STORE_ADOPT_SH`), POSIX sh so a
  *  nested runtime's busybox can run the same file. */
 export declare const STORE_ADOPT_PATH = "/usr/local/bin/spectest-store-adopt";
+/**
+ * The BuildKit cache directory under each cache disk (`merge.rs::CACHE_DIR`):
+ * on the layers disk the merged export of every earlier build, read-only;
+ * on the root disk this lineage's own exports, which the merge harvests.
+ */
+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.
+ */
+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.
+ */
+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 `-`. */
+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;
@@ -46,3 +84,33 @@ export declare function nestedStoreDir(paths: ImageCachePaths, service: string):
  * delta-restore teardown must not wipe it.
  */
 export declare function isOnImageCache(hostPath: string, paths: ImageCachePaths | null): boolean;
+/** The shape of an OCI layout's `index.json` the BuildKit local cache
+ *  exporter writes: one manifest per tag, the tag in the ref-name
+ *  annotation. */
+export interface OciIndex {
+    schemaVersion?: number;
+    mediaType?: string;
+    manifests: Array<{
+        mediaType?: string;
+        digest: string;
+        size?: number;
+        annotations?: Record<string, string>;
+    }>;
+}
+/**
+ * The index the BuildKit cache union must show: every tag of the merged
+ * cache (lower), overridden by this lineage's own exports (upper) where
+ * the upper still holds the manifest.
+ *
+ * overlayfs shadows whole files, so an `index.json` in the upper hides
+ * the lower's completely — and a root disk can carry one: the exports
+ * of a lineage that built before the union existed, or an index left
+ * behind with its blobs gone. Either way BuildKit then imports from an
+ * index naming a few tags whose manifests may not exist, skips the
+ * import, and every step runs (seen 2026-09-06: a cold build with
+ * every service's cache on the layers disk and 4 stale tags in the
+ * upper built everything from scratch). `upperHasBlob` says whether the
+ * upper holds a manifest's blob; an upper entry without one is dropped,
+ * since it would fail the whole import.
+ */
+export declare function mergeCacheIndex(lower: OciIndex | null, upper: OciIndex | null, upperHasBlob: (hex: string) => boolean): OciIndex;

package/dist/harness/image-cache.js

@@ -29,6 +29,46 @@ export const MKFS_EROFS_PATH = "/usr/local/bin/mkfs.erofs";
 /** The guest's adopt helper (`base.rs::STORE_ADOPT_SH`), POSIX sh so a
  *  nested runtime's busybox can run the same file. */
 export const STORE_ADOPT_PATH = "/usr/local/bin/spectest-store-adopt";
+/**
+ * The BuildKit cache directory under each cache disk (`merge.rs::CACHE_DIR`):
+ * on the layers disk the merged export of every earlier build, read-only;
+ * on the root disk this lineage's own exports, which the merge harvests.
+ */
+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.
+ */
+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.
+ */
+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 `-`. */
+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;
@@ -59,5 +99,51 @@ export function nestedStoreDir(paths, service) {
 export function isOnImageCache(hostPath, paths) {
     if (!paths)
         return false;
+    // The union is the root's cache directory seen through the layers
+    // disk: wiping it would wipe the upper, i.e. this lineage's exports.
+    if (hostPath === BUILDKIT_CACHE_UNION || hostPath.startsWith(`${BUILDKIT_CACHE_UNION}/`))
+        return true;
     return hostPath === paths.root || hostPath.startsWith(`${paths.root}/`) || hostPath === paths.layers || hostPath.startsWith(`${paths.layers}/`);
 }
+const REF_NAME = "org.opencontainers.image.ref.name";
+/**
+ * The index the BuildKit cache union must show: every tag of the merged
+ * cache (lower), overridden by this lineage's own exports (upper) where
+ * the upper still holds the manifest.
+ *
+ * overlayfs shadows whole files, so an `index.json` in the upper hides
+ * the lower's completely — and a root disk can carry one: the exports
+ * of a lineage that built before the union existed, or an index left
+ * behind with its blobs gone. Either way BuildKit then imports from an
+ * index naming a few tags whose manifests may not exist, skips the
+ * import, and every step runs (seen 2026-09-06: a cold build with
+ * every service's cache on the layers disk and 4 stale tags in the
+ * upper built everything from scratch). `upperHasBlob` says whether the
+ * upper holds a manifest's blob; an upper entry without one is dropped,
+ * since it would fail the whole import.
+ */
+export function mergeCacheIndex(lower, upper, upperHasBlob) {
+    const byTag = new Map();
+    const untagged = [];
+    for (const m of lower?.manifests ?? []) {
+        const tag = m.annotations?.[REF_NAME];
+        if (tag)
+            byTag.set(tag, m);
+        else
+            untagged.push(m);
+    }
+    for (const m of upper?.manifests ?? []) {
+        if (!upperHasBlob(m.digest.replace(/^sha256:/, "")))
+            continue;
+        const tag = m.annotations?.[REF_NAME];
+        if (tag)
+            byTag.set(tag, m);
+        else
+            untagged.push(m);
+    }
+    return {
+        schemaVersion: 2,
+        mediaType: lower?.mediaType ?? upper?.mediaType ?? "application/vnd.oci.image.index.v1+json",
+        manifests: [...untagged, ...byTag.values()],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.73.1",
+  "version": "0.75.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 { summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
+import { executedSteps, summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import {
   resolveHostPath as resolveVolumeHostPath,
@@ -135,7 +135,17 @@ import {
 } from "./harness/ingress-table.js";
 import { startTlsTerminator, type TlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
-import { IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache, type ImageCachePaths } from "./harness/image-cache.js";
+import {
+  BUILDKIT_CACHE_DIR,
+  BUILDKIT_CACHE_UNION,
+  buildkitCacheTag,
+  IMAGE_CACHE_MANIFEST,
+  imageCachePathsSync,
+  isOnImageCache,
+  mergeCacheIndex,
+  type ImageCachePaths,
+  type OciIndex,
+} from "./harness/image-cache.js";
 import {
   assertAbsolute,
   certificateHostnames,
@@ -778,14 +788,93 @@ 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})`);
-  // 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).
-  _localCacheDir = `${state}/spectest-buildkit-cache`;
-  _localCacheImports = [`${paths.layers}/spectest-buildkit-cache`, `${state}/spectest-buildkit-cache`];
+  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;
   return true;
 }
+
+/**
+ * Mount the BuildKit cache union (`BUILDKIT_CACHE_UNION`): overlayfs with
+ * the layers disk's cache directory as the lower and the root disk's as
+ * the upper, so one path serves `--cache-from` and `--cache-to`.
+ *
+ * Idempotent — a delta restore restarts the harness on a guest that
+ * still has the mount. Returns null, and the caller keeps the two-directory
+ * scheme, when the lower does not exist yet (a volume that has never
+ * been merged has no cache directory on its layers disk) or the mount is
+ * refused; the build is then slower, never failed. The work directory
+ * has to share a filesystem with the upper, so it lives on the root disk
+ * beside it; the merge reads neither it nor anything but the upper.
+ */
+async function ensureBuildkitCacheUnion(paths: ImageCachePaths): Promise<string | null> {
+  const lower = `${paths.layers}/${BUILDKIT_CACHE_DIR}`;
+  const upper = `${paths.root}/${BUILDKIT_CACHE_DIR}`;
+  const work = `${paths.root}/spectest-buildkit-work`;
+  if (!existsSync(lower)) {
+    // eslint-disable-next-line no-console
+    console.log(`[build] no merged BuildKit cache on the layers disk yet; exporting to the root directly`);
+    return null;
+  }
+  // overlayfs shows the upper's `index.json` INSTEAD of the lower's, so
+  // an index on the root (a lineage's exports, or one left behind with
+  // its blobs gone) would hide every merged tag and, naming manifests
+  // that are not there, make BuildKit skip the import altogether. Write
+  // the union of the two into the upper first (`mergeCacheIndex`), and
+  // say what each side held so a miss can be read off the boot log.
+  try {
+    const readIndex = (dir: string): OciIndex | null =>
+      existsSync(`${dir}/index.json`) ? (JSON.parse(readFileSync(`${dir}/index.json`, "utf8")) as OciIndex) : null;
+    const lowerIdx = readIndex(lower);
+    const upperIdx = readIndex(upper);
+    if (upperIdx && lowerIdx) {
+      const merged = mergeCacheIndex(lowerIdx, upperIdx, (hex) => existsSync(`${upper}/blobs/sha256/${hex}`));
+      await fs.mkdir(upper, { recursive: true });
+      await fs.writeFile(`${upper}/index.json`, JSON.stringify(merged));
+      await fs.writeFile(`${upper}/oci-layout`, JSON.stringify({ imageLayoutVersion: "1.0.0" }));
+      // eslint-disable-next-line no-console
+      console.log(
+        `[build] BuildKit cache union: ${lowerIdx.manifests.length} tag(s) from the merged cache, ${upperIdx.manifests.length} on this root, ${merged.manifests.length} after the merge`,
+      );
+    } else {
+      // eslint-disable-next-line no-console
+      console.log(`[build] BuildKit cache union: ${lowerIdx?.manifests.length ?? 0} tag(s) from the merged cache, none on this root`);
+    }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[build] could not reconcile the BuildKit cache indexes (${err}); the union shows the root's`);
+  }
+  const r = await shx(
+    "/bin/sh",
+    [
+      "-c",
+      `mkdir -p "${BUILDKIT_CACHE_UNION}" "${upper}" "${work}" && ` +
+        `{ mountpoint -q "${BUILDKIT_CACHE_UNION}" || ` +
+        `mount -t overlay overlay -o "lowerdir=${lower},upperdir=${upper},workdir=${work}" "${BUILDKIT_CACHE_UNION}"; }`,
+    ],
+    60_000,
+  );
+  if (r.code !== 0) {
+    // eslint-disable-next-line no-console
+    console.warn(`[build] could not mount the BuildKit cache union; exporting to the root directly:\n${(r.stderr || r.stdout).trim()}`);
+    return null;
+  }
+  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
@@ -1353,6 +1442,10 @@ 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.
     const argFlags = buildArgFlags(image.buildArgs);
@@ -1364,7 +1457,19 @@ async function runServiceBuild(
       // 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();
+      // 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
@@ -1377,7 +1482,6 @@ async function runServiceBuild(
         "--progress=plain",
         "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
         ..._localCacheImports.flatMap((src) => ["--cache-from", `type=local,src=${src},tag=${cacheTag}`]),
-        "--cache-to", `type=local,dest=${_localCacheDir},mode=max,compression=uncompressed,force-compression=true,tag=${cacheTag}`,
         ...argFlags,
         "-f", dfPath, WORKSPACE,
       ];
@@ -1425,6 +1529,27 @@ 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.

package/src/harness/buildkit-progress.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { summarizeBuildKit } from "./buildkit-progress";
+import { executedSteps, summarizeBuildKit } from "./buildkit-progress";
 
 /** A realistic slice of `docker build --progress=plain` output. */
 const SAMPLE = `
@@ -96,3 +96,56 @@ describe("summarizeBuildKit", () => {
     expect(out[0].cached).toBe(true);
   });
 });
+
+/** Captured from a fully cached in-VM build of a real service
+ *  (2026-09-06): bookkeeping steps report DONE, the base image resolves
+ *  in no time, every Dockerfile step is CACHED. */
+const FULLY_CACHED = `
+#1 [internal] load build definition from Dockerfile
+#1 transferring dockerfile: 3.38kB done
+#1 DONE 0.0s
+#2 resolve image config for docker-image://docker.io/docker/dockerfile:1
+#2 DONE 0.1s
+#4 [internal] load metadata for docker.io/library/node:25-slim
+#4 DONE 0.1s
+#5 [stage-0  1/19] FROM docker.io/library/node:25-slim@sha256:81db02c4b671288a03915da9534dbd54f96d0e7c24d80ccc54f5b36b2e684370
+#5 DONE 0.0s
+#6 [internal] load build context
+#6 transferring context: 11.87kB done
+#6 DONE 0.0s
+#7 [stage-0  5/19] RUN --mount=type=cache,target=/pnpm-store,sharing=locked     cd config && pnpm install --frozen-lockfile
+#7 CACHED
+#8 [stage-0 10/19] COPY packages/tunnel/client tunnel/client
+#8 CACHED
+#25 exporting to image
+#25 exporting layers done
+#25 DONE 0.3s
+`;
+
+describe("executedSteps", () => {
+  test("a fully cached build ran nothing", () => {
+    expect(executedSteps(FULLY_CACHED)).toEqual([]);
+  });
+
+  test("a step that ended in DONE ran", () => {
+    expect(executedSteps(SAMPLE)).toEqual([
+      "RUN go build -o /out/api ./cmd/api",
+      "COPY --from=builder /out/api /usr/local/bin/api",
+    ]);
+  });
+
+  /** A base image that had to be pulled is new content the export
+   *  records; one found locally in 0.0s is not. */
+  test("a pulled base image counts, a local one does not", () => {
+    const pulled = FULLY_CACHED.replace("#5 DONE 0.0s", "#5 DONE 4.2s");
+    const ran = executedSteps(pulled);
+    expect(ran).toHaveLength(1);
+    // Names are capped like `summarizeBuildKit`'s, so match the prefix.
+    expect(ran[0].startsWith("FROM docker.io/library/node:25-slim@sha256:")).toBe(true);
+  });
+
+  test("bookkeeping steps never count", () => {
+    const out = "#1 [internal] load build context\n#1 DONE 2.5s\n#2 [auth] library/node:pull token\n#2 DONE 0.4s\n";
+    expect(executedSteps(out)).toEqual([]);
+  });
+});

package/src/harness/buildkit-progress.ts

@@ -72,3 +72,54 @@ export function summarizeBuildKit(out: string): BuildStep[] {
   }
   return steps.sort((a, b) => b.secs - a.secs);
 }
+
+/**
+ * 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.
+ *
+ * What counts: a bracketed stage step (`[builder 3/6] RUN …`) that ended
+ * in `DONE` rather than `CACHED`. What does not: BuildKit's own
+ * `[internal]`/`[auth]` bookkeeping, which is never cached and never a
+ * layer, and a `FROM` step that finished in the blink it takes to find
+ * the base image locally — a pulled base takes seconds and does count,
+ * since the export records its layers too.
+ */
+export function executedSteps(out: string): string[] {
+  const names = new Map<string, string>();
+  const stages = new Map<string, string>();
+  const secs = new Map<string, number>();
+  const cached = new Set<string>();
+  for (const line of out.split("\n")) {
+    let m = line.match(/^#(\d+)\s+\[([^\]]*)\]\s+(.+)$/);
+    if (m) {
+      const id = `#${m[1]}`;
+      if (!names.has(id)) {
+        names.set(id, m[3].trim().slice(0, MAX_NAME));
+        stages.set(id, m[2].trim());
+      }
+      continue;
+    }
+    m = line.match(/^#(\d+)\s+DONE\s+([\d.]+)s/);
+    if (m) {
+      secs.set(`#${m[1]}`, parseFloat(m[2]));
+      continue;
+    }
+    m = line.match(/^#(\d+)\s+CACHED/);
+    if (m) cached.add(`#${m[1]}`);
+  }
+  const ran: string[] = [];
+  for (const [id, name] of names) {
+    if (cached.has(id)) continue;
+    const stage = stages.get(id) ?? "";
+    if (stage === "internal" || stage === "auth") continue;
+    if (/^FROM\s/.test(name) && (secs.get(id) ?? 0) < 0.5) continue;
+    ran.push(name);
+  }
+  return ran;
+}

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

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+
+import { BUILDKIT_CACHE_UNION, isOnImageCache } from "./image-cache";
+
+const paths = { root: "/var/lib/containerd", layers: "/var/lib/spectest-image-cache" };
+
+describe("isOnImageCache", () => {
+  test("the two cache disks and anything under them", () => {
+    expect(isOnImageCache("/var/lib/containerd", paths)).toBe(true);
+    expect(isOnImageCache("/var/lib/containerd/spectest-nested/k8s", paths)).toBe(true);
+    expect(isOnImageCache("/var/lib/spectest-image-cache/spectest-buildkit-cache", paths)).toBe(true);
+  });
+
+  /** The union is the root's export directory seen through the layers
+   *  disk; wiping it at a delta restore would wipe this lineage's exports. */
+  test("the BuildKit cache union counts as cache", () => {
+    expect(isOnImageCache(BUILDKIT_CACHE_UNION, paths)).toBe(true);
+    expect(isOnImageCache(`${BUILDKIT_CACHE_UNION}/blobs`, paths)).toBe(true);
+  });
+
+  test("an ordinary project volume does not", () => {
+    expect(isOnImageCache("/var/cache/spectest/volumes/db", paths)).toBe(false);
+    expect(isOnImageCache("/var/lib/containerd-not", paths)).toBe(false);
+  });
+
+  test("no cache, nothing counts", () => {
+    expect(isOnImageCache(BUILDKIT_CACHE_UNION, null)).toBe(false);
+  });
+});
+
+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 } });
+
+describe("mergeCacheIndex", () => {
+  const lower: OciIndex = { schemaVersion: 2, manifests: [entry("api", "a1"), entry("cli", "c1")] };
+
+  test("no upper index: the merged cache's tags, unchanged", () => {
+    const out = mergeCacheIndex(lower, null, () => false);
+    expect(out.manifests.map((m) => m.annotations?.["org.opencontainers.image.ref.name"])).toEqual(["api", "cli"]);
+  });
+
+  /** The lineage's own export of a service wins over the merged one. */
+  test("an upper entry whose manifest exists overrides the lower's tag", () => {
+    const upper: OciIndex = { schemaVersion: 2, manifests: [entry("api", "a2")] };
+    const out = mergeCacheIndex(lower, upper, (hex) => hex === "a2");
+    const api = out.manifests.find((m) => m.annotations?.["org.opencontainers.image.ref.name"] === "api");
+    expect(api?.digest).toBe("sha256:a2");
+    expect(out.manifests).toHaveLength(2);
+  });
+
+  /** A stale upper index — blobs emptied, index left — would hide every
+   *  lower tag and fail the import; its entries are dropped instead. */
+  test("an upper entry without its manifest blob is dropped", () => {
+    const upper: OciIndex = { schemaVersion: 2, manifests: [entry("api", "a2"), entry("worker", "w1")] };
+    const out = mergeCacheIndex(lower, upper, () => false);
+    expect(out.manifests.map((m) => m.digest)).toEqual(["sha256:a1", "sha256:c1"]);
+  });
+
+  test("a valid upper tag the lower lacks is added", () => {
+    const upper: OciIndex = { schemaVersion: 2, manifests: [entry("worker", "w1")] };
+    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

@@ -43,6 +43,50 @@ export const MKFS_EROFS_PATH = "/usr/local/bin/mkfs.erofs";
  *  nested runtime's busybox can run the same file. */
 export const STORE_ADOPT_PATH = "/usr/local/bin/spectest-store-adopt";
 
+/**
+ * The BuildKit cache directory under each cache disk (`merge.rs::CACHE_DIR`):
+ * on the layers disk the merged export of every earlier build, read-only;
+ * on the root disk this lineage's own exports, which the merge harvests.
+ */
+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.
+ */
+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.
+ */
+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 `-`. */
+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;
@@ -75,5 +119,56 @@ export function nestedStoreDir(paths: ImageCachePaths, service: string): string
  */
 export function isOnImageCache(hostPath: string, paths: ImageCachePaths | null): boolean {
   if (!paths) return false;
+  // The union is the root's cache directory seen through the layers
+  // disk: wiping it would wipe the upper, i.e. this lineage's exports.
+  if (hostPath === BUILDKIT_CACHE_UNION || hostPath.startsWith(`${BUILDKIT_CACHE_UNION}/`)) return true;
   return hostPath === paths.root || hostPath.startsWith(`${paths.root}/`) || hostPath === paths.layers || hostPath.startsWith(`${paths.layers}/`);
 }
+
+/** The shape of an OCI layout's `index.json` the BuildKit local cache
+ *  exporter writes: one manifest per tag, the tag in the ref-name
+ *  annotation. */
+export interface OciIndex {
+  schemaVersion?: number;
+  mediaType?: string;
+  manifests: Array<{ mediaType?: string; digest: string; size?: number; annotations?: Record<string, string> }>;
+}
+
+const REF_NAME = "org.opencontainers.image.ref.name";
+
+/**
+ * The index the BuildKit cache union must show: every tag of the merged
+ * cache (lower), overridden by this lineage's own exports (upper) where
+ * the upper still holds the manifest.
+ *
+ * overlayfs shadows whole files, so an `index.json` in the upper hides
+ * the lower's completely — and a root disk can carry one: the exports
+ * of a lineage that built before the union existed, or an index left
+ * behind with its blobs gone. Either way BuildKit then imports from an
+ * index naming a few tags whose manifests may not exist, skips the
+ * import, and every step runs (seen 2026-09-06: a cold build with
+ * every service's cache on the layers disk and 4 stale tags in the
+ * upper built everything from scratch). `upperHasBlob` says whether the
+ * upper holds a manifest's blob; an upper entry without one is dropped,
+ * since it would fail the whole import.
+ */
+export function mergeCacheIndex(lower: OciIndex | null, upper: OciIndex | null, upperHasBlob: (hex: string) => boolean): OciIndex {
+  const byTag = new Map<string, OciIndex["manifests"][number]>();
+  const untagged: OciIndex["manifests"] = [];
+  for (const m of lower?.manifests ?? []) {
+    const tag = m.annotations?.[REF_NAME];
+    if (tag) byTag.set(tag, m);
+    else untagged.push(m);
+  }
+  for (const m of upper?.manifests ?? []) {
+    if (!upperHasBlob(m.digest.replace(/^sha256:/, ""))) continue;
+    const tag = m.annotations?.[REF_NAME];
+    if (tag) byTag.set(tag, m);
+    else untagged.push(m);
+  }
+  return {
+    schemaVersion: 2,
+    mediaType: lower?.mediaType ?? upper?.mediaType ?? "application/vnd.oci.image.index.v1+json",
+    manifests: [...untagged, ...byTag.values()],
+  };
+}