feat(docker): add docker engine integration

Lazy Docker Engine client on the local socket listing running containers with a per-call timeout; unit tests and e2e tests against a fake Engine socket and real containers.

docker_client.go

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (C) 2026 Bryan Joshua Pedini
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"github.com/moby/moby/api/types/container"
+	"github.com/moby/moby/client"
+)
+
+// dockerHost is the Docker Engine endpoint used in production
+const dockerHost = "unix:///var/run/docker.sock"
+
+// dockerListTimeout bounds every container-list call (the SDK has no default timeout)
+const dockerListTimeout = 10 * time.Second
+
+// ContainerLister is the narrow Docker dependency of the HTTP layer
+type ContainerLister interface {
+	ListRunningContainers(ctx context.Context) ([]container.Summary, error)
+}
+
+// DockerClient wraps the Docker Engine SDK client
+type DockerClient struct {
+	cli     *client.Client
+	log     *slog.Logger
+	timeout time.Duration
+}
+
+// NewDockerClient creates a client for the given Engine host (e.g. unix:///var/run/docker.sock)
+// The connection is lazy: an absent or inaccessible socket only fails individual requests
+func NewDockerClient(host string, log *slog.Logger) (*DockerClient, error) {
+	cli, err := client.New(client.WithHost(host))
+	if err != nil {
+		return nil, fmt.Errorf("create docker client: %w", err)
+	}
+	return &DockerClient{cli: cli, log: log, timeout: dockerListTimeout}, nil
+}
+
+// ListRunningContainers returns the running containers, like `docker ps`
+// The result is never nil, so it serializes as [] when empty
+func (d *DockerClient) ListRunningContainers(ctx context.Context) ([]container.Summary, error) {
+	defer traceFunc(ctx, d.log, "DockerClient.ListRunningContainers")()
+
+	ctx, cancel := context.WithTimeout(ctx, d.timeout)
+	defer cancel()
+
+	// All=false: running containers only
+	res, err := d.cli.ContainerList(ctx, client.ContainerListOptions{})
+	if err != nil {
+		return nil, fmt.Errorf("list containers: %w", err)
+	}
+	items := res.Items
+	if items == nil {
+		items = []container.Summary{}
+	}
+	for _, c := range items {
+		trace(ctx, d.log, "container listed", "id", c.ID, "names", c.Names, "image", c.Image, "state", c.State)
+	}
+	return items, nil
+}
+
+// Close releases the client's resources
+func (d *DockerClient) Close() error {
+	return d.cli.Close()
+}

docker_client_test.go

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (C) 2026 Bryan Joshua Pedini
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// fakeEngine is a minimal Docker Engine API served on a temporary unix socket
+type fakeEngine struct {
+	mu      sync.Mutex
+	status  int
+	body    string
+	hang    bool
+	queries []string
+	host    string
+}
+
+func startFakeEngine(t *testing.T) *fakeEngine {
+	t.Helper()
+	// Keep the socket path short (unix socket paths are limited to ~108 bytes)
+	dir, err := os.MkdirTemp("", "dps")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { os.RemoveAll(dir) })
+	sock := filepath.Join(dir, "docker.sock")
+	ln, err := net.Listen("unix", sock)
+	if err != nil {
+		t.Fatal(err)
+	}
+	f := &fakeEngine{status: http.StatusOK, body: "[]", host: "unix://" + sock}
+	stop := make(chan struct{})
+	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasSuffix(r.URL.Path, "/_ping") {
+			w.Header().Set("Api-Version", "1.47")
+			w.Header().Set("Ostype", "linux")
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("OK"))
+			return
+		}
+		if !strings.HasSuffix(r.URL.Path, "/containers/json") {
+			http.NotFound(w, r)
+			return
+		}
+		f.mu.Lock()
+		f.queries = append(f.queries, r.URL.RawQuery)
+		status, body, hang := f.status, f.body, f.hang
+		f.mu.Unlock()
+		if hang {
+			select {
+			case <-r.Context().Done():
+			case <-stop:
+			}
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(status)
+		w.Write([]byte(body))
+	})}
+	go srv.Serve(ln)
+	t.Cleanup(func() {
+		close(stop)
+		srv.Close()
+	})
+	return f
+}
+
+func (f *fakeEngine) set(status int, body string, hang bool) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.status, f.body, f.hang = status, body, hang
+}
+
+func newTestDockerClient(t *testing.T, host string) *DockerClient {
+	t.Helper()
+	d, err := NewDockerClient(host, traceDiscard())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { d.Close() })
+	return d
+}
+
+func TestDockerClientSuccess(t *testing.T) {
+	t.Parallel()
+	engine := startFakeEngine(t)
+	want := makeContainers(3)
+	body, _ := json.Marshal(want)
+	engine.set(http.StatusOK, string(body), false)
+
+	log, buf := newTestLogger(LevelTrace)
+	d, err := NewDockerClient(engine.host, log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer d.Close()
+	got, err := d.ListRunningContainers(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 3 || got[0].ID != want[0].ID || got[2].Names[0] != "/c2" || got[1].Labels["index"] != "1" {
+		t.Fatalf("got %+v", got)
+	}
+	// docker ps semantics: no all=1
+	engine.mu.Lock()
+	queries := engine.queries
+	engine.mu.Unlock()
+	if len(queries) != 1 || strings.Contains(queries[0], "all") {
+		t.Fatalf("queries = %q", queries)
+	}
+	if !strings.Contains(buf.String(), `msg="container listed" id=`+want[0].ID) ||
+		!strings.Contains(buf.String(), `func=DockerClient.ListRunningContainers`) {
+		t.Fatalf("missing trace:\n%s", buf.String())
+	}
+}
+
+func TestDockerClientEmpty(t *testing.T) {
+	t.Parallel()
+	engine := startFakeEngine(t)
+	d := newTestDockerClient(t, engine.host)
+	for _, body := range []string{"[]", "null"} {
+		engine.set(http.StatusOK, body, false)
+		got, err := d.ListRunningContainers(context.Background())
+		if err != nil {
+			t.Fatalf("%s: %v", body, err)
+		}
+		if got == nil || len(got) != 0 {
+			t.Fatalf("%s: expected empty non-nil slice, got %#v", body, got)
+		}
+		b, _ := json.Marshal(got)
+		if string(b) != "[]" {
+			t.Fatalf("%s: serialized as %s", body, b)
+		}
+	}
+}
+
+func TestDockerClientDaemonError(t *testing.T) {
+	t.Parallel()
+	engine := startFakeEngine(t)
+	d := newTestDockerClient(t, engine.host)
+	engine.set(http.StatusInternalServerError, `{"message":"daemon exploded"}`, false)
+	if _, err := d.ListRunningContainers(context.Background()); err == nil || !strings.Contains(err.Error(), "daemon exploded") {
+		t.Fatalf("got %v", err)
+	}
+	engine.set(http.StatusOK, `{not json`, false)
+	if _, err := d.ListRunningContainers(context.Background()); err == nil {
+		t.Fatal("expected decode error")
+	}
+}
+
+func TestDockerClientTimeout(t *testing.T) {
+	t.Parallel()
+	engine := startFakeEngine(t)
+	d := newTestDockerClient(t, engine.host)
+	d.timeout = 100 * time.Millisecond
+	engine.set(0, "", true)
+	start := time.Now()
+	_, err := d.ListRunningContainers(context.Background())
+	if err == nil {
+		t.Fatal("expected timeout error")
+	}
+	if elapsed := time.Since(start); elapsed > 5*time.Second {
+		t.Fatalf("timeout not applied: %v", elapsed)
+	}
+	if d := dockerListTimeout; d != 10*time.Second {
+		t.Fatalf("production timeout = %v", d)
+	}
+}
+
+func TestDockerClientMissingSocket(t *testing.T) {
+	t.Parallel()
+	// Creation is lazy: a missing socket only fails the request
+	d := newTestDockerClient(t, "unix://"+filepath.Join(t.TempDir(), "absent.sock"))
+	if _, err := d.ListRunningContainers(context.Background()); err == nil {
+		t.Fatal("expected connection error")
+	}
+}
+
+func TestNewDockerClientInvalidHost(t *testing.T) {
+	t.Parallel()
+	if _, err := NewDockerClient("not a host", traceDiscard()); err == nil || !strings.Contains(err.Error(), "create docker client") {
+		t.Fatalf("got %v", err)
+	}
+	if dockerHost != "unix:///var/run/docker.sock" {
+		t.Fatalf("dockerHost = %q", dockerHost)
+	}
+}

e2e/tests/host/containers-real.spec.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (C) 2026 Bryan Joshua Pedini
+
+/**
+ * PLAN §12 core items 6, 7, 12 against the real Docker Engine: uniquely named, labelled alpine
+ * containers are started, stopped, restarted and removed, and GET /api/v1/containers (Playwright
+ * request and real curl) must reflect `docker ps` for exactly those containers. Assertions only
+ * look at the suite's own names/labels — the host runs unrelated containers.
+ */
+import {
+  test,
+  expect,
+  assertDbInvariants,
+  expectContainersResponse,
+  readOperations,
+  type HttpClient,
+  type RealDocker,
+  type ServerHandle,
+  type TestContainer,
+} from '../../harness';
+
+interface ApiContainer {
+  Id: string;
+  Names: string[];
+  Image: string;
+  Command: string;
+  Labels: Record<string, string>;
+  State: string;
+  Status: string;
+}
+
+/** Our containers in the API response, via Playwright and via curl (both must agree). */
+async function ownViaApi(http: HttpClient, server: ServerHandle, token: string, docker: RealDocker): Promise<Map<string, ApiContainer>> {
+  const pw = expectContainersResponse<ApiContainer>(await http.get(server.url(), { token }));
+  const cu = await http.curl({ url: server.url(), token });
+  expect(cu.exitCode).toBe(0);
+  const viaCurl = expectContainersResponse<ApiContainer>(cu);
+  const own = (list: ApiContainer[]) => list.filter((c) => c.Labels?.['dpsapi.e2e.test'] === docker.testKey);
+  const a = own(pw).map((c) => c.Id).sort();
+  const b = own(viaCurl).map((c) => c.Id).sort();
+  expect(b, 'curl and Playwright see the same containers').toEqual(a);
+  // never stopped containers, for anyone
+  expect(pw.filter((c) => c.State !== 'running').map((c) => c.Names), 'only running containers are listed').toEqual([]);
+  return new Map(own(pw).map((c) => [c.Id, c]));
+}
+
+async function expectApiMatchesDocker(http: HttpClient, server: ServerHandle, token: string, docker: RealDocker, expected: TestContainer[]): Promise<Map<string, ApiContainer>> {
+  const api = await ownViaApi(http, server, token, docker);
+  const running = (await docker.runningIds()).sort();
+  expect([...api.keys()].sort(), 'API equals docker ps for our label').toEqual(running);
+  expect([...api.keys()].sort(), 'API equals the expected set').toEqual(expected.map((c) => c.id).sort());
+  return api;
+}
+
+test('started, stopped, restarted and removed containers are reflected (Playwright request and curl)', async ({ cli, startServer, http, docker }) => {
+  test.setTimeout(120_000);
+  const token = await cli.tokenNew('real docker');
+  const [sleeper, looper, tailer] = await Promise.all([
+    docker.run({ suffix: 'sleeper', command: ['sleep', '3600'], labels: { 'com.example.role': 'sleeper', 'unicode.label': 'naïve ☃' } }),
+    docker.run({ suffix: 'looper', command: ['sh', '-c', 'trap "exit 0" TERM; while :; do sleep 1; done'], labels: { 'com.example.role': 'looper' }, env: { FOO: 'bar' } }),
+    docker.run({ suffix: 'tail.er_2', command: ['tail', '-f', '/dev/null'], labels: { 'empty.value': '' } }),
+  ]);
+  const server = await startServer({ docker: 'real', logLevel: 'DEBUG' });
+
+  const api = await expectApiMatchesDocker(http, server, token, docker, [sleeper, looper, tailer]);
+  for (const c of [sleeper, looper, tailer]) {
+    const got = api.get(c.id)!;
+    expect(got.Names).toEqual([`/${c.name}`]);
+    expect(got.Image).toBe('alpine:3.22');
+    expect(got.State).toBe('running');
+    expect(got.Status).toMatch(/^Up /);
+    for (const [k, v] of Object.entries(c.labels)) expect(got.Labels[k]).toBe(v);
+  }
+  expect(api.get(sleeper.id)!.Command).toContain('sleep 3600');
+  expect(api.get(tailer.id)!.Command).toContain('tail -f /dev/null');
+
+  await docker.stop(sleeper);
+  await expectApiMatchesDocker(http, server, token, docker, [looper, tailer]);
+  expect((await docker.listOwn()).find((c) => c.name === sleeper.name)!.state, 'stopped container still exists').toBe('exited');
+
+  await docker.remove(looper);
+  await expectApiMatchesDocker(http, server, token, docker, [tailer]);
+
+  await docker.start(sleeper);
+  await expectApiMatchesDocker(http, server, token, docker, [sleeper, tailer]);
+
+  await docker.remove(sleeper);
+  await docker.remove(tailer);
+  await expectApiMatchesDocker(http, server, token, docker, []);
+  expect(await docker.listOwn()).toEqual([]);
+
+  expect((await server.stop()).exitCode).toBe(0);
+  // 5 checkpoints × 2 clients
+  expect(readOperations(server.dbPath)).toHaveLength(10);
+  expect(server.logs().filter({ msg: 'docker request finished' }).every((r) => r.attrs.ok === 'true')).toBe(true);
+  assertDbInvariants(server.dbPath, { operationCount: 10 });
+});
+
+test('moderate real set: 15 containers with varied names, labels and commands', async ({ cli, startServer, http, docker }) => {
+  test.setTimeout(150_000);
+  const token = await cli.tokenNew();
+  const commands = [['sleep', '3600'], ['tail', '-f', '/dev/null'], ['sh', '-c', 'while :; do sleep 2; done'], ['top', '-b', '-d', '5']];
+  const set = await docker.runMany(15, (i) => ({
+    suffix: `m${String(i).padStart(2, '0')}${i % 3 === 0 ? '.dot' : i % 3 === 1 ? '_under' : '-dash'}`,
+    command: commands[i % commands.length],
+    labels: { 'com.example.index': String(i), [`com.example.k${i}`]: `v${i}` },
+  }));
+  const server = await startServer({ docker: 'real' });
+  const api = await expectApiMatchesDocker(http, server, token, docker, set);
+  for (const [i, c] of set.entries()) {
+    const got = api.get(c.id)!;
+    expect(got.Names).toEqual([`/${c.name}`]);
+    expect(got.Labels['com.example.index']).toBe(String(i));
+  }
+  // stop a third of them
+  const stopped = set.filter((_, i) => i % 3 === 0);
+  await Promise.all(stopped.map((c) => docker.stop(c, 1)));
+  await expectApiMatchesDocker(http, server, token, docker, set.filter((c) => !stopped.includes(c)));
+  // remove everything
+  await Promise.all(set.map((c) => docker.remove(c)));
+  await expectApiMatchesDocker(http, server, token, docker, []);
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(6);
+});

e2e/tests/host/docker-backend.spec.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (C) 2026 Bryan Joshua Pedini
+
+/**
+ * PLAN §12 core item 12 and the Docker-socket matrix: empty / one / large container sets
+ * (FakeDocker), inaccessible / missing / failing / hanging Engine → 500 with a generic body and no
+ * internal details, recovery once the Engine recovers, and running-only (`docker ps`) semantics.
+ */
+import {
+  test,
+  expect,
+  assertDbInvariants,
+  expectContainersResponse,
+  expectErrorResponse,
+  expectNoInternalDetails,
+  makeContainerSummary,
+  pollUntil,
+  readOperations,
+  type ContainerSummary,
+} from '../../harness';
+
+test('no running containers → 200 with exactly []', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  server.fakeDocker!.empty();
+  const pw = await http.get(server.url(), { token: tok });
+  expect(expectContainersResponse(pw)).toEqual([]);
+  expect(pw.body).toBe('[]');
+  expect(pw.headers['content-length']).toBe('2');
+  const c = await http.curl({ url: server.url(), token: tok });
+  expect(c.body).toBe('[]');
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(2);
+});
+
+test('the Engine is asked for running containers only (GET /containers/json without all)', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  expectContainersResponse(await http.get(server.url('/api/v1/containers?all=true'), { token: tok }));
+  expect((await server.stop()).exitCode).toBe(0);
+  const lists = server.fakeDocker!.requests.filter((r) => r.path === '/containers/json');
+  expect(lists).toHaveLength(1);
+  expect(lists[0].method).toBe('GET');
+  expect(new URLSearchParams(lists[0].query).get('all') ?? '0').toMatch(/^(0|false)$/);
+  expect(server.fakeDocker!.stats.other, 'no other Engine endpoints are called').toBe(0);
+});
+
+test('one container: Engine summary fields are passed through', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  const c: ContainerSummary = makeContainerSummary(0, undefined, {
+    Names: ['/web-1'],
+    Image: 'nginx:1.29',
+    Command: 'nginx -g "daemon off;"',
+    Labels: { 'com.example.role': 'web', 'unicode.label': 'naïve ☃' },
+    Ports: [{ IP: '127.0.0.1', PrivatePort: 80, PublicPort: 8080, Type: 'tcp' }],
+    Status: 'Up 5 minutes',
+  });
+  server.fakeDocker!.setContainers([c]);
+  const [got] = expectContainersResponse(await http.get(server.url(), { token: tok }));
+  expect(got).toMatchObject({ Id: c.Id, Names: c.Names, Image: c.Image, ImageID: c.ImageID, Command: c.Command, Created: c.Created, Labels: c.Labels, State: 'running', Status: c.Status });
+  expect(got.Ports).toEqual([{ IP: '127.0.0.1', PrivatePort: 80, PublicPort: 8080, Type: 'tcp' }]);
+  expect((await server.stop()).exitCode).toBe(0);
+});
+
+test('large container set: 2000 summaries, complete and in order (Playwright and curl)', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  server.fakeDocker!.many(2000);
+  const ids = server.fakeDocker!.containers.map((c) => c.Id);
+  const pw = expectContainersResponse<ContainerSummary>(await http.get(server.url(), { token: tok }));
+  expect(pw.map((c) => c.Id)).toEqual(ids);
+  expect(pw.every((c) => c.State === 'running')).toBe(true);
+  const cu = await http.curl({ url: server.url(), token: tok });
+  expect(expectContainersResponse<ContainerSummary>(cu).map((c) => c.Names[0])).toEqual(ids.map((_, i) => `/fake-${i}`));
+  expect(cu.bodyBuffer.length).toBeGreaterThan(500_000);
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(2);
+});
+
+test('Engine failures → 500 with the generic body only; details stay in the ERROR log', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer({ logLevel: 'INFO' });
+  const f = server.fakeDocker!;
+  const modes: Array<[string, () => void]> = [
+    ['500 with internal message', () => f.error500('boom: /var/lib/docker/overlay2 sqlite secret path')],
+    ['404 (API mismatch)', () => f.error(404, 'page not found')],
+    ['503', () => f.error(503, 'engine starting')],
+    ['connection dropped mid-request', () => f.destroy()],
+    ['malformed JSON', () => f.badJson('{"not":"an array"')],
+    ['JSON of the wrong shape', () => f.badJson('{"Id":"x"}')],
+    ['HTML instead of JSON', () => f.badJson('<html>proxy error</html>')],
+  ];
+  for (const [name, apply] of modes) {
+    await test.step(name, async () => {
+      apply();
+      const r = await http.get(server.url(), { token: tok });
+      expectErrorResponse(r, 500);
+      expectNoInternalDetails(r.body);
+      expect(Object.keys(r.headers).filter((h) => /^(api-version|docker|ostype|server)/i.test(h)), 'no Engine headers forwarded').toEqual([]);
+    });
+  }
+  f.many(3);
+  expect(expectContainersResponse(await http.get(server.url(), { token: tok }))).toHaveLength(3);
+  expect((await server.stop()).exitCode).toBe(0);
+  const errors = server.logs().filter({ level: 'ERROR' });
+  expect(errors.map((e) => e.msg)).toEqual(modes.map(() => 'docker request failed'));
+  expect(errors[0].attrs.error).toContain('boom');
+  expect(server.logs().requests().map((r) => r.attrs.status)).toEqual([...modes.map(() => '500'), '200']);
+  expect(readOperations(server.dbPath)).toHaveLength(modes.length + 1);
+  assertDbInvariants(server.dbPath);
+});
+
+test('socket inaccessible (EACCES) and missing (ENOENT): server starts, requests → 500, no details', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  for (const docker of ['inaccessible', 'missing'] as const) {
+    await test.step(docker, async () => {
+      const server = await startServer({ docker });
+      const r = await http.get(server.url(), { token: tok });
+      expectErrorResponse(r, 500);
+      expectNoInternalDetails(r.body);
+      const c = await http.curl({ url: server.url(), token: tok });
+      expectErrorResponse(c, 500);
+      expectErrorResponse(await http.get(server.url()), 401);
+      expect((await server.stop()).exitCode).toBe(0);
+      const err = server.logs().filter({ level: 'ERROR', msg: 'docker request failed' });
+      expect(err).toHaveLength(2);
+      expect(err[0].attrs.error).toMatch(docker === 'inaccessible' ? /permission denied/ : /no such file or directory/);
+    });
+  }
+});
+
+test('temporarily failing Engine: errors while failing, recovery afterwards', async ({ cli, startServer, http }) => {
+  const tok = await cli.tokenNew();
+  const server = await startServer();
+  const f = server.fakeDocker!.many(2).flaky(3);
+  const statuses: number[] = [];
+  for (let i = 0; i < 5; i++) statuses.push((await http.get(server.url(), { token: tok })).status);
+  expect(statuses).toEqual([500, 500, 500, 200, 200]);
+  // full outage then recovery
+  f.destroy();
+  expectErrorResponse(await http.get(server.url(), { token: tok }), 500);
+  f.many(1);
+  expect(expectContainersResponse(await http.get(server.url(), { token: tok }))).toHaveLength(1);
+  expect((await server.stop()).exitCode).toBe(0);
+  expect(readOperations(server.dbPath)).toHaveLength(7);
+});
+
+test('hung Engine: request bounded by the 10 s Docker timeout, server stays responsive, graceful shutdown waits for it', async ({ cli, startServer, http }) => {
+  test.setTimeout(90_000);
+  const tok = await cli.tokenNew();
+  const server = await startServer({ logLevel: 'DEBUG' });
+  const f = server.fakeDocker!.hang();
+  const t0 = performance.now();
+  const hung = http.get(server.url(), { token: tok, timeoutMs: 30_000 });
+  await pollUntil('the hung list call to reach the fake', () => (f.listCalls() >= 1 ? true : undefined));
+  // other requests are served meanwhile
+  const quick = await http.get(server.url('/elsewhere'));
+  expectErrorResponse(quick, 404);
+  expect(quick.durationMs).toBeLessThan(2000);
+  const r = await hung;
+  const elapsed = performance.now() - t0;
+  expectErrorResponse(r, 500);
+  expect(elapsed, 'bounded by the 10 s Engine timeout').toBeGreaterThan(9_500);
+  expect(elapsed).toBeLessThan(15_000);
+  expect(server.logs().find({ level: 'ERROR', msg: 'docker request failed' })!.attrs.error).toMatch(/context deadline exceeded|timeout/i);
+
+  // second hung request in flight while SIGTERM arrives: shutdown drains it and exits 0
+  const hung2 = http.get(server.url(), { token: tok, timeoutMs: 30_000 });
+  await pollUntil('second hung call', () => (f.listCalls() >= 2 ? true : undefined));
+  const stopping = server.stop('SIGTERM', { timeoutMs: 25_000 });
+  expectErrorResponse(await hung2, 500);
+  const exit = await stopping;
+  expect(exit.exitCode).toBe(0);
+  expect(server.logs().has({ msg: 'server stopped' })).toBe(true);
+  expect(readOperations(server.dbPath)).toHaveLength(2);
+});