@specific.dev/spectest 0.89.0 → 0.90.0

package/src/daemon.ts

@@ -1,3 +1,4 @@
+import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp, type AndroidRecording } from "./android.js";
 // Long-running HTTP daemon. Runs as a systemd unit on the VM host (not in
 // a container). Owns:
 //
@@ -124,6 +125,13 @@ import {
   corsPreflightResponse,
   isCorsPreflight,
 } from "./harness/http-proxy.js";
+import {
+  WS_BRIDGE_HANDLERS,
+  openUpstreamWebSocket,
+  parseSubprotocols,
+  upstreamHandshakeHeaders,
+  type WsBridgeData,
+} from "./harness/ws-bridge.js";
 import {
   certCovers as hostmatchCertCovers,
   hostWithoutPort,
@@ -768,6 +776,11 @@ function ensureLocalBuildkitd(): Promise<boolean> {
 }
 
 async function bringUpLocalBuildkitd(): Promise<boolean> {
+  if (existsSync("/run/spectest-sticky/consumer.json")) {
+    const ready = await docker(["buildx", "inspect", "--bootstrap", LOCAL_BUILDER_NAME], 30_000);
+    if (ready.code !== 0) throw new Error(`sticky BuildKit unavailable: ${ready.stderr}`);
+    return true;
+  }
   const paths = await imageCachePaths();
   if (!paths) return false;
   const state = paths.root;
@@ -2112,14 +2125,6 @@ async function bridgeGatewayIp(): Promise<string> {
  *  The shape is `harness/ingress-table.ts`'s, generic over that record. */
 type Route = IngressRoute<FakeRuntime>;
 
-/** Per-WS-upgrade context: the upstream URL we'll open in `open()` and
- * keep the bridge in `message()`/`close()`. Stored on `ws.data`. */
-interface WsBridgeData {
-  upstreamUrl: string;
-  upstream: WebSocket | null;
-  pending: Array<string | ArrayBuffer | Uint8Array>;
-}
-
 /**
  * Pristine `fetch` captured at module load, before any test-scoped
  * fetch wrapper can monkey-patch `globalThis.fetch`. The reverse-proxy
@@ -2440,8 +2445,8 @@ async function unbindRuntimeTls(hostname: string): Promise<void> {
  * Spin up one Bun.serve listener bound to (port, optional TLS) that
  * dispatches every request to the matching Route by Host header.
  *
- * Shared by the HTTP and HTTPS branches. Also exports a `websocket`
- * handler so reverse-proxy targets can transparently bridge WS
+ * Shared by the HTTP and HTTPS branches. Also carries the `websocket`
+ * handler set so reverse-proxy targets can transparently bridge WS
  * upgrades through to their upstream service.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -2485,74 +2490,9 @@ function bindIngressServer(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     fetch: (req: Request, server: any): Response | Promise<Response> =>
       dispatchIngress(req, server, byHost, listenerLabel, proto),
-    websocket: {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      async open(ws: any) {
-        const data = ws.data as WsBridgeData;
-        try {
-          const upstream = new WebSocket(data.upstreamUrl);
-          // ArrayBuffer so binary frames can be ws.send()'d to the
-          // downstream client verbatim — Blob would need an extra
-          // .arrayBuffer() round-trip on every message.
-          upstream.binaryType = "arraybuffer";
-          data.upstream = upstream;
-          upstream.addEventListener("open", () => {
-            for (const m of data.pending) upstream.send(m);
-            data.pending = [];
-          });
-          upstream.addEventListener("message", (ev: MessageEvent) => {
-            try {
-              ws.send(ev.data);
-            } catch {
-              /* client gone */
-            }
-          });
-          upstream.addEventListener("close", (ev: CloseEvent) => {
-            try {
-              ws.close(ev.code, ev.reason);
-            } catch {
-              /* already closed */
-            }
-          });
-          upstream.addEventListener("error", () => {
-            try {
-              ws.close(1011, "upstream error");
-            } catch {
-              /* already closed */
-            }
-          });
-        } catch (err) {
-          // eslint-disable-next-line no-console
-          console.warn(`[ingress] ws upstream open failed for ${data.upstreamUrl}:`, err);
-          try {
-            ws.close(1011, "upstream open failed");
-          } catch {
-            /* ignore */
-          }
-        }
-      },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      message(ws: any, message: string | Buffer) {
-        const data = ws.data as WsBridgeData;
-        const payload =
-          typeof message === "string" ? message : new Uint8Array(message);
-        if (data.upstream && data.upstream.readyState === WebSocket.OPEN) {
-          data.upstream.send(payload);
-        } else {
-          // Buffer until the upstream finishes its handshake.
-          data.pending.push(payload);
-        }
-      },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      close(ws: any, code: number, reason: string) {
-        const data = ws.data as WsBridgeData;
-        try {
-          data.upstream?.close(code, reason);
-        } catch {
-          /* ignore */
-        }
-      },
-    },
+    // The frame relay for bridged WebSocket upgrades; `proxyToService`
+    // opens the upstream before it upgrades the client (harness/ws-bridge.ts).
+    websocket: WS_BRIDGE_HANDLERS,
   };
   return Bun.serve(opts);
 }
@@ -2657,8 +2597,12 @@ function ingressClientIp(server: any, req: Request, proto: string): string | und
  * Reverse-proxy a request to `http://<service>:<port>` on
  * `spectest-net`. Handles plain HTTP/1.1 + 2 and WebSocket upgrades:
  *
- *   - WS upgrade requests get routed through `server.upgrade()`, with
- *     the upstream URL stashed on `ws.data`. The shared `websocket`
+ *   - WS upgrade requests open the upstream WebSocket first, with the
+ *     client's full `Sec-WebSocket-Protocol` list and its forwardable
+ *     headers (cookies, authorization, origin, x-forwarded-*). Only after
+ *     that handshake succeeds is the client upgraded, with the protocol
+ *     the upstream selected; a refused upstream handshake is a 502, not a
+ *     101 followed by a close. The open upstream rides on `ws.data`; the shared `websocket`
  *     handler opens the upstream and bridges frames both ways.
  *   - Plain requests pass through via `fetch()` with hop-by-hop
  *     headers stripped; the response body is a ReadableStream returned
@@ -2688,16 +2632,40 @@ async function proxyToService(
   const upgrade = req.headers.get("upgrade")?.toLowerCase() ?? "";
   if (upgrade === "websocket") {
     const upstreamUrl = `ws://${await proxyUpstreamHost(service)}:${port}${upstreamPath}`;
-    const wsData: WsBridgeData = {
-      upstreamUrl,
-      upstream: null,
-      pending: [],
-    };
-    const ok = server.upgrade(req, { data: wsData });
+    // The upstream handshake carries what the client's did: the whole
+    // subprotocol list (a console ticket often rides as the second entry)
+    // and the forwardable headers. Same provenance stamps as the HTTP path.
+    const protocols = parseSubprotocols(req.headers.get("sec-websocket-protocol"));
+    const headers = upstreamHandshakeHeaders(req.headers, {
+      service,
+      port,
+      proto,
+      clientIp: ingressClientIp(server, req, proto),
+    });
+    const opened = await openUpstreamWebSocket(upstreamUrl, { protocols, headers });
+    if (!opened.ok) {
+      return new Response(
+        `spectest-daemon: ${opened.reason} (${upstreamUrl}) on ${listenerLabel}\n`,
+        { status: 502, headers: { "content-type": "text/plain" } },
+      );
+    }
+    const wsData: WsBridgeData = { upstreamUrl, upstream: opened.socket };
+    // Echo the protocol the upstream selected; Bun would otherwise pick
+    // the client's first entry by itself, which can differ.
+    const selected = opened.socket.protocol;
+    const ok = server.upgrade(req, {
+      data: wsData,
+      headers: selected ? { "sec-websocket-protocol": selected } : undefined,
+    });
     if (ok) {
       // Bun has already taken over the response — return a stub.
       return new Response(null, { status: 101 });
     }
+    try {
+      opened.socket.close(1011, "client upgrade refused");
+    } catch {
+      /* ignore */
+    }
     return new Response(
       `spectest-daemon: ws upgrade refused on ${listenerLabel}\n`,
       { status: 426, headers: { "content-type": "text/plain" } },
@@ -3802,6 +3770,7 @@ async function runProjectSetupInner(): Promise<ProjectSetupResult> {
 // ────────────────────────────────────────────────────────────────────────
 
 interface RunResult {
+  androidRecordings: AndroidRecording[];
   status: "passed" | "failed";
   durationMs: number;
   log: string;
@@ -5328,6 +5297,8 @@ function captureConsole(chunks: LineSink): () => void {
 
 async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   const start = Date.now();
+  const nativeAndroid = androidScope(testCase.id, start);
+  let androidRecordings: AndroidRecording[] = [];
   const chunks: string[] = [];
   const origStdout = process.stdout.write.bind(process.stdout);
   const origStderr = process.stderr.write.bind(process.stderr);
@@ -5520,7 +5491,8 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     return term;
   };
 
-  startRecording();
+  // Share the case clock with native video timestamps and other artifacts.
+  startRecording(start);
   const restoreFetch = installFetchWrapper();
   const fetchScope = createInstrumentationScope();
 
@@ -5635,6 +5607,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     openTerminal: recordedOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    android: nativeAndroid.open,
     desktop: desktopOpener(start, testCase.id, sessions, browserDetaches),
     mcp: openMcp,
     testName: testCase.name,
@@ -5662,10 +5635,10 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
 
   // Result events are gathered inside finally (after the final browser
   // drains) so we hoist these out of the try/catch.
-  let outcome: { status: "passed" | "failed"; error?: RunResult["error"] };
+  let outcome: { status: "passed" | "failed"; error?: RunResult["error"] } = { status: "passed" };
   try {
     const value = await Promise.race([
-      Promise.resolve(runInstrumented(fetchScope, () => testCase.run(ctx))),
+      Promise.resolve(runInstrumented(fetchScope, async () => { await nativeAndroid.begin(Object.values(base.svc).filter(isAndroidApp)); return testCase.run(ctx); })),
       timedOut,
     ]);
     // Stash the return value so child cases — which fork from the snapshot
@@ -5680,6 +5653,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     };
   } finally {
     if (timer) clearTimeout(timer);
+    nativeAndroid.deactivate();
     RECORDING_EXEC = undefined;
     INTERCEPTORS.endScope();
     fetchScope.active = false;
@@ -5702,6 +5676,9 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
       }
     }
     for (const s of sessions) s.markClosed();
+    androidRecordings = await nativeAndroid.finish();
+    const captureErrors = androidRecordings.flatMap(r => r.error ? [r.error] : []);
+    if (captureErrors.length && outcome.status === "passed") outcome = { status: "failed", error: { message: captureErrors.join("\n") } };
   }
   const durationMs = Date.now() - start;
   // Capture each service's log delta (the lines THIS case added beyond its
@@ -5757,6 +5734,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   }
   return {
     status: outcome.status,
+    androidRecordings,
     durationMs,
     log: chunks.join(""),
     events,
@@ -6032,6 +6010,7 @@ function explainEvalExportError(code: string, message: string): string {
 
 async function evalCode(code: string): Promise<EvalResult> {
   const start = Date.now();
+  const nativeAndroid = androidScope("eval", start, { record: false });
   const chunks: string[] = [];
   const origStdout = process.stdout.write.bind(process.stdout);
   const origStderr = process.stderr.write.bind(process.stderr);
@@ -6183,6 +6162,7 @@ async function evalCode(code: string): Promise<EvalResult> {
     openTerminal: evalOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    android: nativeAndroid.open,
     desktop: desktopOpener(start, "eval", sessions, browserDetaches, artifactCollector),
     mcp: openMcp,
     testName: "eval",
@@ -6243,6 +6223,7 @@ async function evalCode(code: string): Promise<EvalResult> {
       }
     }
     for (const s of sessions) s.markClosed();
+    await nativeAndroid.finish();
     if (filePath) {
       fs.unlink(filePath).catch(() => {
         /* best-effort cleanup */
@@ -6833,6 +6814,8 @@ export function harnessMethods(state: RouteState): MethodTable {
 
     // One chunk of a parked replay bundle. Case ids are arbitrary user
     // strings, so they travel in params rather than a URL path.
+    androidRecordingChunk: async (params) => androidRecordingChunk(String(params.caseId ?? params.id), params.offset, params.limit),
+    releaseAndroidRecording: async (params) => releaseAndroidRecording(String(params.id)),
     replayChunk: async (params) => {
       const caseId = requireString(params, "caseId", "caseId");
       const gz = REPLAY_BUNDLES.get(caseId);

package/src/harness/main.ts

@@ -34,6 +34,7 @@
  */
 
 import net from "node:net";
+import { initializeStickyConsumer, STICKY_CAPABILITY, type StickyConsumerConfig } from "./sticky-consumer";
 
 import { METHODS } from "../daemon";
 import { codeOf } from "./methods";
@@ -50,7 +51,7 @@ import {
 
 /** Capabilities this build announces. Empty is fine — the slot is what
  *  matters, so a later release has something to negotiate against. */
-const CAPABILITIES: string[] = [];
+const CAPABILITIES: string[] = [STICKY_CAPABILITY];
 
 type Handler = (params: Record<string, unknown>) => Promise<unknown>;
 
@@ -65,6 +66,10 @@ export function handlers(
   return {
     // Everything the environment actually does.
     ...methods,
+    stickyInitialize: async (params) => {
+      await initializeStickyConsumer(params as unknown as StickyConsumerConfig);
+      return { initialized: true };
+    },
     // Transport-level methods, which the method table has no business
     // knowing about: they concern this connection, not this environment.
     // Declared after the spread so the table can never shadow them — a

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

@@ -0,0 +1,45 @@
+import { expect, test } from "bun:test";
+import { STICKY_COMPATIBILITY, validateStickyConfig, collectStickyCache } from "./sticky-consumer";
+
+const GiB = 1024 ** 3;
+const config = { path: "/var/lib/spectest-sticky", capacityBytes: 256 * GiB,
+  headroomBytes: 32 * GiB, cacheTargetBytes: 64 * GiB, buildkitTargetBytes: 32 * GiB,
+  compatibility: STICKY_COMPATIBILITY };
+
+test("sticky consumer validates independent retention and working budgets", () => {
+  expect(() => validateStickyConfig(config)).not.toThrow();
+  // Changing capacity does not require increasing either retention target.
+  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 }]) {
+    expect(() => validateStickyConfig({ ...config, ...override })).toThrow();
+  }
+});
+
+test("filesystem pressure removes oldest Docker images when BuildKit pruning frees nothing", async () => {
+  let used = 100 * 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 }));
+  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)));
+});
+
+test("healthy cache keeps recent 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 }));
+  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");
+});

package/src/harness/sticky-consumer.ts

@@ -0,0 +1,176 @@
+/** Docker/BuildKit policy for the generic sticky disk. No host publication API. */
+import { execFile } from "node:child_process";
+import { mkdir, readFile, statfs, writeFile } from "node:fs/promises";
+
+export const STICKY_CAPABILITY = "sticky-disks-v1";
+export const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
+export const STICKY_RUNTIME = "/run/spectest-sticky";
+export interface StickyConsumerConfig {
+  path: string;
+  capacityBytes: number;
+  headroomBytes: number;
+  cacheTargetBytes: number;
+  buildkitTargetBytes: number;
+  compatibility: string;
+}
+
+function exec(program: string, args: string[], timeout = 60_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(program, args, { timeout, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) reject(new Error(`${program} failed: ${stderr || stdout || error.message}`));
+      else resolve(stdout.trim());
+    });
+  });
+}
+async function ready(program: string, args: string[]): Promise<void> {
+  const deadline = Date.now() + 30_000;
+  let last: unknown;
+  do {
+    try { await exec(program, args, 2000); return; } catch (error) { last = error; }
+    await Bun.sleep(100);
+  } while (Date.now() < deadline);
+  throw last;
+}
+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) {
+    throw new Error("unsupported sticky consumer profile or budget");
+  }
+}
+
+export async function initializeStickyConsumer(config: StickyConsumerConfig): Promise<void> {
+  validateStickyConfig(config);
+  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.
+  for (const unit of ["docker.service", "docker.socket", "containerd.service"]) {
+    const state = await exec("systemctl", ["show", unit, "-p", "ActiveState", "--value"]);
+    if (!["inactive", "failed"].includes(state)) throw new Error(`sticky base has active legacy consumer: ${unit}: ${state}`);
+  }
+  for (const [program, version] of [["dockerd", "29.7.2"], ["containerd", "v2.1.5"], ["buildkitd", "v0.32.2"]]) {
+    if (!(await exec(program!, ["--version"])).includes(version!)) throw new Error(`unsupported ${program} version for sticky profile`);
+  }
+  await mkdir(STICKY_RUNTIME, { recursive: true });
+  for (const child of ["docker", "containerd", "buildkit"]) await mkdir(`${config.path}/${child}`, { recursive: true });
+  await writeFile(`${STICKY_RUNTIME}/consumer.json`, JSON.stringify(config));
+  await writeFile(`${STICKY_RUNTIME}/containerd.toml`, `version = 2
+root = "${config.path}/containerd"
+state = "/run/containerd"
+disabled_plugins = ["io.containerd.grpc.v1.cri"]
+[grpc]
+  address = "/run/containerd/containerd.sock"
+`);
+  const dockerConfig = JSON.parse(await readFile("/etc/docker/daemon.json", "utf8"));
+  dockerConfig["data-root"] = `${config.path}/docker`;
+  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}
+`);
+  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
+      // shutdown (util/appcontext). A timeout/signal still fails the unit.
+      ...(unit === "spectest-sticky-buildkit" ? ["-p", "SuccessExitStatus=1"] : []),
+      program, ...args]);
+  };
+  await start("spectest-sticky-containerd", "containerd", ["--config", `${STICKY_RUNTIME}/containerd.toml`]);
+  await ready("ctr", ["version"]);
+  await start("spectest-sticky-docker", "dockerd", ["--config-file", `${STICKY_RUNTIME}/docker.json`,
+    "--host", "unix:///run/docker.sock", "--exec-root", "/run/docker", "--pidfile", "/run/docker.pid",
+    "--containerd", "/run/containerd/containerd.sock", "--containerd-namespace", "moby"]);
+  await ready("docker", ["info"]);
+  await start("spectest-sticky-buildkit", "buildkitd", ["--config", `${STICKY_RUNTIME}/buildkit.toml`]);
+  await ready("buildctl", ["--addr", "tcp://127.0.0.1:1234", "debug", "workers"]);
+  await exec("docker", ["buildx", "create", "--name", "spectest-local", "--driver", "remote", "tcp://127.0.0.1:1234"]);
+  await exec("docker", ["buildx", "inspect", "--bootstrap", "spectest-local"]);
+}
+
+/** 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 async function collectStickyCache(
+  config: StickyConsumerConfig,
+  run: typeof exec = exec,
+  usage = async (): Promise<{ freeBytes: number; totalBytes: number }> => {
+    const fs = await statfs(config.path);
+    return { freeBytes: fs.bavail * fs.bsize, totalBytes: fs.blocks * fs.bsize };
+  },
+): 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;
+  let fs = await usage();
+  // Always enforce the independent BuildKit target. Its accounting alone
+  // cannot bound shared images/content, so also request real filesystem space.
+  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);
+    fs = await usage();
+  };
+  await pruneBuildkit();
+  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));
+  for (const image of images) {
+    await run("docker", ["image", "rm", "-f", image.Id], 120_000);
+    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");
+}
+
+/** Only on an isolated maintenance clone; never on the live ready environment. */
+export async function prepareStickyConsumer(artifact = false): Promise<{ prepared: true; freeBytes: number }> {
+  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);
+    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]);
+    await collectStickyCache(config);
+  }
+  const units = ["spectest-sticky-buildkit", "spectest-sticky-docker", "spectest-sticky-containerd"];
+  for (const unit of units) {
+    const active = await exec("systemctl", ["show", unit, "-p", "ActiveState", "--value"]);
+    if (active !== "active") throw new Error(`consumer exited before sealing: ${unit}: ${active}`);
+    await exec("systemctl", ["stop", unit], 45_000);
+    const result = await exec("systemctl", ["show", unit, "-p", "Result", "--value"]);
+    if (result !== "success") throw new Error(`unclean consumer shutdown: ${unit}: ${result}`);
+  }
+  const fs = await statfs(config.path);
+  const freeBytes = fs.bavail * fs.bsize;
+  if (freeBytes < config.headroomBytes) throw new Error("sticky publication has insufficient write headroom");
+  // The supervisor verifies and unmounts; only the worker seals/publishes.
+  return { prepared: true, freeBytes };
+}

package/src/harness/sticky-maintenance.ts

@@ -0,0 +1,7 @@
+// Dedicated entry point: no daemon.ts, project modules, bootstrap or tests.
+import { prepareStickyConsumer } from "./sticky-consumer";
+
+if (import.meta.main) {
+  try { console.log(JSON.stringify(await prepareStickyConsumer(process.argv.includes("--artifact")))); }
+  catch (error) { console.error(error); process.exitCode = 1; }
+}