@specific.dev/spectest 0.70.0 → 0.71.1

package/src/daemon.ts

@@ -92,6 +92,7 @@ import {
 import { pollUntilReady } from "./harness/ready-poll.js";
 import { runWrapperRules } from "./harness/wrapper-rules.js";
 import type { WrapperDiagnostic } from "./harness/wrapper-rules.js";
+import { cpus } from "node:os";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import {
   isTextualContentType,
@@ -240,30 +241,49 @@ const DEFAULT_TEST_TIMEOUT_MS = 60_000;
 const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
 
 // Stable hostname every service container resolves to the host (the
-// `spectest-br0` gateway) — so apps that build or pull images at runtime
-// can point a builder at `spectest-host:5000` (the zot Docker Hub mirror)
-// or `spectest-host:1234` (the shared buildkitd) without hard-coding the
-// gateway IP. Injected into each container's /etc/hosts in runContainer.
+// `spectest-br0` gateway) — so an app that runs its OWN BuildKit inside a
+// test can point its cache export at the host's build-cache registry,
+// `spectest-host:5007`, without hard-coding the gateway IP. Nothing else
+// lives behind it any more: images are pulled and built inside the VM
+// against the container store (CONTAINER_STORE.md). Injected into each
+// container's /etc/hosts in runContainer.
 const SPECTEST_HOST_NAME = "spectest-host";
 
-// The host image-cache gateway, discovered once from the same
-// `registry-mirrors` entry the in-VM dockerd already uses (baked into the
-// local provider's golden /etc/docker/daemon.json). `null` when there's
-// no host cache, so nothing is injected.
+// The host gateway, read once from the guest's own default route
+// (/proc/net/route: destination 0, gateway as a little-endian hex word).
+// `null` when the guest has no default route, in which case nothing is
+// injected.
 let _hostCacheGateway: string | null | undefined;
 function hostCacheGateway(): string | null {
   if (_hostCacheGateway !== undefined) return _hostCacheGateway;
+  _hostCacheGateway = null;
   try {
-    const cfg = JSON.parse(
-      readFileSync("/etc/docker/daemon.json", "utf8"),
-    ) as { "registry-mirrors"?: string[] };
-    const first = cfg["registry-mirrors"]?.[0];
-    _hostCacheGateway = first ? new URL(first).hostname || null : null;
+    for (const line of readFileSync("/proc/net/route", "utf8").split("\n").slice(1)) {
+      const f = line.trim().split(/\s+/);
+      if (f.length < 3 || f[1] !== "00000000") continue;
+      const hex = f[2];
+      const octets = [6, 4, 2, 0].map((i) => parseInt(hex.slice(i, i + 2), 16));
+      if (octets.every((o) => Number.isFinite(o))) {
+        _hostCacheGateway = octets.join(".");
+        break;
+      }
+    }
   } catch {
     _hostCacheGateway = null;
   }
   return _hostCacheGateway;
 }
+/** vCPUs this guest has, for BuildKit's `max-parallelism` — the number
+ *  Blacksmith sets too, and the one that matters now that the build
+ *  competes for the guest's own cores rather than the host's. */
+function cpuCount(): number {
+  try {
+    return Math.max(1, cpus().length);
+  } catch {
+    return 4;
+  }
+}
+
 // WORKSPACE (/workspace) and APP_DIR (/opt/spectest/app) both live in
 // project-files.ts, next to the rule that decides which copy of a project
 // file is the current one.
@@ -688,46 +708,110 @@ async function hasBuildx(): Promise<boolean> {
   return _buildxAvailable;
 }
 
-// A single buildkitd runs on the host (see scripts/install-buildkitd.sh),
-// reachable from every VM at the bridge gateway. Building against it as a
-// `remote` buildx builder gives a persistent, shared layer/mount cache that
-// survives forks and warm-template misses — a fresh VM no longer rebuilds
-// from scratch. The build runs on the host (runc-isolated); `--load` pulls
-// the finished image back into the in-VM dockerd. Detected once; if the
-// builder can't be created or buildkitd is unreachable we fall back to the
-// in-VM builder, so a missing/dead buildkitd just means slower builds.
-const REMOTE_BUILDER_ADDR = process.env.SPECTEST_BUILDKIT_ADDR ?? "tcp://10.42.0.1:1234";
-const REMOTE_BUILDER_NAME = "spectest-remote";
-/** Parent of the per-build buildx config dirs (see isolatedBuildxConfig).
- *  On tmpfs: each holds a builder stub and an 8-byte node id. */
-let _remoteBuilder: boolean | undefined;
-async function ensureRemoteBuilder(): Promise<boolean> {
-  if (_remoteBuilder !== undefined) return _remoteBuilder;
-  if (!(await hasBuildx())) {
-    _remoteBuilder = false;
+// Every VM carries its project's container store (CONTAINER_STORE.md):
+// the disk every pull and every build lands on, mounted by the control
+// plane before this harness starts. The manifest below says where; the
+// in-VM buildkitd keeps its exported cache there too, so a fresh VM finds
+// every layer it built before. Detected once; if the daemon will not
+// start, dockerd's own BuildKit builds instead.
+const IMAGE_CACHE_MANIFEST = "/run/spectest-image-cache.json";
+const LOCAL_BUILDER_NAME = "spectest-local";
+const LOCAL_BUILDKIT_ADDR = "tcp://127.0.0.1:1234";
+/** The bring-up script the cache base bakes (`base.rs::BUILDKITD_UP_SH`). */
+const BUILDKITD_UP_PATH = "/usr/local/bin/spectest-buildkitd-up";
+
+/** Where the control plane mounted this VM's image cache: containerd's
+ *  root (read-write, this VM's own) and the layers disk (read-only, shared
+ *  by every VM of a generation). `null` when the VM carries no cache. */
+async function imageCachePaths(): Promise<{ root: string; layers: string } | null> {
+  try {
+    const raw = await fs.readFile(IMAGE_CACHE_MANIFEST, "utf8");
+    const parsed = JSON.parse(raw) as { disks?: { role?: string; path?: string }[] };
+    const root = (parsed.disks ?? []).find((d) => d.role === "root" && d.path)?.path;
+    const layers = (parsed.disks ?? []).find((d) => d.role === "layers" && d.path)?.path;
+    return root && layers ? { root, layers } : null;
+  } catch {
+    return null;
+  }
+}
+
+let _localBuilder: boolean | undefined;
+/**
+ * Start buildkitd inside this VM with its state on the cache disk, and
+ * register it as a buildx `remote` builder.
+ *
+ * Lazy on purpose: it runs on the first build a project actually does,
+ * so a project with no dockerfile service never pays for a builder. And
+ * 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;
+  const paths = await imageCachePaths();
+  if (!paths) return false;
+  const state = paths.root;
+  if (!(await hasBuildx())) return false;
+
+  // The bring-up itself is a script baked into the image cache's base
+  // snapshot (`base.rs::BUILDKITD_UP_SH`), so production and the real-VM
+  // test drive exactly the same daemon with exactly the same config. All
+  // it takes from us is where the state lives — the registry routing is
+  // its own (Docker Hub via `mirror.gcr.io`, deliberately not the host
+  // zot instance).
+  const started = await shx("/bin/bash", [BUILDKITD_UP_PATH, state], 900_000);
+  if (started.code !== 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[build] in-VM buildkitd would not start; building with dockerd's own BuildKit:\n${(started.stderr || started.stdout).trim()}`,
+    );
     return false;
   }
-  // Idempotent: a repeat create with the same name errors ("existing
-  // instance"), which we treat as already-present.
   const create = await docker(
-    ["buildx", "create", "--name", REMOTE_BUILDER_NAME, "--driver", "remote", REMOTE_BUILDER_ADDR],
+    ["buildx", "create", "--name", LOCAL_BUILDER_NAME, "--driver", "remote", LOCAL_BUILDKIT_ADDR],
     30_000,
   );
   if (create.code !== 0 && !/existing instance|already exists/i.test(create.stderr)) {
-    _remoteBuilder = false;
+    // eslint-disable-next-line no-console
+    console.warn(`[build] could not register the in-VM builder:\n${create.stderr.trim()}`);
     return false;
   }
-  // `inspect --bootstrap` actually dials buildkitd, so it's our reachability
-  // probe. If buildkitd is down this fails and we fall back.
-  const boot = await docker(["buildx", "inspect", "--bootstrap", REMOTE_BUILDER_NAME], 60_000);
-  _remoteBuilder = boot.code === 0;
-  if (!_remoteBuilder) {
+  // `inspect --bootstrap` dials the daemon, so it is both the readiness
+  // wait and the proof it is really answering.
+  const boot = await docker(["buildx", "inspect", "--bootstrap", LOCAL_BUILDER_NAME], 120_000);
+  if (boot.code !== 0) {
     // eslint-disable-next-line no-console
-    console.warn(
-      `[build] remote buildkitd at ${REMOTE_BUILDER_ADDR} unreachable; using in-VM builder:\n${boot.stderr.trim()}`,
-    );
+    console.warn(`[build] in-VM buildkitd never answered; building with dockerd's own BuildKit:\n${boot.stderr.trim()}`);
+    return false;
   }
-  return _remoteBuilder;
+  // 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`];
+  _localBuilder = true;
+  return true;
+}
+/** 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
+ * resolve (measured, CONTAINER_STORE.md), so the in-VM build names its
+ * output in full.
+ */
+function qualifyImageRef(ref: string): string {
+  const slash = ref.indexOf("/");
+  const first = slash < 0 ? "" : ref.slice(0, slash);
+  const isRegistry = first.includes(".") || first.includes(":") || first === "localhost";
+  if (slash < 0) return `docker.io/library/${ref}`;
+  if (!isRegistry) return `docker.io/${ref}`;
+  return ref;
 }
 
 async function ensureNetwork(): Promise<void> {
@@ -788,7 +872,12 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
     // created here nor recorded for the delta-restore wipe.
     if (!(await isExistingNonDirectory(host))) {
       await fs.mkdir(host, { recursive: true });
-      if (vol.source?.startsWith("/") && !host.startsWith("/var/cache/spectest/")) {
+      // …and neither is the pre-disks cache tree, kept for a server still
+      // serving older SDKs. Leaving it out of the manifest is what
+      // protects a project running this SDK against a server whose
+      // teardown guard predates it.
+      const durable = host.startsWith("/var/cache/spectest/");
+      if (vol.source?.startsWith("/") && !durable) {
         await recordAbsoluteVolumeDir(host);
       }
     }
@@ -1348,24 +1437,52 @@ async function runServiceBuild(
     // predates per-Dockerfile ignores — and is written ONLY when the
     // project ships none of its own (see readProjectDockerignore).
     await fs.writeFile(`${dfPath}.dockerignore`, serviceDockerignore(image.exclude));
-    const useRemote = await ensureRemoteBuilder();
-    // Both the remote builder and a local buildx are BuildKit, so both emit
-    // per-step timing on stderr under `--progress=plain` (parsed below). Only
-    // the legacy in-VM builder takes no progress flag.
-    const useBuildKit = useRemote || (await hasBuildx());
+    // The in-VM buildkitd on the container store first: the build runs
+    // inside the guest's own isolation boundary, against this project's
+    // own layer cache, and the finished image is already in the store
+    // dockerd reads. dockerd's built-in BuildKit is the fallback (a guest
+    // with no store, or a daemon that would not start).
+    const useLocal = await ensureLocalBuildkitd();
+    // Both the in-VM daemon and dockerd's buildx are BuildKit, so both
+    // emit per-step timing on stderr under `--progress=plain` (parsed
+    // below). Only the legacy builder takes no progress flag.
+    const useBuildKit = useLocal || (await hasBuildx());
     const buildEnv: Record<string, string> = {};
     let buildArgs: string[];
     // 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);
-    if (useRemote) {
-      // Build on the host-side shared buildkitd (persistent cross-VM cache);
-      // `--load` brings the finished image back into the in-VM dockerd so
-      // runContainer can `docker run` it. The build context (WORKSPACE, minus
-      // .dockerignore) streams to buildkitd over the bridge.
+    if (useLocal && _localCacheDir) {
+      // 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();
+      // 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).
+      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}`]),
+        "--cache-to", `type=local,dest=${_localCacheDir},mode=max,compression=uncompressed,force-compression=true,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", REMOTE_BUILDER_NAME,
+        "--builder", LOCAL_BUILDER_NAME,
         "--load",
         "--progress=plain",
         ...argFlags,
@@ -1674,6 +1791,45 @@ async function waitForReady(svc: NamedService): Promise<void> {
   throw new Error(msg);
 }
 
+/**
+ * Add the container's own account of its death to an error raised by its
+ * `setup` hook.
+ *
+ * `waitForReady` already does this, because a container that never becomes
+ * ready is obviously the container's fault. A `setup` hook is the case that
+ * was missing, and it is the one that reads most misleadingly: the hook
+ * talks to the service over the network, so when the container dies
+ * mid-hook what surfaces is a name that no longer resolves or a rollout
+ * that never finished — a symptom from the far end of a connection to
+ * something that is not there any more. The reason is in a log that goes
+ * with the VM at teardown.
+ *
+ * Only for a container that is **gone**: one that is still up did not cause
+ * this, and its log would bury the real error. Best-effort throughout — a
+ * diagnostic must never replace the failure it explains.
+ */
+async function withContainerPostMortem(name: string, err: unknown): Promise<unknown> {
+  try {
+    const state = await docker(
+      ["inspect", "-f", "{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}}", name],
+      15_000,
+    );
+    const [running, code, oom] = state.stdout.trim().split(/\s+/);
+    if (state.code !== 0 || running !== "false") return err;
+    const logs = await docker(["logs", "--tail=120", name], 30_000);
+    const output = `${logs.stdout}\n${logs.stderr}`.trim();
+    const base = err instanceof Error ? err : new Error(String(err));
+    base.message +=
+      `\n\nThe "${name}" container exited (code ${code}` +
+      `${oom === "true" ? ", OOM-killed" : ""}) while its setup hook was running, ` +
+      `which is why the hook could not reach it.` +
+      (output ? `\nIts last output:\n${output}` : `\nIt logged nothing.`);
+    return base;
+  } catch {
+    return err;
+  }
+}
+
 /** Validate the `dependsOn` graph and return the name→service map used to
  *  walk it. Rules live in `harness/service-graph.ts`. */
 function validateServiceGraph(services: NamedService[]): Map<string, NamedService> {
@@ -3448,18 +3604,14 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
   // 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 parallelize *only* when the host
-  // buildkitd is in play — there the build executes host-side under runc, so
-  // N concurrent builds don't touch the VM's memory ceiling. When we fall
-  // back to the in-VM builder, 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 we
-  // serialize that case behind a FIFO chain — but only the in-VM builds
-  // serialize; pulls and starts run freely alongside them. The remote-builder
-  // probe is memoized, so this up-front call is free; skip it with no builds.
+  // 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.
   const tags = new Map<string, string>();
   const builds = services.filter((s) => s.image.type === "dockerfile");
-  const buildsRunHostSide = builds.length > 0 && (await ensureRemoteBuilder());
+  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();
@@ -3546,11 +3698,15 @@ async function bootstrapInner(): Promise<BootstrapTimings> {
     if (svc.setup) {
       progressService(svc.name, { status: "probing", detail: "running setup" });
       const helpers = await ensureHelpers(svc.name, svc);
-      await svc.setup({
-        name: svc.name,
-        helpers,
-        ...(await spectestContext({ service: svc.name, includeSelf: true })),
-      });
+      try {
+        await svc.setup({
+          name: svc.name,
+          helpers,
+          ...(await spectestContext({ service: svc.name, includeSelf: true })),
+        });
+      } catch (err) {
+        throw await withContainerPostMortem(svc.name, err);
+      }
     }
     progressService(svc.name, { status: "ready", detail: undefined });
     const ti = timings.get(svc.name);

package/src/harness/volume-paths.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
 import {
-  CACHE_ROOT,
   resolveHostPath,
   sanitizeSegment,
   survivesTeardown,
@@ -68,35 +67,3 @@ describe("resolveHostPath", () => {
   });
 });
 
-describe("cache volumes and delta teardown", () => {
-  /** The whole point of the flag: teardown does `rm -rf /workspace`, so a
-   *  cache volume must be rooted outside it or it does not survive. */
-  test("a cache volume is rooted outside the workspace", () => {
-    const host = resolveHostPath("bun", { target: "/root/.bun/install/cache", cache: true }, WS);
-    expect(host.startsWith(CACHE_ROOT)).toBe(true);
-    expect(host.startsWith(WS)).toBe(false);
-  });
-
-  test("a non-cache volume is inside the workspace, so teardown wipes it", () => {
-    const host = resolveHostPath("db", { target: "/data" }, WS);
-    expect(host.startsWith(`${WS}/`)).toBe(true);
-  });
-
-  test("a shared volume honours the cache flag too", () => {
-    const cached = resolveHostPath("a", { name: "layers", target: "/x", cache: true }, WS);
-    const plain = resolveHostPath("a", { name: "layers", target: "/x" }, WS);
-    expect(cached.startsWith(CACHE_ROOT)).toBe(true);
-    expect(plain.startsWith(`${WS}/`)).toBe(true);
-    expect(cached).not.toBe(plain);
-  });
-
-  test("survivesTeardown agrees with where the path landed", () => {
-    expect(survivesTeardown({ target: "/data" }, "db", WS)).toBe(false);
-    expect(survivesTeardown({ target: "/data", cache: true }, "db", WS)).toBe(true);
-    // An absolute source outside /workspace also survives — worth knowing,
-    // because it is a way to keep state by accident.
-    expect(survivesTeardown({ source: "/mnt/big", target: "/d" }, "db", WS)).toBe(true);
-    // …but an absolute source inside /workspace does not.
-    expect(survivesTeardown({ source: "/workspace/keep", target: "/d" }, "db", WS)).toBe(false);
-  });
-});

package/src/harness/volume-paths.ts

@@ -6,27 +6,18 @@
  * delta-restore teardown**.
  *
  * Teardown wipes `/workspace` to give a restored environment fresh-state
- * semantics. Anything that must survive it therefore has to live outside
- * `/workspace` — and that is exactly what `cache: true` selects, by
- * rooting the directory under `/var/cache/spectest/volumes` instead.
- *
- * The flag is only ever correct for **content-addressed accelerator
- * data**: package stores, layer caches — data whose presence can change
- * how *fast* something runs but never *what* it does. It is wrong for any
- * real state, because a restored environment would then start with a
- * previous run's data and stop being reproducible. (Counter-example worth
- * remembering: `k3s()` deliberately does not cache its containerd store —
- * a fresh cluster over an un-cleanly-killed store wedged the apiserver.)
+ * semantics. Every volume lives inside it: the one cache spectest keeps
+ * across environments is the container store, which is not a volume at
+ * all (CONTAINER_STORE.md).
  */
 
 import path from "node:path";
 
+import { expandServiceToken } from "./file-mounts";
+
 /** Root of the per-environment state tree. Wiped by delta teardown. */
 export const DEFAULT_WORKSPACE = "/workspace";
 
-/** Root of the cache tree. Deliberately outside the workspace. */
-export const CACHE_ROOT = "/var/cache/spectest/volumes";
-
 /** Directory holding named shared volumes, under whichever root applies. */
 export const SHARED_DIR = "_shared";
 
@@ -40,8 +31,6 @@ export interface VolumeSpec {
   /** Path inside the container. Used to derive a directory when neither
    *  `name` nor `source` is given. */
   target: string;
-  /** Survive the delta-restore teardown. Content-addressed data only. */
-  cache?: boolean;
 }
 
 /**
@@ -70,6 +59,13 @@ export function sanitizeSegment(p: string): string {
  *  3. A relative `source`, or nothing at all — under the service's own
  *     directory, derived from `target` when `source` is absent.
  *
+ * `source` honours the `{{SPECTEST_SERVICE}}` token, for the same reason
+ * `files` does: a component cannot know the map key the user will give it,
+ * and an **absolute** source gets no automatic per-service directory. A
+ * component that needs one — a nested runtime keeping its store under
+ * {@link NESTED_STORE_ROOT}, where two of them sharing one directory would
+ * be two daemons on one metadata store — writes the token into the path.
+ *
  * `workspace` is a parameter rather than a module constant so the rule is
  * testable without touching the filesystem.
  */
@@ -79,19 +75,18 @@ export function resolveHostPath(
   workspace: string = DEFAULT_WORKSPACE,
 ): string {
   const stateRoot = [workspace, ".spectest", "volumes"];
+  const source = vol.source === undefined ? undefined : expandServiceToken(vol.source, service);
 
   if (vol.name) {
-    const root = vol.cache ? [CACHE_ROOT, SHARED_DIR] : [...stateRoot, SHARED_DIR];
-    return path.join(...root, sanitizeSegment(vol.name));
+    return path.join(...stateRoot, SHARED_DIR, sanitizeSegment(vol.name));
   }
 
-  // An absolute source is the project's own path; `cache` doesn't apply
-  // because the location was already chosen explicitly.
-  if (vol.source && vol.source.startsWith("/")) return vol.source;
+  // An absolute source is the project's own path, used as is.
+  if (source && source.startsWith("/")) return source;
 
-  const root = vol.cache ? [CACHE_ROOT, service] : [...stateRoot, service];
-  if (vol.source) {
-    return path.join(...root, vol.source.replace(/^\/+/, ""));
+  const root = [...stateRoot, service];
+  if (source) {
+    return path.join(...root, source.replace(/^\/+/, ""));
   }
   return path.join(...root, sanitizeSegment(vol.target));
 }
@@ -99,8 +94,9 @@ export function resolveHostPath(
 /**
  * Does this volume survive a delta-restore teardown?
  *
- * True for cache-flagged volumes and for absolute sources outside the
- * workspace — the two ways a directory ends up beyond `rm -rf /workspace`.
+ * True for a volume on a mounted cache disk, and for an absolute source
+ * outside the workspace — the two ways a directory ends up beyond
+ * `rm -rf /workspace`.
  */
 export function survivesTeardown(
   vol: VolumeSpec,

package/src/index.ts

@@ -1276,15 +1276,6 @@ export interface VolumeMount {
   /** Container path. */
   target: string;
   readOnly?: boolean;
-  /**
-   * Cache volume: the backing dir lives outside the per-env state tree and
-   * survives a delta-restore teardown (which recreates every container,
-   * volume, and the daemon for fresh-state semantics). Reserve this for
-   * content-addressed data whose presence is purely an accelerator — an
-   * image/layer store, a package cache — never for app state: anything in
-   * a cache volume is visible to the "fresh" environment.
-   */
-  cache?: boolean;
 }
 
 export interface FileMount {