@specific.dev/spectest 0.116.0 → 0.116.2

package/dist/harness/sticky-consumer.d.ts

@@ -1,4 +1,5 @@
 import { type KubernetesCacheMaintenance } from "./sticky-kubernetes.js";
+import { type StickyImageRetention } from "./sticky-image-retention.js";
 export declare const STICKY_CAPABILITY = "sticky-disks-v1";
 export declare const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
 export { STICKY_RUNTIME } from "./sticky-paths.js";
@@ -6,18 +7,25 @@ export interface StickyConsumerConfig {
     path: string;
     capacityBytes: number;
     headroomBytes: number;
-    cacheTargetBytes: number;
-    buildkitTargetBytes: number;
+    /** Legacy controller fields, accepted for compatibility but not enforced. */
+    cacheTargetBytes?: number;
+    buildkitTargetBytes?: number;
     compatibility: string;
 }
 declare function exec(program: string, args: string[], timeout?: number): Promise<string>;
 export declare function validateStickyConfig(config: StickyConsumerConfig): void;
+/** Explicit policy avoids BuildKit's default size caps (including its separate
+ * cache-mount/source cap). Use physical capacity as the nonbinding max: with
+ * only minFreeSpace, BuildKit 0.32.2 sets keepBytes == totalSize when healthy,
+ * and pruneOnce's strict '<' check can still evict a record on every GC pass.
+ * Actual filesystem capacity is smaller than the device due to metadata. */
+export declare function stickyBuildkitConfig(config: StickyConsumerConfig): string;
 export declare function initializeStickyConsumer(config: StickyConsumerConfig): Promise<void>;
 /** Filesystem pressure takes precedence over cache age/BuildKit record sizes.
  * Only called after runtime containers/volumes have been removed on the
  * isolated publication clone. Never removes files behind the daemons' backs.
  */
-export declare function collectStickyCache(config: StickyConsumerConfig, run?: typeof exec, usage?: () => Promise<{
+export declare function collectStickyCache(config: StickyConsumerConfig, retention: StickyImageRetention, run?: typeof exec, usage?: () => Promise<{
     freeBytes: number;
     totalBytes: number;
 }>, kubernetes?: KubernetesCacheMaintenance): Promise<void>;

package/dist/harness/sticky-consumer.js

@@ -3,6 +3,7 @@ import { execFile } from "node:child_process";
 import { mkdir, readFile, statfs, writeFile } from "node:fs/promises";
 import { STICKY_RUNTIME } from "./sticky-paths.js";
 import { openKubernetesCacheMaintenance } from "./sticky-kubernetes.js";
+import { recordStickyImageUse } from "./sticky-image-retention.js";
 export const STICKY_CAPABILITY = "sticky-disks-v1";
 export const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
 export { STICKY_RUNTIME } from "./sticky-paths.js";
@@ -35,15 +36,40 @@ export function validateStickyConfig(config) {
     if (config.path !== "/var/lib/spectest-sticky" || config.compatibility !== STICKY_COMPATIBILITY ||
         !Number.isSafeInteger(config.capacityBytes) || config.capacityBytes <= 0 ||
         !Number.isSafeInteger(config.headroomBytes) || config.headroomBytes < 16 * 1024 * 1024 ||
-        !Number.isSafeInteger(config.cacheTargetBytes) || config.cacheTargetBytes <= 0 ||
-        !Number.isSafeInteger(config.buildkitTargetBytes) || config.buildkitTargetBytes <= 0 ||
-        config.buildkitTargetBytes > config.cacheTargetBytes ||
-        config.cacheTargetBytes + config.headroomBytes >= config.capacityBytes) {
+        config.headroomBytes >= config.capacityBytes) {
         throw new Error("unsupported sticky consumer profile or budget");
     }
 }
+/** Explicit policy avoids BuildKit's default size caps (including its separate
+ * cache-mount/source cap). Use physical capacity as the nonbinding max: with
+ * only minFreeSpace, BuildKit 0.32.2 sets keepBytes == totalSize when healthy,
+ * and pruneOnce's strict '<' check can still evict a record on every GC pass.
+ * Actual filesystem capacity is smaller than the device due to metadata. */
+export function stickyBuildkitConfig(config) {
+    validateStickyConfig(config);
+    return `root = "${config.path}/buildkit"
+[grpc]
+  address = ["tcp://127.0.0.1:1234"]
+[worker.oci]
+  enabled = false
+[worker.containerd]
+  enabled = true
+  address = "/run/containerd/containerd.sock"
+  namespace = "moby"
+  snapshotter = "overlayfs"
+  gc = true
+[[worker.containerd.gcpolicy]]
+  all = true
+  maxUsedSpace = ${config.capacityBytes}
+  minFreeSpace = ${config.headroomBytes}
+`;
+}
 export async function initializeStickyConsumer(config) {
     validateStickyConfig(config);
+    // Do not persist obsolete caps supplied by an older controller. Maintenance
+    // also ignores them when restoring a snapshot written by an older SDK.
+    config = { path: config.path, capacityBytes: config.capacityBytes,
+        headroomBytes: config.headroomBytes, compatibility: config.compatibility };
     await exec("mountpoint", ["-q", config.path]);
     // The base must have stopped these before its RAM was captured. Refuse an
     // unexpected writer rather than racing it for the standard daemon sockets.
@@ -72,21 +98,7 @@ disabled_plugins = ["io.containerd.grpc.v1.cri"]
     dockerConfig.features = { "containerd-snapshotter": true };
     dockerConfig["storage-driver"] = "overlayfs";
     await writeFile(`${STICKY_RUNTIME}/docker.json`, JSON.stringify(dockerConfig));
-    await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, `root = "${config.path}/buildkit"
-[grpc]
-  address = ["tcp://127.0.0.1:1234"]
-[worker.oci]
-  enabled = false
-[worker.containerd]
-  enabled = true
-  address = "/run/containerd/containerd.sock"
-  namespace = "moby"
-  snapshotter = "overlayfs"
-  gc = true
-  reservedSpace = "1GB"
-  maxUsedSpace = ${config.buildkitTargetBytes}
-  minFreeSpace = ${config.headroomBytes}
-`);
+    await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, stickyBuildkitConfig(config));
     const start = async (unit, program, args) => {
         await exec("systemd-run", ["--quiet", "--unit", unit, "-p", "TimeoutStopSec=30",
             // Pinned BuildKit 0.32.2 returns 1 after its normal first-SIGTERM
@@ -109,22 +121,38 @@ disabled_plugins = ["io.containerd.grpc.v1.cri"]
  * Only called after runtime containers/volumes have been removed on the
  * isolated publication clone. Never removes files behind the daemons' backs.
  */
-export async function collectStickyCache(config, run = exec, usage = async () => {
+export async function collectStickyCache(config, retention, run = exec, usage = async () => {
     const fs = await statfs(config.path);
     return { freeBytes: fs.bavail * fs.bsize, totalBytes: fs.blocks * fs.bsize };
 }, kubernetes) {
     validateStickyConfig(config);
     const buildctl = ["--addr", "tcp://127.0.0.1:1234", "prune"];
-    await run("buildctl", [...buildctl, "--keep-duration", "168h"], 120_000);
-    await run("docker", ["image", "prune", "-af", "--filter", "until=168h"], 120_000);
-    const withinTarget = (fs) => fs.freeBytes >= config.headroomBytes && fs.totalBytes - fs.freeBytes <= config.cacheTargetBytes;
+    // Docker 29's containerd until filter uses local image-record creation;
+    // inspect's Created uses the publisher's build date. Neither tracks use.
+    // Never prune a just-used image merely because either timestamp is old.
+    const protectedImage = (id) => retention.protectedImages.has(id) || kubernetes?.protectedImages.has(id);
+    const images = [...retention.images].sort((a, b) => a.lastUsed - b.lastUsed || a.id.localeCompare(b.id));
+    const expired = new Set();
+    for (const image of images) {
+        if (protectedImage(image.id) || image.lastUsed >= retention.observedAt - 6 * 60 * 60 * 1000)
+            continue;
+        await run("docker", ["image", "rm", "-f", image.id], 120_000);
+        expired.add(image.id);
+    }
+    // Drop expired image references first so they no longer pin obsolete build
+    // layers. Cache mounts need a longer window: a cached RUN skips mounting
+    // its package cache, even though a later dependency change will need it.
+    await run("buildctl", [...buildctl, "--keep-duration", "6h", "--filter", "type!=exec.cachemount"], 120_000);
+    await run("buildctl", [...buildctl, "--keep-duration", "168h", "--filter", "type==exec.cachemount"], 120_000);
+    const withinTarget = (fs) => fs.freeBytes >= config.headroomBytes;
     let fs = await usage();
-    // Always enforce the independent BuildKit target. Its accounting alone
-    // cannot bound shared images/content, so also request real filesystem space.
+    if (withinTarget(fs))
+        return;
+    // All consumers share this filesystem. Reclaim only the missing headroom;
+    // a per-consumer cap evicts useful cache even when the disk is mostly empty.
     const pruneBuildkit = async () => {
-        await run("buildctl", [...buildctl, "--all", "--keep-storage",
-            String(Math.floor(config.buildkitTargetBytes / 1e6)), "--free-storage",
-            String(Math.ceil(Math.max(config.headroomBytes, fs.totalBytes - config.cacheTargetBytes) / 1e6))], 120_000);
+        await run("buildctl", [...buildctl, "--all", "--free-storage",
+            String(Math.ceil(config.headroomBytes / 1e6))], 120_000);
         fs = await usage();
     };
     await pruneBuildkit();
@@ -135,16 +163,15 @@ export async function collectStickyCache(config, run = exec, usage = async () =>
         if (withinTarget(fs))
             return;
     }
-    // Pressure can be entirely in recent Docker images. Drop oldest images
-    // first, even within the age window, until the whole filesystem fits.
-    const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"])).split(/\s+/).filter(Boolean))];
-    const images = ids.length
-        ? JSON.parse(await run("docker", ["image", "inspect", ...ids])) : [];
-    images.sort((a, b) => a.Created.localeCompare(b.Created) || a.Id.localeCompare(b.Id));
+    // Under pressure, evict least recently used images, including within the
+    // age window, but preserve this environment's images for the next build.
     for (const image of images) {
-        if (kubernetes?.protectedImages.has(image.Id))
+        if (expired.has(image.id) || protectedImage(image.id))
             continue;
-        await run("docker", ["image", "rm", "-f", image.Id], 120_000);
+        await run("docker", ["image", "rm", "-f", image.id], 120_000);
+        fs = await usage();
+        if (withinTarget(fs))
+            return;
         await pruneBuildkit();
         if (withinTarget(fs))
             return;
@@ -153,14 +180,15 @@ export async function collectStickyCache(config, run = exec, usage = async () =>
     for (let pass = 0; pass < 3 && !withinTarget(fs); pass++)
         await pruneBuildkit();
     if (!withinTarget(fs))
-        throw new Error("sticky cache cannot meet filesystem retention target and write headroom");
+        throw new Error("sticky cache cannot reclaim required write headroom");
 }
 /** Only on an isolated maintenance clone; never on the live ready environment. */
 export async function prepareStickyConsumer(artifact = false) {
     const config = JSON.parse(await readFile(`${STICKY_RUNTIME}/consumer.json`, "utf8"));
     validateStickyConfig(config);
     if (!artifact) {
-        const containers = (await exec("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+        const retention = await recordStickyImageUse(config.path, exec);
+        const { containers } = retention;
         if (containers.length)
             await exec("docker", ["rm", "-f", ...containers]);
         const volumes = (await exec("docker", ["volume", "ls", "-q"])).split(/\s+/).filter(Boolean);
@@ -168,7 +196,7 @@ export async function prepareStickyConsumer(artifact = false) {
             await exec("docker", ["volume", "rm", ...volumes]);
         const kubernetes = await openKubernetesCacheMaintenance(exec);
         try {
-            await collectStickyCache(config, exec, undefined, kubernetes);
+            await collectStickyCache(config, retention, exec, undefined, kubernetes);
         }
         finally {
             await kubernetes.close();

package/dist/harness/sticky-image-retention.d.ts

@@ -0,0 +1,15 @@
+import type { CacheCommand } from "./sticky-kubernetes.js";
+export interface StickyImageRetention {
+    images: {
+        id: string;
+        lastUsed: number;
+    }[];
+    protectedImages: Set<string>;
+    containers: string[];
+    observedAt: number;
+}
+/** Call before removing containers from the isolated publication clone.
+ * New/legacy images get a first observation; inherited unused images retain
+ * their previous timestamp. Rewriting from the inventory drops stale IDs.
+ */
+export declare function recordStickyImageUse(root: string, run: CacheCommand, now?: number): Promise<StickyImageRetention>;

package/dist/harness/sticky-image-retention.js

@@ -0,0 +1,32 @@
+/** Image use belongs to the cache lineage, not the publisher's image clock. */
+import { randomUUID } from "node:crypto";
+import { readFile, rename, writeFile } from "node:fs/promises";
+/** Call before removing containers from the isolated publication clone.
+ * New/legacy images get a first observation; inherited unused images retain
+ * their previous timestamp. Rewriting from the inventory drops stale IDs.
+ */
+export async function recordStickyImageUse(root, run, now = Date.now()) {
+    const path = `${root}/.spectest-image-use.json`;
+    const saved = await readFile(path, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    const previous = saved === undefined ? { schema: 1, images: {} } : JSON.parse(saved);
+    if (previous.schema !== 1 || !previous.images || typeof previous.images !== "object" ||
+        Array.isArray(previous.images) || Object.values(previous.images).some(value => typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) {
+        throw new Error("invalid sticky image-use ledger");
+    }
+    const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"]))
+            .split(/\s+/).filter(Boolean))];
+    const containers = (await run("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+    const protectedImages = new Set(containers.length
+        ? (await run("docker", ["container", "inspect", "--format", "{{.Image}}", ...containers]))
+            .split(/\s+/).filter(Boolean) : []);
+    const images = ids.map(id => ({ id, lastUsed: protectedImages.has(id) ? now : previous.images[id] ?? now }));
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify({ schema: 1,
+        images: Object.fromEntries(images.map(({ id, lastUsed }) => [id, lastUsed])) }));
+    await rename(temporary, path);
+    return { images, protectedImages, containers, observedAt: now };
+}

package/package.json

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

package/src/harness/sticky-consumer.test.ts

@@ -1,55 +1,141 @@
 import { expect, test } from "bun:test";
-import { STICKY_COMPATIBILITY, validateStickyConfig, collectStickyCache } from "./sticky-consumer";
+import { STICKY_COMPATIBILITY, validateStickyConfig, collectStickyCache, stickyBuildkitConfig } from "./sticky-consumer";
+
+import type { StickyImageRetention } from "./sticky-image-retention";
+
+const now = Date.UTC(2026, 9, 13);
+const retention = (images: StickyImageRetention["images"] = [], protectedImages: string[] = []): StickyImageRetention =>
+  ({ images, protectedImages: new Set(protectedImages), containers: [], observedAt: now });
 
 const GiB = 1024 ** 3;
 const config = { path: "/var/lib/spectest-sticky", capacityBytes: 256 * GiB,
-  headroomBytes: 32 * GiB, cacheTargetBytes: 64 * GiB, buildkitTargetBytes: 32 * GiB,
+  headroomBytes: 32 * GiB,
   compatibility: STICKY_COMPATIBILITY };
 
-test("sticky consumer validates independent retention and working budgets", () => {
+test("sticky consumer validates disk capacity and required free space", () => {
   expect(() => validateStickyConfig(config)).not.toThrow();
-  // Changing capacity does not require increasing either retention target.
+  // Retention has no per-consumer size caps.
   expect(() => validateStickyConfig({ ...config, capacityBytes: 512 * GiB })).not.toThrow();
   for (const override of [{ path: "/" }, { compatibility: "legacy" }, { headroomBytes: 0 },
     { headroomBytes: config.capacityBytes }, { capacityBytes: Number.NaN },
-    { cacheTargetBytes: 240 * GiB }, { buildkitTargetBytes: 65 * GiB }, { cacheTargetBytes: Number.NaN }]) {
+    { headroomBytes: Number.NaN }, { headroomBytes: -1 }, { capacityBytes: 0 }]) {
     expect(() => validateStickyConfig({ ...config, ...override })).toThrow();
   }
 });
 
-test("filesystem pressure removes oldest Docker images when BuildKit pruning frees nothing", async () => {
-  let used = 100 * GiB;
+test("automatic BuildKit GC has one free-space policy without default cache-size caps", () => {
+  const worker = (Bun.TOML.parse(stickyBuildkitConfig(config)) as any).worker.containerd;
+  expect(worker.gc).toBe(true);
+  expect(worker.gcpolicy).toEqual([{ all: true, maxUsedSpace: config.capacityBytes, minFreeSpace: 32 * GiB }]);
+  expect(worker.maxUsedSpace).toBeUndefined();
+  // Older controllers still send targets; they must not reinstate size GC.
+  expect(stickyBuildkitConfig({ ...config, cacheTargetBytes: 64 * GiB, buildkitTargetBytes: 32 * GiB }))
+    .toBe(stickyBuildkitConfig(config));
+});
+
+test("Listen-sized and larger caches retain recent build state while there is headroom", async () => {
+  for (const used of [77, 160, 219]) {
+    const calls: string[][] = [];
+    const run = async (command: string, args: string[]) => { calls.push([command, ...args]); return ""; };
+    // Real filesystem capacity excludes ext4 overhead. Legacy wire values
+    // must not turn 77 GiB of healthy cache into a 64 GiB pressure event.
+    await collectStickyCache({ ...config, cacheTargetBytes: 64 * GiB, buildkitTargetBytes: 32 * GiB },
+      retention([{ id: "postgres", lastUsed: now }]), run,
+      async () => ({ totalBytes: 251 * GiB, freeBytes: (251 - used) * GiB }));
+    expect(calls.some(c => c.includes("--free-storage") || c.includes("--keep-storage"))).toBe(false);
+    expect(calls.some(c => c[0] === "docker")).toBe(false);
+  }
+});
+
+test("pressure reclamation stops when the free-space reserve is restored", async () => {
+  let free = 20 * GiB;
+  const calls: string[][] = [];
+  const run = async (command: string, args: string[]) => {
+    calls.push([command, ...args]);
+    if (args.includes("--free-storage")) free = 33 * GiB;
+    return "";
+  };
+  await collectStickyCache(config, retention([{ id: "unused", lastUsed: now }]), run,
+    async () => ({ totalBytes: 251 * GiB, freeBytes: free }));
+  expect(calls.filter(c => c.includes("--free-storage"))).toHaveLength(1);
+  expect(calls.some(c => c[0] === "docker")).toBe(false);
+});
+
+test("filesystem pressure removes least recently used Docker images when BuildKit pruning frees nothing", async () => {
+  let used = 236 * GiB;
   const calls: string[][] = [];
   const run = async (command: string, args: string[]) => {
     calls.push([command, ...args]);
-    if (command === "docker" && args[1] === "ls") return "new\nold\n";
-    if (command === "docker" && args[1] === "inspect") return JSON.stringify([
-      { Id: "new", Created: "2026-09-29T10:00:00Z" }, { Id: "old", Created: "2026-09-28T10:00:00Z" }]);
     if (command === "docker" && args[1] === "rm") used -= 40 * GiB;
     return ""; // Model Harmony: BuildKit's own GC reports no reclaimable data.
   };
-  await collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: 256 * GiB - used }));
+  await collectStickyCache(config, retention([{ id: "new", lastUsed: now }, { id: "old", lastUsed: now - 1000 }]),
+    run, async () => ({ totalBytes: 256 * GiB, freeBytes: 256 * GiB - used }));
   expect(calls.filter(c => c[2] === "rm")).toEqual([["docker", "image", "rm", "-f", "old"]]);
   const prune = calls.find(c => c.includes("--free-storage"))!;
-  expect(prune[prune.indexOf("--keep-storage") + 1]).toBe(String(Math.floor(32 * GiB / 1e6)));
-  expect(prune[prune.indexOf("--free-storage") + 1]).toBe(String(Math.ceil(192 * GiB / 1e6)));
+  expect(prune.includes("--keep-storage")).toBe(false);
+  expect(prune[prune.indexOf("--free-storage") + 1]).toBe(String(Math.ceil(32 * GiB / 1e6)));
 });
 
-test("healthy cache keeps recent images and a cache that cannot shrink is not published", async () => {
+test("healthy cache keeps recently used images and a cache that cannot shrink is not published", async () => {
   const calls: string[][] = [];
   const run = async (command: string, args: string[]) => { calls.push([command, ...args]); return ""; };
-  await collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: 220 * GiB }));
+  await collectStickyCache(config, retention([{ id: "postgres-built-in-june", lastUsed: now }]),
+    run, async () => ({ totalBytes: 256 * GiB, freeBytes: 220 * GiB }));
   expect(calls.some(c => c[2] === "rm" || c[2] === "inspect")).toBe(false);
-  await expect(collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: 5 * GiB })))
-    .rejects.toThrow("cannot meet filesystem retention target");
+  expect(calls.some(c => c[0] === "docker" && c.includes("prune"))).toBe(false);
+  await expect(collectStickyCache(config, retention(), run, async () => ({ totalBytes: 256 * GiB, freeBytes: 5 * GiB })))
+    .rejects.toThrow("cannot reclaim required write headroom");
+});
+
+test("six-hour image expiry uses last observation and respects the boundary and image protection", async () => {
+  const removed: string[] = [];
+  const run = async (command: string, args: string[]) => {
+    if (command === "docker" && args[1] === "rm") removed.push(args.at(-1)!);
+    return "";
+  };
+  await collectStickyCache(config, retention([
+    { id: "unused-for-seven-hours", lastUsed: now - 7 * 3600_000 },
+    { id: "exactly-six-hours", lastUsed: now - 6 * 3600_000 },
+    { id: "used-five-hours-ago", lastUsed: now - 5 * 3600_000 },
+    { id: "used-today", lastUsed: now },
+    { id: "protected", lastUsed: 0 },
+  ], ["protected"]), run, async () => ({ totalBytes: 256 * GiB, freeBytes: 220 * GiB }));
+  expect(removed).toEqual(["unused-for-seven-hours"]);
+});
+
+test("publication removes expired images before pruning build records and gives cache mounts seven days", async () => {
+  const calls: string[][] = [];
+  const run = async (command: string, args: string[]) => { calls.push([command, ...args]); return ""; };
+  await collectStickyCache(config, retention([{ id: "superseded", lastUsed: now - 7 * 3600_000 }]),
+    run, async () => ({ totalBytes: 251 * GiB, freeBytes: 170 * GiB }));
+  expect(calls).toEqual([
+    ["docker", "image", "rm", "-f", "superseded"],
+    ["buildctl", "--addr", "tcp://127.0.0.1:1234", "prune", "--keep-duration", "6h", "--filter", "type!=exec.cachemount"],
+    ["buildctl", "--addr", "tcp://127.0.0.1:1234", "prune", "--keep-duration", "168h", "--filter", "type==exec.cachemount"],
+  ]);
+});
+
+test("pressure cannot evict the images used by the environment being published", async () => {
+  const removed: string[] = [];
+  const run = async (command: string, args: string[]) => {
+    if (command === "docker" && args[1] === "rm") removed.push(args.at(-1)!);
+    return "";
+  };
+  await expect(collectStickyCache(config, retention([
+    { id: "postgres", lastUsed: now },
+    { id: "unused", lastUsed: now - 1000 },
+  ], ["postgres"]), run, async () => ({ totalBytes: 256 * GiB, freeBytes: 20 * GiB })))
+    .rejects.toThrow("cannot reclaim required write headroom");
+  expect(removed).toEqual(["unused"]);
 });
 
 test("nested Kubernetes stores share the filesystem budget and are pruned before recent Docker images", async () => {
-  let used = 100 * GiB;
+  let used = 236 * GiB;
   const calls: string[][] = [];
   let evictions = 0;
   const run = async (command: string, args: string[]) => { calls.push([command, ...args]); return ""; };
-  await collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: 256 * GiB - used }), {
+  await collectStickyCache(config, retention(), run, async () => ({ totalBytes: 256 * GiB, freeBytes: 256 * GiB - used }), {
     protectedImages: new Set(), close: async () => {},
     pruneOldest: async () => { used -= 40 * GiB; evictions++; return true; },
   });
@@ -60,13 +146,11 @@ test("nested Kubernetes stores share the filesystem budget and are pruned before
 test("GC does not remove an image while it supplies the Kubernetes maintenance daemon", async () => {
   const removed: string[] = [];
   const run = async (command: string, args: string[]) => {
-    if (command === "docker" && args[1] === "ls") return "runtime\nold";
-    if (command === "docker" && args[1] === "inspect") return JSON.stringify([
-      { Id: "runtime", Created: "2020" }, { Id: "old", Created: "2021" }]);
     if (command === "docker" && args[1] === "rm") removed.push(args.at(-1)!);
     return "";
   };
-  await collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: (removed.length ? 220 : 150) * GiB }), {
+  await collectStickyCache(config, retention([{ id: "runtime", lastUsed: 0 }, { id: "old", lastUsed: now }]),
+    run, async () => ({ totalBytes: 256 * GiB, freeBytes: (removed.length ? 220 : 20) * GiB }), {
     protectedImages: new Set(["runtime"]), close: async () => {}, pruneOldest: async () => false,
   });
   expect(removed).toEqual(["old"]);

package/src/harness/sticky-consumer.ts

@@ -4,6 +4,7 @@ import { mkdir, readFile, statfs, writeFile } from "node:fs/promises";
 
 import { STICKY_RUNTIME } from "./sticky-paths.js";
 import { openKubernetesCacheMaintenance, type KubernetesCacheMaintenance } from "./sticky-kubernetes.js";
+import { recordStickyImageUse, type StickyImageRetention } from "./sticky-image-retention.js";
 
 export const STICKY_CAPABILITY = "sticky-disks-v1";
 export const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
@@ -12,8 +13,9 @@ export interface StickyConsumerConfig {
   path: string;
   capacityBytes: number;
   headroomBytes: number;
-  cacheTargetBytes: number;
-  buildkitTargetBytes: number;
+  /** Legacy controller fields, accepted for compatibility but not enforced. */
+  cacheTargetBytes?: number;
+  buildkitTargetBytes?: number;
   compatibility: string;
 }
 
@@ -38,16 +40,42 @@ export function validateStickyConfig(config: StickyConsumerConfig): void {
   if (config.path !== "/var/lib/spectest-sticky" || config.compatibility !== STICKY_COMPATIBILITY ||
       !Number.isSafeInteger(config.capacityBytes) || config.capacityBytes <= 0 ||
       !Number.isSafeInteger(config.headroomBytes) || config.headroomBytes < 16 * 1024 * 1024 ||
-      !Number.isSafeInteger(config.cacheTargetBytes) || config.cacheTargetBytes <= 0 ||
-      !Number.isSafeInteger(config.buildkitTargetBytes) || config.buildkitTargetBytes <= 0 ||
-      config.buildkitTargetBytes > config.cacheTargetBytes ||
-      config.cacheTargetBytes + config.headroomBytes >= config.capacityBytes) {
+      config.headroomBytes >= config.capacityBytes) {
     throw new Error("unsupported sticky consumer profile or budget");
   }
 }
 
+/** Explicit policy avoids BuildKit's default size caps (including its separate
+ * cache-mount/source cap). Use physical capacity as the nonbinding max: with
+ * only minFreeSpace, BuildKit 0.32.2 sets keepBytes == totalSize when healthy,
+ * and pruneOnce's strict '<' check can still evict a record on every GC pass.
+ * Actual filesystem capacity is smaller than the device due to metadata. */
+export function stickyBuildkitConfig(config: StickyConsumerConfig): string {
+  validateStickyConfig(config);
+  return `root = "${config.path}/buildkit"
+[grpc]
+  address = ["tcp://127.0.0.1:1234"]
+[worker.oci]
+  enabled = false
+[worker.containerd]
+  enabled = true
+  address = "/run/containerd/containerd.sock"
+  namespace = "moby"
+  snapshotter = "overlayfs"
+  gc = true
+[[worker.containerd.gcpolicy]]
+  all = true
+  maxUsedSpace = ${config.capacityBytes}
+  minFreeSpace = ${config.headroomBytes}
+`;
+}
+
 export async function initializeStickyConsumer(config: StickyConsumerConfig): Promise<void> {
   validateStickyConfig(config);
+  // Do not persist obsolete caps supplied by an older controller. Maintenance
+  // also ignores them when restoring a snapshot written by an older SDK.
+  config = { path: config.path, capacityBytes: config.capacityBytes,
+    headroomBytes: config.headroomBytes, compatibility: config.compatibility };
   await exec("mountpoint", ["-q", config.path]);
   // The base must have stopped these before its RAM was captured. Refuse an
   // unexpected writer rather than racing it for the standard daemon sockets.
@@ -73,21 +101,7 @@ disabled_plugins = ["io.containerd.grpc.v1.cri"]
   dockerConfig.features = { "containerd-snapshotter": true };
   dockerConfig["storage-driver"] = "overlayfs";
   await writeFile(`${STICKY_RUNTIME}/docker.json`, JSON.stringify(dockerConfig));
-  await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, `root = "${config.path}/buildkit"
-[grpc]
-  address = ["tcp://127.0.0.1:1234"]
-[worker.oci]
-  enabled = false
-[worker.containerd]
-  enabled = true
-  address = "/run/containerd/containerd.sock"
-  namespace = "moby"
-  snapshotter = "overlayfs"
-  gc = true
-  reservedSpace = "1GB"
-  maxUsedSpace = ${config.buildkitTargetBytes}
-  minFreeSpace = ${config.headroomBytes}
-`);
+  await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, stickyBuildkitConfig(config));
   const start = async (unit: string, program: string, args: string[]) => {
     await exec("systemd-run", ["--quiet", "--unit", unit, "-p", "TimeoutStopSec=30",
       // Pinned BuildKit 0.32.2 returns 1 after its normal first-SIGTERM
@@ -113,6 +127,7 @@ disabled_plugins = ["io.containerd.grpc.v1.cri"]
  */
 export async function collectStickyCache(
   config: StickyConsumerConfig,
+  retention: StickyImageRetention,
   run: typeof exec = exec,
   usage = async (): Promise<{ freeBytes: number; totalBytes: number }> => {
     const fs = await statfs(config.path);
@@ -122,17 +137,30 @@ export async function collectStickyCache(
 ): Promise<void> {
   validateStickyConfig(config);
   const buildctl = ["--addr", "tcp://127.0.0.1:1234", "prune"];
-  await run("buildctl", [...buildctl, "--keep-duration", "168h"], 120_000);
-  await run("docker", ["image", "prune", "-af", "--filter", "until=168h"], 120_000);
-  const withinTarget = (fs: { freeBytes: number; totalBytes: number }) =>
-    fs.freeBytes >= config.headroomBytes && fs.totalBytes - fs.freeBytes <= config.cacheTargetBytes;
+  // Docker 29's containerd until filter uses local image-record creation;
+  // inspect's Created uses the publisher's build date. Neither tracks use.
+  // Never prune a just-used image merely because either timestamp is old.
+  const protectedImage = (id: string) => retention.protectedImages.has(id) || kubernetes?.protectedImages.has(id);
+  const images = [...retention.images].sort((a, b) => a.lastUsed - b.lastUsed || a.id.localeCompare(b.id));
+  const expired = new Set<string>();
+  for (const image of images) {
+    if (protectedImage(image.id) || image.lastUsed >= retention.observedAt - 6 * 60 * 60 * 1000) continue;
+    await run("docker", ["image", "rm", "-f", image.id], 120_000);
+    expired.add(image.id);
+  }
+  // Drop expired image references first so they no longer pin obsolete build
+  // layers. Cache mounts need a longer window: a cached RUN skips mounting
+  // its package cache, even though a later dependency change will need it.
+  await run("buildctl", [...buildctl, "--keep-duration", "6h", "--filter", "type!=exec.cachemount"], 120_000);
+  await run("buildctl", [...buildctl, "--keep-duration", "168h", "--filter", "type==exec.cachemount"], 120_000);
+  const withinTarget = (fs: { freeBytes: number }) => fs.freeBytes >= config.headroomBytes;
   let fs = await usage();
-  // Always enforce the independent BuildKit target. Its accounting alone
-  // cannot bound shared images/content, so also request real filesystem space.
+  if (withinTarget(fs)) return;
+  // All consumers share this filesystem. Reclaim only the missing headroom;
+  // a per-consumer cap evicts useful cache even when the disk is mostly empty.
   const pruneBuildkit = async () => {
-    await run("buildctl", [...buildctl, "--all", "--keep-storage",
-      String(Math.floor(config.buildkitTargetBytes / 1e6)), "--free-storage",
-      String(Math.ceil(Math.max(config.headroomBytes, fs.totalBytes - config.cacheTargetBytes) / 1e6))], 120_000);
+    await run("buildctl", [...buildctl, "--all", "--free-storage",
+      String(Math.ceil(config.headroomBytes / 1e6))], 120_000);
     fs = await usage();
   };
   await pruneBuildkit();
@@ -141,21 +169,19 @@ export async function collectStickyCache(
     fs = await usage();
     if (withinTarget(fs)) return;
   }
-  // Pressure can be entirely in recent Docker images. Drop oldest images
-  // first, even within the age window, until the whole filesystem fits.
-  const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"])).split(/\s+/).filter(Boolean))];
-  const images: { Id: string; Created: string }[] = ids.length
-    ? JSON.parse(await run("docker", ["image", "inspect", ...ids])) : [];
-  images.sort((a, b) => a.Created.localeCompare(b.Created) || a.Id.localeCompare(b.Id));
+  // Under pressure, evict least recently used images, including within the
+  // age window, but preserve this environment's images for the next build.
   for (const image of images) {
-    if (kubernetes?.protectedImages.has(image.Id)) continue;
-    await run("docker", ["image", "rm", "-f", image.Id], 120_000);
+    if (expired.has(image.id) || protectedImage(image.id)) continue;
+    await run("docker", ["image", "rm", "-f", image.id], 120_000);
+    fs = await usage();
+    if (withinTarget(fs)) return;
     await pruneBuildkit();
     if (withinTarget(fs)) return;
   }
   // Containerd GC may lag reference removal; allow bounded additional passes.
   for (let pass = 0; pass < 3 && !withinTarget(fs); pass++) await pruneBuildkit();
-  if (!withinTarget(fs)) throw new Error("sticky cache cannot meet filesystem retention target and write headroom");
+  if (!withinTarget(fs)) throw new Error("sticky cache cannot reclaim required write headroom");
 }
 
 /** Only on an isolated maintenance clone; never on the live ready environment. */
@@ -163,12 +189,13 @@ export async function prepareStickyConsumer(artifact = false): Promise<{ prepare
   const config: StickyConsumerConfig = JSON.parse(await readFile(`${STICKY_RUNTIME}/consumer.json`, "utf8"));
   validateStickyConfig(config);
   if (!artifact) {
-    const containers = (await exec("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+    const retention = await recordStickyImageUse(config.path, exec);
+    const { containers } = retention;
     if (containers.length) await exec("docker", ["rm", "-f", ...containers]);
     const volumes = (await exec("docker", ["volume", "ls", "-q"])).split(/\s+/).filter(Boolean);
     if (volumes.length) await exec("docker", ["volume", "rm", ...volumes]);
     const kubernetes = await openKubernetesCacheMaintenance(exec);
-    try { await collectStickyCache(config, exec, undefined, kubernetes); }
+    try { await collectStickyCache(config, retention, exec, undefined, kubernetes); }
     finally { await kubernetes.close(); }
   }
   const units = ["spectest-sticky-buildkit", "spectest-sticky-docker", "spectest-sticky-containerd"];

package/src/harness/sticky-image-retention.test.ts

@@ -0,0 +1,59 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { recordStickyImageUse } from "./sticky-image-retention";
+import { collectStickyCache, STICKY_COMPATIBILITY } from "./sticky-consumer";
+
+test("publication records container use before removal and carries it into the next generation", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-image-use-"));
+  try {
+    const now = Date.UTC(2026, 9, 13), GiB = 1024 ** 3;
+    const path = `${root}/.spectest-image-use.json`;
+    await writeFile(path, JSON.stringify({ schema: 1, images: {
+      postgres: now - 10 * 86400_000, unused: now - 9 * 86400_000, gone: now,
+    } }));
+    let containers = true;
+    const calls: string[][] = [];
+    const run = async (command: string, args: string[]) => {
+      calls.push([command, ...args]);
+      if (command === "docker" && args[0] === "image" && args[1] === "ls") return "postgres\nnew\nunused\npostgres";
+      if (command === "docker" && args[0] === "ps") return containers ? "db-container" : "";
+      if (command === "docker" && args[0] === "container" && args[1] === "inspect") return "postgres";
+      return "";
+    };
+    const first = await recordStickyImageUse(root, run, now);
+    expect(first.containers).toEqual(["db-container"]);
+    expect(first.protectedImages).toEqual(new Set(["postgres"]));
+    expect(JSON.parse(await readFile(path, "utf8"))).toEqual({ schema: 1,
+      images: { postgres: now, new: now, unused: now - 9 * 86400_000 } });
+    containers = false; // Publication removes the containers after recording use.
+    await collectStickyCache({ path: "/var/lib/spectest-sticky", capacityBytes: 256 * GiB,
+      headroomBytes: 32 * GiB,
+      compatibility: STICKY_COMPATIBILITY }, first, run,
+    async () => ({ totalBytes: 256 * GiB, freeBytes: 200 * GiB }));
+    expect(calls.filter(c => c[0] === "docker" && c[2] === "rm"))
+      .toEqual([["docker", "image", "rm", "-f", "unused"]]);
+    expect(calls.some(c => c.includes("until=168h"))).toBe(false);
+    const next = await recordStickyImageUse(root, run, now + 86400_000);
+    expect(next.images.find(image => image.id === "postgres")?.lastUsed).toBe(now);
+    expect(next.protectedImages.size).toBe(0);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("legacy generations give unknown images a first observation instead of inferring publisher age", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-image-use-"));
+  try {
+    const state = await recordStickyImageUse(root, async (_, args) => args[1] === "ls" ? "old-published-image" : "", 1234);
+    expect(state.images).toEqual([{ id: "old-published-image", lastUsed: 1234 }]);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test("invalid image-use history fails publication rather than treating every image as expired", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-image-use-"));
+  try {
+    await writeFile(`${root}/.spectest-image-use.json`, JSON.stringify({ schema: 1, images: { postgres: "yesterday" } }));
+    await expect(recordStickyImageUse(root, async () => { throw new Error("must not reach Docker"); }))
+      .rejects.toThrow("invalid sticky image-use ledger");
+  } finally { await rm(root, { recursive: true, force: true }); }
+});

package/src/harness/sticky-image-retention.ts

@@ -0,0 +1,43 @@
+/** Image use belongs to the cache lineage, not the publisher's image clock. */
+import { randomUUID } from "node:crypto";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import type { CacheCommand } from "./sticky-kubernetes.js";
+
+export interface StickyImageRetention {
+  images: { id: string; lastUsed: number }[];
+  protectedImages: Set<string>;
+  containers: string[];
+  observedAt: number;
+}
+
+/** Call before removing containers from the isolated publication clone.
+ * New/legacy images get a first observation; inherited unused images retain
+ * their previous timestamp. Rewriting from the inventory drops stale IDs.
+ */
+export async function recordStickyImageUse(
+  root: string, run: CacheCommand, now = Date.now(),
+): Promise<StickyImageRetention> {
+  const path = `${root}/.spectest-image-use.json`;
+  const saved = await readFile(path, "utf8").catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  });
+  const previous = saved === undefined ? { schema: 1, images: {} } : JSON.parse(saved);
+  if (previous.schema !== 1 || !previous.images || typeof previous.images !== "object" ||
+      Array.isArray(previous.images) || Object.values(previous.images).some(value =>
+        typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) {
+    throw new Error("invalid sticky image-use ledger");
+  }
+  const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"]))
+    .split(/\s+/).filter(Boolean))];
+  const containers = (await run("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+  const protectedImages = new Set(containers.length
+    ? (await run("docker", ["container", "inspect", "--format", "{{.Image}}", ...containers]))
+      .split(/\s+/).filter(Boolean) : []);
+  const images = ids.map(id => ({ id, lastUsed: protectedImages.has(id) ? now : previous.images[id] ?? now }));
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify({ schema: 1,
+    images: Object.fromEntries(images.map(({ id, lastUsed }) => [id, lastUsed])) }));
+  await rename(temporary, path);
+  return { images, protectedImages, containers, observedAt: now };
+}