@specific.dev/spectest 0.89.1 → 0.90.0

package/src/components/android-runtime.mjs

@@ -0,0 +1,257 @@
+// Runs inside the Android tools container, in the same snapshotted VM.
+import http from "node:http";
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, stat, open, rm } from "node:fs/promises";
+const exec = promisify(execFile);
+const serial = process.env.ANDROID_SERIAL;
+const directory = "/recordings";
+const recordings = new Map();
+const maxBytes = 256 * 1024 * 1024;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const adb = (...args) =>
+  exec("adb", ["-s", serial, ...args], { timeout: 120000, maxBuffer: 1024 * 1024 });
+await mkdir(directory, { recursive: true });
+let ready = false;
+let bootError;
+async function bootstrap() {
+  const deadline = Date.now() + 180000;
+  while (Date.now() < deadline) {
+    try {
+      await exec("adb", ["connect", serial], { timeout: 10000 });
+      if ((await adb("shell", "getprop", "sys.boot_completed")).stdout.trim() === "1") break;
+    } catch {}
+    await sleep(500);
+  }
+  if ((await adb("shell", "getprop", "sys.boot_completed")).stdout.trim() !== "1") {
+    throw new Error(
+      "Android did not boot; the guest kernel needs Binder, DMA-BUF heaps and PSI enabled",
+    );
+  }
+  await adb("install", "-r", "/spectest/app.apk");
+  await adb("shell", "settings", "put", "global", "private_dns_mode", "off");
+  for (const setting of [
+    "window_animation_scale",
+    "transition_animation_scale",
+    "animator_duration_scale",
+  ]) {
+    await adb("shell", "settings", "put", "global", setting, "0");
+  }
+  // Native feedback covers physical input; injected Appium taps use replay metadata.
+  await adb("shell", "settings", "put", "system", "show_touches", process.env.ANDROID_SHOW_TOUCHES ?? "1");
+  await adb("shell", "svc", "power", "stayon", "true");
+  await adb("shell", "input", "keyevent", "82");
+  await adb("shell", "am", "start", "-W", "-n", process.env.ANDROID_ACTIVITY);
+  const appium = spawn(
+    "appium",
+    ["--address", "0.0.0.0", "--port", "4723", "--log-level", "warn"],
+    { stdio: "inherit" },
+  );
+  appium.on("exit", (code) => {
+    ready = false;
+    bootError = `Appium exited (${code})`;
+  });
+  appium.on("error", (error) => {
+    ready = false;
+    bootError = error.message;
+  });
+  for (let i = 0; i < 120; i++) {
+    try {
+      if ((await fetch("http://127.0.0.1:4723/status")).ok) {
+        ready = true;
+        return;
+      }
+    } catch {}
+    await sleep(250);
+  }
+  throw new Error("Appium did not become ready");
+}
+bootstrap().catch((error) => {
+  bootError = error.message;
+  console.error(error);
+});
+
+async function startRecording(body) {
+  if (!/^[a-z0-9-]{1,100}$/.test(body.id)) throw new Error("invalid recording id");
+  if (recordings.has(body.id)) throw new Error("recording already exists");
+  if ([...recordings.values()].some((r) => !r.stopped))
+    throw new Error("a recording is already active");
+  if (recordings.size >= 8) throw new Error("release older recordings before starting another");
+  const size = body.maxSize ?? 1280,
+    fps = body.maxFps ?? 15,
+    bitrate = body.bitRate ?? 2000000;
+  if (
+    !Number.isInteger(size) ||
+    size < 320 ||
+    size > 1920 ||
+    !Number.isInteger(fps) ||
+    fps < 1 ||
+    fps > 30 ||
+    !Number.isInteger(bitrate) ||
+    bitrate < 100000 ||
+    bitrate > 8000000
+  )
+    throw new Error("invalid recording settings");
+  const path = `${directory}/${body.id}.mp4`;
+  // scrcpy's stdout is otherwise block-buffered under Node's pipes: the
+  // readiness line may never flush on an idle screen.
+  const child = spawn("stdbuf", [
+    "-oL",
+    "-eL",
+    "scrcpy",
+    "--serial",
+    serial,
+    "--no-window",
+    "--no-playback",
+    "--no-control",
+    "--no-audio",
+    "--video-codec=h264",
+    "--video-encoder=c2.android.avc.encoder",
+    `--max-size=${size}`,
+    `--max-fps=${fps}`,
+    `--video-bit-rate=${bitrate}`,
+    `--record=${path}`,
+  ]);
+  const record = { child, path, stopped: false, log: "", error: null, startedAtMs: Date.now() };
+  recordings.set(body.id, record);
+  record.exit = new Promise((resolve) => {
+    child.on("error", (error) => {
+      record.error = error.message;
+      resolve(-1);
+    });
+    child.on("exit", (code) => {
+      if (!record.stopped) record.error = `Recorder exited early (${code})`;
+      resolve(code);
+    });
+  });
+  for (const output of [child.stdout, child.stderr])
+    output.on("data", (b) => {
+      record.log = (record.log + b).slice(-16000);
+      if (!record.started && record.log.includes("Recording started")) {
+        record.started = true;
+        record.startedAtMs = Date.now();
+      }
+    });
+  record.guard = setInterval(async () => {
+    if ((await stat(path).catch(() => ({ size: 0 }))).size > maxBytes) {
+      record.error = "Recording exceeded 256 MiB";
+      child.kill("SIGINT");
+    }
+  }, 1000);
+  try {
+    for (let i = 0; i < 200; i++) {
+      if (record.error) throw new Error(`${record.error}: ${record.log}`);
+      if (record.started) return { startedAtMs: record.startedAtMs };
+      await sleep(50);
+    }
+    throw new Error(`Recorder startup timed out: ${record.log}`);
+  } catch (error) {
+    clearInterval(record.guard);
+    record.stopped = true;
+    child.kill("SIGKILL");
+    await record.exit;
+    await rm(path, { force: true });
+    recordings.delete(body.id);
+    throw error;
+  }
+}
+async function stopRecording(record) {
+  if (record.result) return record.result;
+  record.stopped = true;
+  const closedAtMs = Date.now();
+  clearInterval(record.guard);
+  record.child.kill("SIGINT");
+  let timer;
+  const code = await Promise.race([
+    record.exit,
+    new Promise((resolve) => {
+      timer = setTimeout(() => {
+        record.error = "Recorder finalization timed out";
+        record.child.kill("SIGKILL");
+        resolve(-1);
+      }, 15000);
+    }),
+  ]);
+  clearTimeout(timer);
+  if (record.error || code !== 0)
+    throw new Error(`${record.error ?? "Recorder failed"}: ${record.log}`);
+  const bytes = (await stat(record.path)).size;
+  if (bytes > maxBytes) throw new Error("Recording exceeded 256 MiB");
+  const { stdout } = await exec("ffprobe", [
+    "-v",
+    "error",
+    "-show_format",
+    "-show_streams",
+    "-of",
+    "json",
+    record.path,
+  ]);
+  const probe = JSON.parse(stdout),
+    stream = probe.streams.find((s) => s.codec_type === "video");
+  if (!stream || !Number(stream.nb_frames)) throw new Error("Recording contains no video frames");
+  return (record.result = {
+    bytes,
+    startedAtMs: record.startedAtMs,
+    closedAtMs,
+    width: stream.width,
+    height: stream.height,
+    mediaDurationMs: Math.round(Number(probe.format.duration) * 1000),
+  });
+}
+const server = http.createServer(async (req, res) => {
+  const json = (status, body) => {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+  };
+  try {
+    const url = new URL(req.url, "http://localhost");
+    if (url.pathname === "/ready") return json(ready ? 200 : 503, { ready, error: bootError });
+    if (!ready) return json(503, { error: bootError ?? "Android is starting" });
+    if (req.method === "POST" && url.pathname === "/recordings") {
+      let body = "";
+      for await (const chunk of req) {
+        body += chunk;
+        if (body.length > 8192) throw new Error("request too large");
+      }
+      return json(200, await startRecording(JSON.parse(body)));
+    }
+    const match = url.pathname.match(/^\/recordings\/([a-z0-9-]{1,100})(\/stop)?$/);
+    const record = match && recordings.get(match[1]);
+    if (!record) return json(404, { error: "Unknown recording" });
+    if (req.method === "POST" && match[2]) return json(200, await stopRecording(record));
+    if (req.method === "DELETE") {
+      if (!record.stopped) throw new Error("Stop the recording before releasing it");
+      await rm(record.path, { force: true });
+      recordings.delete(match[1]);
+      return json(200, { released: true });
+    }
+    if (req.method === "GET" && record.result) {
+      const offset = Number(url.searchParams.get("offset") ?? 0),
+        limit = Number(url.searchParams.get("limit") ?? 6291456);
+      if (
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        !Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > 6291456
+      )
+        throw new Error("invalid chunk range");
+      const file = await open(record.path, "r");
+      try {
+        const buffer = Buffer.alloc(Math.min(limit, Math.max(0, record.result.bytes - offset)));
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, offset);
+        return json(200, {
+          total: record.result.bytes,
+          offset,
+          b64: buffer.subarray(0, bytesRead).toString("base64"),
+        });
+      } finally {
+        await file.close();
+      }
+    }
+    json(409, { error: "Recording is not finalized" });
+  } catch (error) {
+    json(500, { error: error.message });
+  }
+});
+server.listen(4725, "0.0.0.0");

package/src/components/android.test.ts

@@ -0,0 +1,68 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { android } from "./android.js";
+
+test("Android expands into two VM services with an APK input and private Appium/ADB addresses", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "spectest-android-")),
+    apk = join(dir, "app.apk");
+  writeFileSync(apk, "fixture");
+  try {
+    // Project path constants are captured on module load, just as in a guest.
+    const child = Bun.spawn(
+      [
+        process.execPath,
+        "-e",
+        `
+      import { defineEnvironment } from ${JSON.stringify(new URL("../index.ts", import.meta.url).pathname)};
+      import { android } from ${JSON.stringify(new URL("./android.ts", import.meta.url).pathname)};
+      const env = defineEnvironment({ name: "android", services: {
+        phone: android({ apk: "app.apk", package: "com.example.app", activity: ".MainActivity", dependsOn: ["backend"], recording: { maxSize: 640 } }),
+        backend: { image: { type: "registry", reference: "node:22" } },
+      } }).project().environment;
+      console.log(JSON.stringify(env));
+    `,
+      ],
+      { env: { ...process.env, SPECTEST_WORKSPACE: dir }, stdout: "pipe", stderr: "pipe" },
+    );
+    const output = await new Response(child.stdout).text();
+    expect(await new Response(child.stderr).text()).toBe("");
+    expect(await child.exited).toBe(0);
+    const env = JSON.parse(output);
+    const device = env.services["phone-device"],
+      tools = env.services.phone;
+    expect(device.privileged).toBe(true);
+    expect(device.args).toContain("androidboot.redroid_width=1080");
+    expect(device.args).toContain("androidboot.redroid_height=2400");
+    expect(device.args).toContain("androidboot.redroid_dpi=420");
+    expect(device.dependsOn).toEqual(["backend"]);
+    expect(device.args).toContain("androidboot.redroid_net_dns1=127.0.0.11");
+    expect(tools.dependsOn).toContain("phone-device");
+    expect(tools.env?.ANDROID_SERIAL).toBe("phone-device.internal:5555");
+    expect(tools.env?.ANDROID_ACTIVITY).toBe("com.example.app/.MainActivity");
+    expect(tools.env?.ANDROID_SHOW_TOUCHES).toBe("1");
+    expect(tools.inputs).toContain("app.apk");
+    expect(tools.volumes).toContainEqual({
+      source: apk,
+      target: "/spectest/app.apk",
+      readOnly: true,
+    });
+    expect(tools.readyCheck).toMatchObject({ type: "http", port: 4725 });
+    expect(tools.files?.[0].content).toContain("--no-window");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bad dimensions and identifiers fail before image builds", () => {
+  expect(() =>
+    android({ apk: "x.apk", package: "bad/package", activity: ".MainActivity" }),
+  ).toThrow();
+  expect(() =>
+    android({ apk: "x.apk", package: "com.example", activity: ".MainActivity", width: NaN }),
+  ).toThrow();
+  expect(() =>
+    android({ apk: "spectest/tests/app.apk", package: "com.example", activity: ".MainActivity" }),
+  ).toThrow("invalidate snapshots");
+});

package/src/components/android.ts

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import { posix } from "node:path";
+import { serviceGroup } from "../index.js";
+import { resolveExistingProjectPath } from "../project-files.js";
+import { androidApp, type AndroidApp, type AndroidRecordingOptions } from "../android.js";
+
+export interface AndroidOptions {
+  /** Project-relative path to an APK built for the worker's native ABI. */
+  apk: string;
+  /** Android application id, for example com.example.app. */
+  package: string;
+  /** Launch activity, for example .MainActivity. */
+  activity: string;
+  /** Android image; default is the tested Android 14 arm64-only redroid image. */
+  image?: string;
+  /** Optional prebuilt image containing the same tools as ANDROID_TOOLS_DOCKERFILE. */
+  toolsImage?: string;
+  /** Display defaults to Pixel 8 dimensions: 1080 × 2400, at 420 logical dpi. */
+  width?: number;
+  height?: number;
+  dpi?: number;
+  /** Show tap markers in replay and enable native physical-touch feedback. Default true. */
+  showTouches?: boolean;
+  recording?: false | AndroidRecordingOptions;
+  dependsOn?: string[];
+}
+
+export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
+RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
+ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium
+RUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0
+`;
+
+/** Native Android, Appium and software recording, all inside the environment VM. */
+export function android(options: AndroidOptions) {
+  if (
+    !options.apk ||
+    !/^[\w]+(?:\.[\w]+)+$/.test(options.package) ||
+    !/^[\w.$]+$/.test(options.activity)
+  )
+    throw new Error("android(): apk, package and activity are required");
+  const apk = posix.normalize(options.apk);
+  if (posix.isAbsolute(apk) || apk.startsWith("../") || apk.startsWith("spectest/tests/"))
+    throw new Error(
+      "android(): apk must be project-relative and outside spectest/tests so app changes invalidate snapshots",
+    );
+  const width = options.width ?? 1080,
+    height = options.height ?? 2400,
+    dpi = options.dpi ?? 420;
+  for (const value of [width, height, dpi])
+    if (!Number.isInteger(value) || value < 1 || value > 4096)
+      throw new Error("android(): invalid display dimensions/density");
+  return serviceGroup({
+    primary: "tools",
+    services: (g) => ({
+      device: {
+        image: {
+          type: "registry" as const,
+          reference:
+            options.image ??
+            "redroid/redroid:14.0.0_64only-latest@sha256:0a611199ba2e0b5d60af39b3327a517f6407231f4352114ed3bd3cbfe2be69aa",
+        },
+        privileged: true,
+        // Android's netd ignores resolv.conf. Use Docker's per-container DNS,
+        // which resolves service aliases and forwards to the in-VM resolver.
+        args: [
+          `androidboot.redroid_width=${width}`,
+          `androidboot.redroid_height=${height}`,
+          `androidboot.redroid_dpi=${dpi}`,
+          "androidboot.redroid_gpu_mode=guest",
+          "androidboot.use_memfd=1",
+          "androidboot.redroid_net_ndns=1",
+          "androidboot.redroid_net_dns1=127.0.0.11",
+        ],
+        ports: [5555],
+        dependsOn: options.dependsOn,
+        readyCheck: {
+          type: "exec" as const,
+          command: 'test "$(getprop sys.boot_completed)" = 1',
+          timeoutSecs: 180,
+        },
+      },
+      tools: {
+        image: options.toolsImage
+          ? { type: "registry" as const, reference: options.toolsImage }
+          : { type: "dockerfile" as const, content: ANDROID_TOOLS_DOCKERFILE },
+        command: "node /spectest-android.mjs",
+        files: [
+          {
+            path: "/spectest-android.mjs",
+            content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
+          },
+        ],
+        volumes: [
+          {
+            source: resolveExistingProjectPath(apk, "Android APK"),
+            target: "/spectest/app.apk",
+            readOnly: true,
+          },
+        ],
+        inputs: [apk],
+        env: {
+          ANDROID_SERIAL: `${g.key("device")}.internal:5555`,
+          ANDROID_ACTIVITY: `${options.package}/${options.activity}`,
+          ANDROID_SHOW_TOUCHES: options.showTouches === false ? "0" : "1",
+        },
+        ports: [4723, 4725],
+        readyCheck: { type: "http" as const, port: 4725, path: "/ready", timeoutSecs: 240 },
+      },
+    }),
+    helpers: ({ name }): AndroidApp =>
+      androidApp({
+        name,
+        endpoint: `http://${name}.internal:4723`,
+        recorderEndpoint: `http://${name}.internal:4725`,
+        serial: `${name}-device.internal:5555`,
+        package: options.package,
+        recording: options.recording ?? {},
+        showTouches: options.showTouches ?? true,
+      }),
+  });
+}

package/src/components/index.ts

@@ -98,3 +98,5 @@ export {
   type CassetteState,
 } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
+
+export { android, type AndroidOptions } from "./android.js";

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:
 //
@@ -775,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;
@@ -3764,6 +3770,7 @@ async function runProjectSetupInner(): Promise<ProjectSetupResult> {
 // ────────────────────────────────────────────────────────────────────────
 
 interface RunResult {
+  androidRecordings: AndroidRecording[];
   status: "passed" | "failed";
   durationMs: number;
   log: string;
@@ -5290,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);
@@ -5482,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();
 
@@ -5597,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,
@@ -5624,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
@@ -5642,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;
@@ -5664,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
@@ -5719,6 +5734,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
   }
   return {
     status: outcome.status,
+    androidRecordings,
     durationMs,
     log: chunks.join(""),
     events,
@@ -5994,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);
@@ -6145,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",
@@ -6205,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 */
@@ -6795,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");
+});