@specific.dev/spectest 0.131.11 → 0.131.13

package/src/components/android.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { serviceGroup } from "../index.js";
@@ -44,7 +45,7 @@ assert s.count(a) == 1
 p.write_text(s.replace(a, a + '\n    puts("spectest-first-frame-v1");'))`;
 const shellQuote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
 
-export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
+export const ANDROID_TOOLS_DOCKERFILE = `FROM ${BUILTIN_IMAGES["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 openssl curl gcc python3 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 && python3 -c ${shellQuote(recorderPatch.replaceAll("\n", ";"))} && 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

package/src/components/aws.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 // `aws()` — the AWS cloud APIs, emulated inside the environment, answering
 // at their **real** endpoints.
 //
@@ -68,7 +69,7 @@ import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../index.js";
 import { pauseRecording, resumeRecording } from "../recorder.js";
 
 /** Backing image, pinned internally (not part of the documented surface). */
-const AWS_IMAGE = "ministackorg/ministack:1.4.8";
+const AWS_IMAGE = BUILTIN_IMAGES["ministackorg/ministack:1.4.8"];
 /** Port the emulator serves every AWS API on. Internal: callers reach the
  *  emulator through the AWS hostnames, never through this port. */
 const AWS_PORT = 4566;

package/src/components/electron.test.ts

@@ -24,6 +24,8 @@ describe('Electron component contract', () => {
     writeFileSync(join(appDir, 'package-lock.json'), '{}');
     const service = electron({ appDir, buildCommand: 'npm run compile', env: { API_URL: 'http://backend:4320' } });
     expect(service.image).toMatchObject({ context: appDir });
+    expect(service.image.content.split('\n')[0]).toMatch(/^FROM node:24-bookworm-slim@sha256:[a-f0-9]{64}$/);
+    expect(electron({ appDir, nodeVersion: '22-alpine' }).image.content.split('\n')[0]).toBe('FROM node:22-alpine');
     expect((service.image as { content: string }).content).toContain('RUN npm ci\n');
     expect((service.image as { content: string }).content).toContain('RUN npm run compile\n');
     expect(service.env?.API_URL).toBe('http://backend:4320');

package/src/components/electron.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { existsSync, readFileSync } from "node:fs";
 import { posix } from "node:path";
 import type { ServiceDefinition } from "../index.js";
@@ -131,7 +132,7 @@ export function electron(options: ElectronOptions = {}) {
       type: "dockerfile",
       context,
       exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
-      content: `FROM node:${node}
+      content: `FROM ${options.nodeVersion === undefined ? BUILTIN_IMAGES["node:24-bookworm-slim"] : `node:${node}`}
 RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY . .

package/src/components/email.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 // `email()` — a real SMTP server as a spectest service. The app under test
 // points its SMTP transport at `<key>:1025` and sends mail exactly as it
@@ -29,7 +30,7 @@ import {
 import { wrap } from "../inspect.js";
 import type { Wrapped } from "../inspect.js";
 
-const DEFAULT_IMAGE = "axllent/mailpit:v1.30";
+const DEFAULT_IMAGE = BUILTIN_IMAGES["axllent/mailpit:v1.30"];
 const SMTP_PORT = 1025;
 const API_PORT = 8025;
 

package/src/components/emulate/service.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../../harness/builtin-images.js";
 // Shared runtime behind the third-party provider components — `google()`,
 // `github()`, `apple()`, `microsoft()`, `okta()`.
 //
@@ -53,7 +54,7 @@ import type { ServiceDefinition } from "../../index.js";
 import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../../index.js";
 
 /** Base image, pinned. Bun runs the emulators' ESM directly. */
-const IMAGE_BASE = "oven/bun:1.3.14-alpine";
+const IMAGE_BASE = BUILTIN_IMAGES["oven/bun:1.3.14-alpine"];
 /** Emulator package version, pinned rather than floated. */
 const EMULATE_VERSION = "0.9.0";
 /** The port the provider is served on. Callers reach it through the

package/src/components/expo.test.ts

@@ -175,9 +175,9 @@ describe("expo() Node version", () => {
     expect(dockerfile(expo())).toContain("FROM node:20-bookworm-slim");
   });
 
-  test("builds on 22 when the app declares nothing readable", () => {
+  test("pins the default Node image when the app declares nothing readable", () => {
     app({ "package.json": pkg(), ".nvmrc": "lts/iron\n" });
-    expect(dockerfile(expo())).toContain("FROM node:22-bookworm-slim");
+    expect(dockerfile(expo()).split("\n")[0]).toMatch(/^FROM node:22-bookworm-slim@sha256:[a-f0-9]{64}$/);
   });
 
   test("the option wins", () => {

package/src/components/expo.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 // `expo()` — a ready-to-use service for an Expo / React Native app rendered
 // to the web, built for `ctx.mobile(...)`.
 //
@@ -420,13 +421,13 @@ function publicEnvLines(env: Record<string, string>): string[] {
  * BuildKit, which every builder in a VM is.
  */
 function generateDockerfile(input: {
-  nodeVersion: string;
+  nodeImage: string;
   plan: InstallPlan;
   publicEnv: string[];
   outputDir: string;
 }): string {
-  const { nodeVersion, plan, publicEnv, outputDir } = input;
-  const lines = [`FROM node:${nodeVersion}`, "WORKDIR /app", "ENV CI=1", ...plan.env];
+  const { nodeImage, plan, publicEnv, outputDir } = input;
+  const lines = [`FROM ${nodeImage}`, "WORKDIR /app", "ENV CI=1", ...plan.env];
   for (const step of plan.bootstrap) lines.push(`RUN ${step}`);
   lines.push(`COPY ${plan.manifests.join(" ")} ./`);
   lines.push(`RUN --mount=type=cache,target=${plan.cacheDir},sharing=locked ${plan.install}`);
@@ -522,7 +523,7 @@ export function expo(opts: ExpoOptions = {}) {
     image = {
       type: "dockerfile",
       content: generateDockerfile({
-        nodeVersion: node.tag,
+        nodeImage: node.source === "the default" ? BUILTIN_IMAGES["node:22-bookworm-slim"] : `node:${node.tag}`,
         plan,
         publicEnv: publicEnvLines(opts.env ?? {}),
         outputDir,

package/src/components/image-pins.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { defineEnvironment } from "../index.js";
+import { postgres, email, aws, k3s, supabase, temporal, google } from "./index.js";
+import { ANDROID_TOOLS_DOCKERFILE } from "./android.js";
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
+import { REGISTRY_IMAGE } from "../harness/registry-seed.js";
+
+const credentials = { database: "app", user: "app", password: "app" };
+const digest = /@sha256:[a-f0-9]{64}$/;
+
+test("SDK-owned component images and generated base images are immutable", () => {
+  const environment = defineEnvironment({ name: "pins", services: {
+    db: postgres(credentials), mail: email(), cloud: aws(), cluster: k3s({ nodes: 3 }),
+    supabase: supabase().group, temporal: temporal({ tls: { hostname: "temporal.test" } }).group,
+    identity: google(),
+  } });
+  for (const [name, service] of Object.entries(environment.config.services)) {
+    const image = service.image;
+    if (image.type === "registry") expect(image.reference, name).toMatch(digest);
+    else if ("content" in image) {
+      for (const line of image.content!.split("\n").filter(line => /^FROM /i.test(line))) {
+        expect(line.split(/\s+/)[1], name).toMatch(digest);
+      }
+    }
+  }
+  expect(ANDROID_TOOLS_DOCKERFILE.split("\n")[0]!.slice(5)).toMatch(digest);
+  expect(REGISTRY_IMAGE).toMatch(digest);
+  for (const [tag, reference] of Object.entries(BUILTIN_IMAGES)) {
+    expect(reference.startsWith(`${tag}@`)).toBe(true);
+    expect(reference).toMatch(digest);
+  }
+});
+
+test("explicit user image and version overrides remain unchanged", () => {
+  expect(postgres({ ...credentials, version: "17-alpine" }).image).toMatchObject({ reference: "postgres:17-alpine" });
+  expect(postgres({ ...credentials, version: "17", image: "custom/db:latest" }).image).toMatchObject({ reference: "custom/db:latest" });
+  expect(email({ image: "custom/mail:latest" }).image).toMatchObject({ reference: "custom/mail:latest" });
+  const env = defineEnvironment({ name: "overrides", services: {
+    cluster: k3s({ version: "v1.33.6-k3s1" }),
+    temporal: temporal({ image: "custom/temporal:latest" }).group,
+  } });
+  expect(env.config.services.cluster.image).toMatchObject({ reference: "rancher/k3s:v1.33.6-k3s1" });
+  expect(env.config.services.temporal.image).toMatchObject({ reference: "custom/temporal:latest" });
+});

package/src/components/k3s.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { isIP } from "node:net";
 import { waitForK3sNodes } from "./k3s-nodes.js";
 import { JOIN_DIRECTORY, prepareK3sJoin } from "./k3s-join.js";
@@ -996,7 +997,7 @@ function withTagging<T extends object>(api: T): Tagged<T> {
  * `registries.yaml`, then captured into the warm-template snapshot so
  * warm starts never pull.
  */
-const TRAEFIK_IMAGE = "rancher/mirrored-library-traefik:3.3.2";
+const TRAEFIK_IMAGE = BUILTIN_IMAGES["rancher/mirrored-library-traefik:3.3.2"];
 
 /**
  * Names of the in-cluster resources that carry the CA-signed default
@@ -1247,7 +1248,7 @@ spec:
       - operator: Exists
       containers:
       - name: registry
-        image: ${seeded ? REGISTRY_IMAGE : "registry:2"}
+        image: ${REGISTRY_IMAGE}
         imagePullPolicy: IfNotPresent
         env:
         - name: REGISTRY_HTTP_ADDR
@@ -2111,7 +2112,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
     // checked all Nodes and finished loading images, not at API readiness.
     const readyCmd = "kubectl get --raw=/readyz >/dev/null 2>&1";
     const def = {
-      image: { type: "registry", reference: `rancher/k3s:${version}` },
+      image: { type: "registry", reference: opts.version === undefined ? BUILTIN_IMAGES["rancher/k3s:v1.33.5-k3s1"] : `rancher/k3s:${version}` },
       imageBuilds: server ? images.builds : [],
       tls: server && registryHost ? [{ hostname: registryHost, port: K3S_REGISTRY_PORT }] : [],
       command: cmd,
@@ -2215,7 +2216,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
           for (;;) {
             try {
               const pod = (await helpers.client.core.createNamespacedPod({ namespace: "default", dryRun: "All", body: {
-                metadata: { generateName: "spectest-trust-probe-" }, spec: { containers: [{ name: "probe", image: "registry.k8s.io/pause:3.10" }] },
+                metadata: { generateName: "spectest-trust-probe-" }, spec: { containers: [{ name: "probe", image: BUILTIN_IMAGES["registry.k8s.io/pause:3.10"] }] },
               } })).unwrap();
               if (pod.spec?.containers[0].env?.some(e => e.name === "SSL_CERT_FILE" && e.value === "/spectest/ca-bundle.crt")) break;
               if (Date.now() >= deadline) throw new Error(`k3s(${name}): Pod CA mounts did not become ready`);

package/src/components/postgres.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import type { ServiceDefinition, ServiceSetupContext } from "../index.js";
 import { SQL, type SqlClient } from "../sql.js";
 import { postgresTls } from "./postgres-tls.js";
@@ -97,8 +98,8 @@ export interface PostgresHelpers {
  * ```
  */
 export function postgres(opts: PostgresOptions) {
-  const version = opts.version ?? "18-alpine";
-  const reference = opts.image ?? `postgres:${version}`;
+  const reference = opts.image ?? (opts.version === undefined
+    ? BUILTIN_IMAGES["postgres:18-alpine"] : `postgres:${opts.version}`);
   const port = opts.port ?? 5432;
   const persistent = opts.persistent ?? true;
   const tls = opts.tls !== false ? postgresTls() : undefined;

package/src/components/replay-websocket.ts

@@ -218,7 +218,12 @@ export function replayWebSocket(args: {
     const progress = record.inputMode === "anchors"
       ? ` occurrence ${record.inputOccurrences![position]}; observed ${occurrences.get(expected) ?? 0} occurrences; received ${receivedMessages} messages, ${receivedCandidates} candidates; last candidate ${lastCandidate ?? "<none>"}`
       : "";
-    return diagnostic(`required input never arrived; expected ${expected}${progress}`);
+    const reordered = record.inputMode === "anchors"
+      && (occurrences.get(expected) ?? 0) >= record.inputOccurrences![position];
+    const detail = reordered
+      ? "required input arrived before preceding anchors matched"
+      : "required input never arrived";
+    return diagnostic(`${detail}; expected ${expected}${progress}`);
   };
   const armDeadline = () => {
     clearTimeout(deadline);

package/src/components/replayFake-websocket.test.ts

@@ -452,3 +452,26 @@ test("a reached response anchor catches up older output without adding its stale
   expect(c.sent).toEqual([...messages.map(m => m.data), "response"]);
   await c.close(); expect(h.state.websocketErrors).toEqual([]);
 });
+
+
+test("an anchor observed before its predecessor is diagnosed as out of order", async () => {
+  const key: WebSocketKey<null> = { initial: null,
+    input(state, message) { return { state, key: message }; },
+    output(state) { return { state, anchorPreviousInput: true }; },
+  };
+  const hash = (value: string) => websocketMatcher(() => value)("x")!;
+  const h = await harness([{ request, inputMode: "anchors",
+    inputs: [hash("start"), hash("warmup"), hash("question")],
+    inputOccurrences: [1, 1, 1],
+    messages: [{ type: "text", data: "answer", afterInput: 3, delayMs: 0 }],
+  }], key);
+  const c = await h.connect();
+  await c.message("start");
+  await c.message("question");
+  await c.message("warmup");
+  await tick();
+  expect(c.sent).toEqual([]);
+  await c.close();
+  expect(h.state.websocketErrors.join()).toContain("input #3: required input arrived before preceding anchors matched");
+  expect(h.state.websocketErrors.join()).toContain("occurrence 1; observed 1 occurrences");
+});

package/src/components/supabase-pooler.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import type { ServiceDefinition } from "../index.js";
 
 /** Supabase CLI's [db.pooler] settings. Ports are local to the pooler container. */
@@ -83,7 +84,7 @@ export function supabasePoolerService(opts: {
   const { config, dbHost, tenantId, password, jwtSecret, tls, url } = opts;
   const quotedUrl = `'${url.replace(/'/g, "'\\''")}'`;
   return {
-    image: { type: "registry", reference: "supabase/supavisor:2.9.12" },
+    image: { type: "registry", reference: BUILTIN_IMAGES["supabase/supavisor:2.9.12"] },
     // eval starts the OTP application too. Give that temporary instance
     // ephemeral SQL ports so readiness only sees the final server process.
     command: '/app/bin/migrate && PROXY_PORT_SESSION=0 PROXY_PORT_TRANSACTION=0 /app/bin/supavisor eval "$(cat /etc/pooler/pooler.exs)" && exec /app/bin/server',

package/src/components/supabase.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 // A ready-to-use, self-hosted **Supabase** stack, expressed as a set of
 // spectest services (one container each) wired together on spectest-net.
@@ -88,22 +89,22 @@ import {
 export type { MailTemplateId, MailTemplateSpec } from "./supabase-config.js";
 
 // ──────────────────────────────────────────────────────────────────────────
-// Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
-// current master). Bump together; each is pulled through the host Hub mirror on
+// Digest-pinned upstream images. Update BUILTIN_IMAGES together for compatible
+// Supabase releases; each is pulled through the host Hub mirror on
 // first cold boot and captured into the warm-template snapshot thereafter.
 // ──────────────────────────────────────────────────────────────────────────
 const IMAGES = {
-  db: "supabase/postgres:17.6.1.136",
-  kong: "kong/kong:3.9.1",
-  auth: "supabase/gotrue:v2.189.0",
-  rest: "postgrest/postgrest:v14.12",
-  realtime: "supabase/realtime:v2.102.3",
-  storage: "supabase/storage-api:v1.60.4",
-  imgproxy: "darthsim/imgproxy:v3.30.1",
-  functions: "supabase/edge-runtime:v1.74.0",
+  db: BUILTIN_IMAGES["supabase/postgres:17.6.1.136"],
+  kong: BUILTIN_IMAGES["kong/kong:3.9.1"],
+  auth: BUILTIN_IMAGES["supabase/gotrue:v2.189.0"],
+  rest: BUILTIN_IMAGES["postgrest/postgrest:v14.12"],
+  realtime: BUILTIN_IMAGES["supabase/realtime:v2.102.3"],
+  storage: BUILTIN_IMAGES["supabase/storage-api:v1.60.4"],
+  imgproxy: BUILTIN_IMAGES["darthsim/imgproxy:v3.30.1"],
+  functions: BUILTIN_IMAGES["supabase/edge-runtime:v1.74.0"],
   // Serves custom mail templates to GoTrue over HTTP (see the `templates`
   // part). Tiny, and only pulled by a stack that configures a template.
-  templates: "busybox:1.37",
+  templates: BUILTIN_IMAGES["busybox:1.37"],
 } as const;
 
 /** Override tables without mutating the parsed project config. */

package/src/components/temporal.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { serviceGroup, type ServiceDefinition, type ServicesMap } from "../index.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { readRaw } from "../inspect.js";
@@ -167,13 +168,13 @@ export function temporal(opts: TemporalOptions = {}) {
     primary, expectKey: name,
     services: (): ServicesMap => {
       const server: ServiceDefinition = {
-        image: { type: "registry", reference: opts.image ?? "temporalio/temporal:1.9.1" }, args,
+        image: { type: "registry", reference: opts.image ?? BUILTIN_IMAGES["temporalio/temporal:1.9.1"] }, args,
         ports: [port, httpPort, ...(opts.ui ? [8233] : [])],
         readyCheck: { type: "http", port: httpPort, path: `/api/v1/namespaces/${encodeURIComponent(namespace)}`, timeoutSecs: 30 },
       };
       if (!opts.tls) return { server };
       return { server, tls: {
-        image: { type: "registry", reference: "nginx:1.29.6-alpine" },
+        image: { type: "registry", reference: BUILTIN_IMAGES["nginx:1.29.6-alpine"] },
         ports: [port], hostnames: [opts.tls.hostname], dependsOn: [serverName],
         certificates: [{ hostnames: [opts.tls.hostname], certPath: "/tls/server.crt", keyPath: "/tls/server.key" }],
         files: [{ path: "/etc/nginx/nginx.conf", content: `worker_processes 1;\nevents { worker_connections 1024; }\nstream { server { listen ${port} ssl; ssl_certificate /tls/server.crt; ssl_certificate_key /tls/server.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_alpn h2; proxy_pass ${serverName}:${port}; } }\n` }],

package/src/daemon.ts

@@ -4,6 +4,7 @@ import { collectSecretRefs } from "./fake-upstream.js";
 import { phoneScope, phoneRecordingChunk, releasePhoneRecording, type PhoneRecording } from "./phone.js";
 import { runWithBackgroundFailures } from "./harness/background-failures.js";
 import { generateHostCert as mintHostCert } from "./harness/certificate.js";
+import { containerdImageOutput } from "./harness/built-image.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
 import { updateServiceProgress, serviceProgressSnapshot, type ServiceProgress } from "./harness/service-progress.js";
@@ -109,7 +110,7 @@ import {
   type GroupMeta,
 } from "./harness/catalogue.js";
 import { summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
-import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
+import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta, mergeServiceLogDeltas } from "./harness/log-delta.js";
 import {
   resolveHostPath as resolveVolumeHostPath,
   sanitizeSegment,
@@ -748,22 +749,6 @@ function ensureLocalBuildkitd(): Promise<boolean> {
   return _localBuilder;
 }
 
-/**
- * A reference as containerd names it. buildx's `-t` on a remote builder
- * stores an unqualified name (`probe:bx`) that dockerd then cannot
- * resolve (measured, CONTAINER_STORE.md), so the in-VM build names its
- * output in full.
- */
-function qualifyImageRef(ref: string): string {
-  const slash = ref.indexOf("/");
-  const first = slash < 0 ? "" : ref.slice(0, slash);
-  const isRegistry = first.includes(".") || first.includes(":") || first === "localhost";
-  if (slash < 0) return `docker.io/library/${ref}`;
-  if (!isRegistry) return `docker.io/${ref}`;
-  return ref;
-}
-
-
 /** Host directory backing one volume mount. Rules (notably which volumes
  *  survive the delta-restore teardown) live in `harness/volume-paths.ts`. */
 function resolveHostPath(service: string, vol: VolumeMount): string {
@@ -1379,11 +1364,15 @@ async function runServiceBuild(
       // every cached parent before the first uncached step (11–79 s for
       // one `COPY` on Specific's dashboard) and a second full pass to
       // export after every miss.
+      // Keep an immutable image reference as well as the service tag. The
+      // containerd exporter replaces the tag directly, bypassing Docker's
+      // dangling-image retention. Old versions must remain usable until our
+      // image GC decides they are no longer needed (including by nested stores).
       buildArgs = [
         "buildx", "build",
         "--builder", LOCAL_BUILDER_NAME,
         "--progress=plain",
-        "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
+        "--output", containerdImageOutput(tag),
         ...argFlags,
         "-f", dfPath, contextDir,
       ];
@@ -1489,6 +1478,11 @@ async function runContainer(
   // container docker-native multi-label resolution for its `hostnames`.
   extraAliases: string[] = [],
 ): Promise<void> {
+  // Preserve the previous incarnation before the name is reused.
+  if (RUNTIME_SERVICES.has(svc.name)) await stopRuntimeService(svc.name);
+  STOPPED_LOG_SERVICES.delete(svc.name);
+  LOG_MARKERS.delete(`${svc.name}\0stdout`);
+  LOG_MARKERS.delete(`${svc.name}\0stderr`);
   // Idempotent: clean up any leftover container with the same name.
   await docker(["rm", "-f", svc.name], 30_000);
 
@@ -2947,6 +2941,15 @@ async function stopRuntimeService(name: string): Promise<void> {
   const t0 = Date.now();
   const resv = reserveEvent();
   const svc = RUNTIME_SERVICES.get(name);
+  // Freeze log production before reading, while Docker still owns the logs.
+  // Keep force-stop semantics; removing first destroys the only copy.
+  await docker(["kill", name], 30_000);
+  if (!STOPPED_LOG_SERVICES.has(name)) {
+    const delta = await captureServiceLogDelta(name, true);
+    const previous = STOPPED_LOG_DELTAS.get(name);
+    STOPPED_LOG_DELTAS.set(name, previous ? mergeServiceLogDeltas(previous, delta) : delta);
+    STOPPED_LOG_SERVICES.add(name);
+  }
   await docker(["rm", "-f", name], 30_000);
   RUNTIME_SERVICES.delete(name);
   for (const entry of svc?.tls ?? []) await unbindRuntimeTls(entry.hostname);
@@ -3482,6 +3485,10 @@ function parkCoverageBundle(
  * so it travels with the snapshot into every fork.
  */
 const LOG_MARKERS = new Map<string, { lines: number }>();
+// Fork with the harness, like markers. Deltas drain once per case; names remain
+// excluded from Docker reads until a replacement container starts.
+const STOPPED_LOG_DELTAS = new Map<string, ServiceLogDelta>();
+const STOPPED_LOG_SERVICES = new Set<string>();
 
 /** Per-(service, stream) delta byte cap. Over this we keep head+tail and
  *  elide the middle — the head preserves the continuation from the parent,
@@ -3537,45 +3544,52 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
   const byName = new Map<string, NamedService>();
   for (const s of namedServices(l.project.environment)) byName.set(s.name, s);
   for (const [name, s] of RUNTIME_SERVICES) byName.set(name, s);
-  const services = [...byName.values()];
-  return Promise.all(
-    services.map(async (svc): Promise<ServiceLogDelta> => {
-      const [r, stop] = await Promise.all([
-        docker(["logs", "--timestamps", svc.name], 30_000),
-        containerStopState(svc.name),
-      ]);
-      if (r.code !== 0) {
-        // Container gone/renamed — surface the CLI error, leave markers put.
-        const err = capMiddle(r.stderr || r.stdout, LOG_DELTA_MAX_BYTES);
-        return {
-          service: svc.name,
-          stdout: "",
-          stdoutTruncated: false,
-          stdoutReset: false,
-          stderr: err.value,
-          stderrTruncated: err.truncated,
-          stderrReset: false,
-          ...stop,
-        };
-      }
-      const outKey = `${svc.name}stdout`;
-      const errKey = `${svc.name}stderr`;
-      const out = streamDelta(r.stdout, LOG_MARKERS.get(outKey)?.lines ?? 0);
-      const err = streamDelta(r.stderr, LOG_MARKERS.get(errKey)?.lines ?? 0);
-      LOG_MARKERS.set(outKey, { lines: out.total });
-      LOG_MARKERS.set(errKey, { lines: err.total });
-      return {
-        service: svc.name,
-        stdout: out.delta,
-        stdoutTruncated: out.truncated,
-        stdoutReset: out.reset,
-        stderr: err.delta,
-        stderrTruncated: err.truncated,
-        stderrReset: err.reset,
-        ...stop,
-      };
-    }),
-  );
+  const deltas = new Map(STOPPED_LOG_DELTAS);
+  for (const delta of await Promise.all([...byName.keys()]
+    .filter(name => !STOPPED_LOG_SERVICES.has(name)).map(name => captureServiceLogDelta(name)))) {
+    const previous = deltas.get(delta.service);
+    deltas.set(delta.service, previous ? mergeServiceLogDeltas(previous, delta) : delta);
+  }
+  STOPPED_LOG_DELTAS.clear();
+  return [...deltas.values()];
+}
+
+async function captureServiceLogDelta(name: string, final = false): Promise<ServiceLogDelta> {
+  const [r, stop] = await Promise.all([
+    docker(["logs", "--timestamps", name], 30_000),
+    containerStopState(name),
+  ]);
+  if (r.code !== 0) {
+    // Container gone/renamed — surface the CLI error, leave markers put.
+    const err = capMiddle(r.stderr || r.stdout, LOG_DELTA_MAX_BYTES);
+    return {
+      service: name,
+      stdout: "",
+      stdoutTruncated: false,
+      stdoutReset: false,
+      stderr: err.value,
+      stderrTruncated: err.truncated,
+      stderrReset: false,
+      ...stop,
+    };
+  }
+  const outKey = `${name}stdout`;
+  const errKey = `${name}stderr`;
+  const complete = (text: string) => final && text && !text.endsWith("\n") ? text + "\n" : text;
+  const out = streamDelta(complete(r.stdout), LOG_MARKERS.get(outKey)?.lines ?? 0);
+  const err = streamDelta(complete(r.stderr), LOG_MARKERS.get(errKey)?.lines ?? 0);
+  LOG_MARKERS.set(outKey, { lines: out.total });
+  LOG_MARKERS.set(errKey, { lines: err.total });
+  return {
+    service: name,
+    stdout: out.delta,
+    stdoutTruncated: out.truncated,
+    stdoutReset: out.reset,
+    stderr: err.delta,
+    stderrTruncated: err.truncated,
+    stderrReset: err.reset,
+    ...stop,
+  };
 }
 
 // ────────────────────────────────────────────────────────────────────────

package/src/harness/built-image-docker.test.ts

@@ -0,0 +1,62 @@
+// SPECTEST_TEST_STICKY_DOCKER=1 bun test sdk/src/harness/built-image-docker.test.ts
+// Requires local Docker's containerd store at /run/containerd/containerd.sock.
+import { expect, test } from "bun:test";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { containerdImageOutput } from "./built-image";
+
+async function run(args: string[]) {
+  const process = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
+  const [code, stdout, stderr] = await Promise.all([process.exited,
+    new Response(process.stdout).text(), new Response(process.stderr).text()]);
+  if (code) throw new Error(`${args.slice(0, 4).join(" ")}: ${stderr}`);
+  return stdout.trim();
+}
+
+test.skipIf(!process.env.SPECTEST_TEST_STICKY_DOCKER)("containerd rebuild retains old images until explicit image GC", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-export-"));
+  const builder = `sticky-export-${crypto.randomUUID()}`;
+  const consumer = `${builder}-consumer`;
+  const tag = `docker.io/spectest/${builder}:latest`;
+  const images = new Set<string>();
+  try {
+    await writeFile(`${root}/Dockerfile`, 'FROM scratch\nCOPY payload /payload\nCMD ["/payload"]\n');
+    await run(["docker", "run", "-d", "--privileged", "--name", builder,
+      "-v", "/run/containerd/containerd.sock:/run/containerd/containerd.sock",
+      "-v", "/var/lib/containerd:/var/lib/containerd", "-v", `${root}:/context:ro`,
+      "moby/buildkit:v0.32.2", "--oci-worker=false", "--containerd-worker=true",
+      "--containerd-worker-namespace=moby", "--containerd-worker-gc=false"]);
+    for (let attempt = 0; ; attempt++) {
+      try { await run(["docker", "exec", builder, "buildctl", "debug", "workers"]); break; }
+      catch (error) { if (attempt === 40) throw error; await Bun.sleep(250); }
+    }
+    async function build(payload: string, output = containerdImageOutput(tag)) {
+      await writeFile(`${root}/payload`, `${builder}-${payload}`);
+      await run(["docker", "exec", builder, "buildctl", "build", "--frontend", "dockerfile.v0",
+        "--local", "context=/context", "--local", "dockerfile=/context", "--output", output]);
+      const id = await run(["docker", "image", "inspect", "--format", "{{.Id}}", tag]);
+      images.add(id);
+      return id;
+    }
+    const first = await build("first");
+    const second = await build("second");
+    expect(second).not.toBe(first);
+    expect(await run(["docker", "image", "inspect", "--format", "{{.Id}}", first])).toBe(first);
+    await run(["docker", "create", "--name", consumer, first]);
+    await run(["docker", "rm", consumer]);
+    // The normal retention collector removes by image ID, including aliases.
+    await run(["docker", "image", "rm", "-f", first]);
+    await expect(run(["docker", "image", "inspect", first])).rejects.toThrow("No such image");
+    expect(await run(["docker", "image", "inspect", "--format", "{{.Id}}", tag])).toBe(second);
+    // Negative control: the old export mode reproduces Tangent's failure.
+    const unpinned = await build("unpinned", `type=image,name=${tag},unpack=true`);
+    await build("replacement");
+    await expect(run(["docker", "image", "inspect", unpinned])).rejects.toThrow("No such image");
+  } finally {
+    await run(["docker", "rm", "-f", consumer]).catch(() => {});
+    await run(["docker", "rm", "-fv", builder]).catch(() => {});
+    for (const id of images) await run(["docker", "image", "rm", "-f", id]).catch(() => {});
+    await rm(root, { recursive: true, force: true });
+  }
+}, 120_000);

package/src/harness/built-image.ts

@@ -4,6 +4,12 @@ import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import { canonicalImageReference } from "./component-images.js";
 
+/** Containerd exports replace mutable tags without Docker's dangling-image
+ * retention. Keep each result addressable until the SDK's image GC evicts it. */
+export function containerdImageOutput(reference: string): string {
+  return `type=image,name=${canonicalImageReference(reference)},name-canonical=true,unpack=true`;
+}
+
 export interface Descriptor { digest: string; size: number; mediaType: string; platform?: { os: string; architecture: string } }
 interface Manifest { schemaVersion: number; mediaType: string; config: Descriptor; layers: Descriptor[]; annotations?: Record<string, string> }
 const digest = (bytes: Uint8Array) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;