@specific.dev/spectest 0.115.1 → 0.116.1

package/src/harness/live-fake.test.ts

@@ -0,0 +1,227 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const moduleUrl = (file: string) => JSON.stringify(new URL(file, import.meta.url).href);
+
+// Isolate DNS/transport mocks, platform secrets and recorder globals. All egress
+// goes to a local stub; no real provider or credential is needed.
+test("whole-fake live HTTP uses the environment gate, brokers secrets and never captures", async () => {
+  const root = await mkdtemp(join(tmpdir(), "spectest-live-http-"));
+  try {
+    await mkdir(join(root, "spectest"));
+    await writeFile(join(root, "spectest/index.ts"), `
+      import { defineEnvironment, defineFake } from ${moduleUrl("../index.ts")};
+      export default defineEnvironment({ name: "live", services: {}, fakes: {
+        live: defineFake({ name: "live", hostnames: ["api.test"], handler: () => new Response(),
+          live: { inject: [{ headers: { authorization: "Bearer {{secret:TOKEN}}" } }],
+            sign: { type: "awsSigv4", accessKeyId: "ID", secretAccessKey: "KEY", sessionToken: "SESSION" } },
+          secretRefs: ["LEGACY", "TOKEN"],
+        }),
+      } }).project({});
+    `);
+    const script = `
+      import { strict as assert } from "node:assert";
+      import { EventEmitter } from "node:events";
+      import { test, mock } from "bun:test";
+      import * as dnsPacket from ${JSON.stringify(import.meta.resolve("dns-packet"))};
+      test("live HTTP", async () => {
+        let dns = 0, requests = [];
+        mock.module("node:dgram", () => ({ createSocket() {
+          dns++;
+          const socket = new EventEmitter(); socket.close = () => {};
+          socket.send = (query, _port, _host, done) => { done(); queueMicrotask(() => socket.emit("message", dnsPacket.encode({
+            type: "response", id: 1, answers: [{ type: "A", name: dnsPacket.decode(query).questions[0].name, ttl: 60, data: "127.0.0.1" }],
+          }))); }; return socket;
+        } }));
+        mock.module("node:https", () => ({ request(options, callback) {
+          requests.push(options);
+          const req = new EventEmitter(); let body = Buffer.alloc(0);
+          req.write = chunk => { body = Buffer.concat([body, chunk]); };
+          req.end = () => queueMicrotask(() => {
+            if (options.path === "/broken") { req.emit("error", new Error("upstream unavailable")); return; }
+            const res = new EventEmitter(); res.statusCode = options.path === "/empty" ? 204 : options.path === "/denied" ? 401 : 200;
+            res.headers = { "content-type": "application/octet-stream", "set-cookie": ["session=real; Path=/", "other=value; Expires=Wed, 21 Oct 2037 07:28:00 GMT"], "content-length": "999" };
+            callback(res); res.emit("data", body.length ? body : Buffer.from("real transcript")); res.emit("end");
+          }); return req;
+        } }));
+        const { defineFake } = await import(${moduleUrl("../index.ts")});
+        const { METHODS } = await import(${moduleUrl("../daemon.ts")});
+        const { dispatchFake } = await import(${moduleUrl("./fake-websocket.ts")});
+        const { setReplayEnvironmentMode } = await import(${moduleUrl("../replay-mode.ts")});
+        const { setRecordSecrets } = await import(${moduleUrl("../record-secrets.ts")});
+        const { startRecording, stopRecording, pauseRecording, resumeRecording } = await import(${moduleUrl("../recorder.ts")});
+        await METHODS.load({});
+        assert.deepEqual((await METHODS.recordSecretRefs({})).refs.sort(), ["ID", "KEY", "LEGACY", "SESSION", "TOKEN"]);
+        const state = { calls: 0 };
+        const def = defineFake({ name: "speech", hostnames: ["api.test", "speech.test"],
+          handler: () => { state.calls++; return new Response("scripted"); },
+          websocket: () => { state.calls++; return new Response("scripted websocket", { status: 403 }); },
+          helpers: () => ({ count: () => state.calls }),
+          live: { inject: [{ headers: { authorization: "Bearer {{secret:TOKEN}}" } }] },
+        });
+        const helpers = def.helpers({ name: def.name, state, ctx: {} });
+        const call = (host = "api.test", path = "/transcribe", options = {}) => dispatchFake(new Request("https://" + host + path, options), {}, def, state, {});
+        setRecordSecrets({ TOKEN: "real-key" });
+        async function checkScripted() {
+          assert.equal(await (await call()).text(), "scripted");
+          assert.equal((await call("speech.test", "/socket", { headers: { upgrade: "websocket" } })).status, 403);
+          assert.equal(dns, 0); assert.equal(requests.length, 0);
+        }
+        await checkScripted(); // baseline startup
+        startRecording(); await checkScripted(); pauseRecording(); await checkScripted();
+        resumeRecording(); stopRecording(); await checkScripted(); // between tests
+        setReplayEnvironmentMode("interactive");
+        const calls = helpers.count();
+        startRecording();
+        for (const host of def.hostnames) {
+          const response = await call(host, "/transcribe?lang=sv&word=a%20b", {
+            method: "POST", body: new Uint8Array([0, 128, 255]), headers: { authorization: "Bearer dummy" },
+          });
+          assert.deepEqual(new Uint8Array(await response.arrayBuffer()), new Uint8Array([0, 128, 255]));
+          assert.deepEqual(response.headers.getSetCookie(), ["session=real; Path=/", "other=value; Expires=Wed, 21 Oct 2037 07:28:00 GMT"]);
+          assert.equal(response.headers.get("content-length"), null);
+          const sent = requests.at(-1);
+          assert.equal(sent.host, "127.0.0.1"); assert.equal(sent.servername, host);
+          assert.equal(sent.headers.host, host); assert.equal(sent.headers.authorization, "Bearer real-key");
+          assert.equal(sent.path, "/transcribe?lang=sv&word=a%20b"); assert.equal(sent.method, "POST");
+        }
+        assert.equal(await (await call()).text(), "real transcript");
+        assert.deepEqual(stopRecording(), []);
+        const compressed = new Uint8Array([31, 139, 8, 0]);
+        await call("api.test", "/compressed", { method: "POST", body: compressed, headers: { "content-encoding": "gzip" } });
+        assert.equal(requests.at(-1).headers["content-encoding"], "gzip");
+        assert.equal(helpers.count(), calls);
+        assert.equal((await call("api.test", "/empty")).status, 204);
+        assert.equal((await call("api.test", "/denied")).status, 401);
+        assert.equal((await call("api.test", "/broken")).status, 599);
+        assert.equal(await (await call("api.test", "/transcribe", { method: "HEAD" })).text(), "");
+        let before = dns;
+        assert.equal((await call("outside.test")).status, 500); assert.equal(dns, before);
+        setRecordSecrets({});
+        assert.equal((await call()).status, 599); assert.equal(dns, before);
+        // Missing credentials never change routing or fall back to the fake.
+        assert.equal(helpers.count(), calls);
+        def.live = {};
+        assert.equal(await (await call()).text(), "real transcript");
+        def.live = { sign: { type: "awsSigv4", accessKeyId: "ID", secretAccessKey: "KEY" } };
+        def.hostnames = ["s3.eu-north-1.amazonaws.com"];
+        setRecordSecrets({ ID: "real-id", KEY: "real-signing-key" });
+        await call(def.hostnames[0]);
+        assert.ok(requests.at(-1).headers.authorization.startsWith("AWS4-HMAC-SHA256 Credential=real-id/"));
+        delete def.live;
+        before = dns; assert.equal(await (await call()).text(), "scripted"); assert.equal(dns, before);
+        def.live = {};
+        setReplayEnvironmentMode("test");
+        before = dns; await call(); assert.equal(dns, before);
+      });
+    `;
+    const file = join(root, "http.test.ts"); await writeFile(file, script);
+    const child = Bun.spawn([process.execPath, "test", file], {
+      env: { ...process.env, SPECTEST_APP_DIR: root }, stdout: "pipe", stderr: "pipe",
+    });
+    const [exit, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+    expect(exit, stdout + stderr).toBe(0);
+  } finally { await rm(root, { recursive: true, force: true }); }
+}, 20_000);
+
+// Real TLS and ingress sockets. Only DNS and the upstream port are redirected.
+test("live WSS forwards binary/text without recording and cleans up both sides", async () => {
+  const root = await mkdtemp(join(tmpdir(), "spectest-live-ws-"));
+  try {
+    const key = join(root, "key.pem"), cert = join(root, "cert.pem");
+    execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", key, "-out", cert,
+      "-days", "1", "-subj", "/CN=speech.test", "-addext", "subjectAltName=DNS:speech.test,DNS:api.test"], { stdio: "ignore" });
+    const script = `
+      import { test, mock } from "bun:test";
+      import { strict as assert } from "node:assert";
+      import { EventEmitter, once } from "node:events";
+      import { createServer } from "node:https";
+      import { readFileSync } from "node:fs";
+      import * as dnsPacket from ${JSON.stringify(import.meta.resolve("dns-packet"))};
+      import WS from ${JSON.stringify(import.meta.resolve("ws").replace(/wrapper\.mjs$/, "index.js"))};
+      test("live WSS", async () => {
+        mock.module("node:dgram", () => ({ createSocket() {
+          const socket = new EventEmitter(); socket.close = () => {};
+          socket.send = (_query, _port, _host, done) => { done(); queueMicrotask(() => socket.emit("message", dnsPacket.encode({
+            type: "response", id: 1, answers: [{ type: "A", name: "speech.test", ttl: 60, data: "127.0.0.1" }],
+          }))); }; return socket;
+        } }));
+        const upstream = createServer({ key: readFileSync(${JSON.stringify(key)}), cert: readFileSync(${JSON.stringify(cert)}) });
+        const wss = new WS.WebSocketServer({ server: upstream, handleProtocols: () => "voice" });
+        upstream.listen(0, "127.0.0.1"); await once(upstream, "listening");
+        const { forwardWebSocket } = await import(${moduleUrl("../fake-upstream-websocket.ts")});
+        mock.module(${moduleUrl("../fake-upstream-websocket.ts")}, () => ({ forwardWebSocket(args) {
+          assert.equal(args.observe, undefined); // no recorder, matcher or capture callback
+          assert.equal(args.url, "wss://" + args.host + "/live?lang=sv");
+          const url = new URL(args.url); url.port = String(upstream.address().port);
+          return forwardWebSocket({ ...args, url: url.href });
+        } }));
+        const { defineFake } = await import(${moduleUrl("../index.ts")});
+        const { setReplayEnvironmentMode } = await import(${moduleUrl("../replay-mode.ts")});
+        const { setRecordSecrets } = await import(${moduleUrl("../record-secrets.ts")});
+        const { startRecording, stopRecording } = await import(${moduleUrl("../recorder.ts")});
+        const { startIngressServer } = await import(${moduleUrl("./ingress-server.ts")});
+        const { dispatchFake } = await import(${moduleUrl("./fake-websocket.ts")});
+        setReplayEnvironmentMode("interactive"); setRecordSecrets({ TOKEN: "real-key" });
+        const state = { calls: 0 };
+        // Deliberately no scripted WebSocket handler: live routing still upgrades.
+        const def = defineFake({ name: "speech", hostnames: ["api.test", "speech.test"],
+          handler: () => { state.calls++; return new Response("scripted"); },
+          live: { inject: [{ headers: { authorization: "Bearer {{secret:TOKEN}}" } }] },
+        });
+        const ingress = await startIngressServer({ port: 0, hostname: "127.0.0.1", fetch: (req, server) => dispatchFake(req, server, def, state, {}) });
+        let connections = 0;
+        wss.on("connection", (socket, req) => {
+          connections++; assert.equal(req.headers.authorization, "Bearer real-key");
+          assert.equal(req.url, "/live?lang=sv");
+          socket.send("real transcript");
+          socket.on("message", (data, binary) => {
+            if (!binary && data.toString() === "finish") socket.close(4003, "provider done");
+            else socket.send(data, { binary });
+          });
+        });
+        try {
+          startRecording();
+          for (const host of def.hostnames) {
+            const client = new WS("ws://127.0.0.1:" + ingress.port + "/live?lang=sv", ["voice"], {
+              headers: { host, authorization: "Bearer dummy" },
+            });
+            const received = []; client.on("message", (data, binary) => received.push({ data: Buffer.from(data), binary }));
+            await once(client, "open"); assert.equal(client.protocol, "voice");
+            client.send('{"model":"test"}'); client.send(new Uint8Array([0, 128, 255]));
+            for (let i = 0; received.length < 3 && i < 200; i++) await Bun.sleep(5);
+            assert.deepEqual(received, [
+              { data: Buffer.from("real transcript"), binary: false },
+              { data: Buffer.from('{"model":"test"}'), binary: false },
+              { data: Buffer.from([0, 128, 255]), binary: true },
+            ]);
+            const closed = once(client, "close");
+            if (host === "api.test") client.close(4002, "client done"); else client.send("finish");
+            const [code, reason] = await closed;
+            assert.equal(code, host === "api.test" ? 4002 : 4003);
+            assert.equal(reason.toString(), host === "api.test" ? "client done" : "provider done");
+          }
+          assert.equal(connections, 2); assert.equal(state.calls, 0);
+          assert.deepEqual(stopRecording(), []);
+          for (let i = 0; wss.clients.size && i < 100; i++) await Bun.sleep(5);
+          assert.equal(wss.clients.size, 0);
+          setRecordSecrets({});
+          const response = await dispatchFake(new Request("https://speech.test/live", { headers: { upgrade: "websocket" } }), {}, def, state, {});
+          assert.equal(response.status, 500); assert.equal(connections, 2); assert.equal(state.calls, 0);
+          def.live.sign = { type: "awsSigv4", accessKeyId: "ID", secretAccessKey: "KEY" };
+          const signed = await dispatchFake(new Request("https://speech.test/live", { headers: { upgrade: "websocket" } }), {}, def, state, {});
+          assert.match(await signed.text(), /SigV4 WebSocket signing is not supported/);
+        } finally {
+          ingress.stop(true); for (const socket of wss.clients) socket.terminate(); wss.close(); upstream.close();
+        }
+      });
+    `;
+    const file = join(root, "ws.test.ts"); await writeFile(file, script);
+    const child = Bun.spawn([process.execPath, "test", file], { env: { ...process.env, NODE_EXTRA_CA_CERTS: cert }, stdout: "pipe", stderr: "pipe" });
+    const [exit, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+    expect(exit, stdout + stderr).toBe(0);
+  } finally { await rm(root, { recursive: true, force: true }); }
+}, 20_000);

package/src/harness/live-fake.ts

@@ -0,0 +1,62 @@
+import type { FakeDefinition } from "../index.js";
+import {
+  brokerHeaders, forwardHttp, resolveExternalA, ruleMatches, STRIP_FORWARD_HEADERS,
+} from "../fake-upstream.js";
+import { forwardWebSocket } from "../fake-upstream-websocket.js";
+import { getWebSocketLifetime } from "./fake-websocket-lifetime.js";
+import { reportBackgroundFailure } from "./background-failures.js";
+import { isInteractiveEnvironment } from "../replay-mode.js";
+
+/** Select at request time, after the baseline has become interactive. */
+export function liveFakeHandlers(def: FakeDefinition): Pick<FakeDefinition, "handler" | "websocket"> {
+  function target(req: Request): string {
+    if (!isInteractiveEnvironment()) throw new Error("live forwarding requires an interactive environment");
+    const url = new URL(req.url);
+    if (!def.hostnames.some(host => host.toLowerCase() === url.hostname.toLowerCase())) {
+      throw new Error(`fake ${def.name}: upstream hostname is not declared on this fake`);
+    }
+    return url.hostname;
+  }
+
+  return {
+    async handler(req) {
+      const host = target(req);
+      const bytes = new Uint8Array(await req.arrayBuffer());
+      const result = await forwardHttp(req, host, def.live!, bytes, `fake(${def.name})`);
+      if (result instanceof Response) return result;
+      const { upstream } = result;
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(upstream.headers)) {
+        if (key !== "set-cookie" && !STRIP_FORWARD_HEADERS.has(key)) headers.set(key, value);
+      }
+      for (const cookie of upstream.cookies ?? []) headers.append("set-cookie", cookie);
+      return new Response(req.method === "HEAD" || [204, 205, 304].includes(upstream.status)
+        ? null : upstream.bytes as unknown as BodyInit, { status: upstream.status, headers });
+    },
+    async websocket(req) {
+      const host = target(req);
+      const opts = def.live!;
+      if (opts.sign) throw new Error(`fake(${def.name}): SigV4 WebSocket signing is not supported`);
+      const url = new URL(req.url);
+      const rule = opts.inject?.find(rule => ruleMatches(rule.match, {
+        method: req.method, path: url.pathname, query: url.searchParams, headers: req.headers,
+      }));
+      const brokered = rule ? brokerHeaders(rule) : { headers: {}, missing: [] };
+      if (brokered.missing.length) throw new Error(`fake(${def.name}): missing WebSocket secrets ${brokered.missing.join(", ")}`);
+      const ips = await resolveExternalA(host);
+      if (!ips.length) throw new Error(`fake(${def.name}): could not resolve real upstream ${host}`);
+      const headers: Record<string, string> = {};
+      req.headers.forEach((value, key) => {
+        if (!STRIP_FORWARD_HEADERS.has(key) && !key.startsWith("sec-websocket-")) headers[key] = value;
+      });
+      Object.assign(headers, brokered.headers);
+      const { handlers } = await forwardWebSocket({
+        url: `wss://${host}${url.pathname}${url.search}`, ip: ips[0], host, headers,
+        protocols: (req.headers.get("sec-websocket-protocol") ?? "").split(",").map(p => p.trim()).filter(Boolean),
+        label: `fake(${def.name}) WebSocket`, lifetime: getWebSocketLifetime(req),
+        finished(_session, error) { if (error) reportBackgroundFailure(error); },
+      });
+      return handlers;
+    },
+  };
+}

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

@@ -1,55 +1,127 @@
 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("seven-day expiry uses our last observation and respects 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-eight-days", lastUsed: now - 8 * 86400_000 },
+    { id: "used-today", lastUsed: now },
+    { id: "protected", lastUsed: 0 },
+  ], ["protected"]), run, async () => ({ totalBytes: 256 * GiB, freeBytes: 220 * GiB }));
+  expect(removed).toEqual(["unused-for-eight-days"]);
+});
+
+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 +132,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);
@@ -123,16 +138,24 @@ export async function collectStickyCache(
   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's until filter and Created field refer to the publisher's build
+  // date, not our use. Never prune a just-used image merely because it 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 - 7 * 24 * 60 * 60 * 1000) continue;
+    await run("docker", ["image", "rm", "-f", image.id], 120_000);
+    expired.add(image.id);
+  }
+  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 +164,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 +184,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"];