From 09fbc1aca7a0df2e66dc556215d3686df938105f Mon Sep 17 00:00:00 2001
From: Andrew Martinez <amartinez@cloudflare.com>
Date: Wed, 27 May 2026 17:58:42 -0500
Subject: [PATCH 1/2] containers: add setLabels API to mutate container labels
 at runtime

Adds a new container.setLabels(labels: Record<string, string>): Promise<void>
JS method, gated behind the workerdExperimental compatibility flag, backed by
a new capnp RPC method setLabels @15 (labels :List(Label)) on the Container
interface. Each call fully replaces the existing label set; the container
must be running. Label-name and label-value validation is shared with start()
via a new requireValidLabels() helper.
---
 src/workerd/api/container.c++                 | 41 +++++++++++++++----
 src/workerd/api/container.h                   |  3 ++
 src/workerd/io/container.capnp                |  3 ++
 .../experimental/index.d.ts                   |  1 +
 .../generated-snapshot/experimental/index.ts  |  1 +
 5 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/src/workerd/api/container.c++ b/src/workerd/api/container.c++
index 4e1fb2eebb2..03b3bb47b10 100644
--- a/src/workerd/api/container.c++
+++ b/src/workerd/api/container.c++
@@ -54,6 +54,21 @@ kj::Array<kj::byte> emptyByteArray() {
   return kj::heapArray<kj::byte>(0);
 }
 
+void requireValidLabels(jsg::Dict<kj::String>& labels) {
+  for (auto i: kj::indices(labels.fields)) {
+    auto& field = labels.fields[i];
+    JSG_REQUIRE(field.name.size() > 0, Error, "Label names cannot be empty");
+    for (auto c: field.name) {
+      JSG_REQUIRE(static_cast<kj::byte>(c) >= 0x20, Error,
+          "Label names cannot contain control characters (index ", i, ")");
+    }
+    for (auto c: field.value) {
+      JSG_REQUIRE(static_cast<kj::byte>(c) >= 0x20, Error,
+          "Label values cannot contain control characters (index ", i, ")");
+    }
+  }
+}
+
 capnp::ByteStream::Client makeExecPipe(
     capnp::ByteStreamFactory& factory, kj::Own<kj::AsyncOutputStream> output) {
   return factory.kjToCapnp(capnp::ExplicitEndOutputStream::wrap(kj::mv(output), []() {}));
@@ -237,18 +252,10 @@ void Container::start(jsg::Lock& js, jsg::Optional<StartupOptions> maybeOptions)
   }
 
   KJ_IF_SOME(labels, options.labels) {
+    requireValidLabels(labels);
     auto list = req.initLabels(labels.fields.size());
     for (auto i: kj::indices(labels.fields)) {
       auto& field = labels.fields[i];
-      JSG_REQUIRE(field.name.size() > 0, Error, "Label names cannot be empty");
-      for (auto c: field.name) {
-        JSG_REQUIRE(static_cast<kj::byte>(c) >= 0x20, Error,
-            "Label names cannot contain control characters (index ", i, ")");
-      }
-      for (auto c: field.value) {
-        JSG_REQUIRE(static_cast<kj::byte>(c) >= 0x20, Error,
-            "Label values cannot contain control characters (index ", i, ")");
-      }
       list[i].setName(field.name);
       list[i].setValue(field.value);
     }
@@ -284,6 +291,22 @@ void Container::start(jsg::Lock& js, jsg::Optional<StartupOptions> maybeOptions)
   running = true;
 }
 
+jsg::Promise<void> Container::setLabels(jsg::Lock& js, jsg::Dict<kj::String> labels) {
+  JSG_REQUIRE(running, Error, "setLabels() cannot be called on a container that is not running.");
+
+  requireValidLabels(labels);
+
+  auto req = rpcClient->setLabelsRequest();
+  auto list = req.initLabels(labels.fields.size());
+  for (auto i: kj::indices(labels.fields)) {
+    auto& field = labels.fields[i];
+    list[i].setName(field.name);
+    list[i].setValue(field.value);
+  }
+
+  return IoContext::current().awaitIo(js, req.sendIgnoringResult());
+}
+
 jsg::Promise<kj::Maybe<Container::Info>> Container::inspect(jsg::Lock& js) {
   return IoContext::current().awaitIo(js, rpcClient->inspectRequest().send(),
       [](jsg::Lock& js,
diff --git a/src/workerd/api/container.h b/src/workerd/api/container.h
index 2bbd745a188..a86e330d133 100644
--- a/src/workerd/api/container.h
+++ b/src/workerd/api/container.h
@@ -258,6 +258,8 @@ class Container: public jsg::Object {
 
   jsg::Promise<kj::Maybe<Info>> inspect(jsg::Lock& js);
 
+  jsg::Promise<void> setLabels(jsg::Lock& js, jsg::Dict<kj::String> labels);
+
   // TODO(containers): listenTcp()
 
   JSG_RESOURCE_TYPE(Container, CompatibilityFlags::Reader flags) {
@@ -278,6 +280,7 @@ class Container: public jsg::Object {
       JSG_METHOD(exec);
       JSG_METHOD(interceptOutboundTcp);
       JSG_METHOD(inspect);
+      JSG_METHOD(setLabels);
     }
   }
 
diff --git a/src/workerd/io/container.capnp b/src/workerd/io/container.capnp
index 7fdf41005af..9d8eeac5f26 100644
--- a/src/workerd/io/container.capnp
+++ b/src/workerd/io/container.capnp
@@ -253,6 +253,9 @@ interface Container @0x9aaceefc06523bca {
   inspect @14 () -> (info :InspectInfo);
   # Returns information about the container, or `none` if the container has not been started.
 
+  setLabels @15 (labels :List(Label));
+  # Replaces the container's current label set with the provided list.
+
   struct InspectInfo {
     union {
       none @0 :Void;
diff --git a/types/generated-snapshot/experimental/index.d.ts b/types/generated-snapshot/experimental/index.d.ts
index 81bdc3137ab..dbfa432d1b7 100755
--- a/types/generated-snapshot/experimental/index.d.ts
+++ b/types/generated-snapshot/experimental/index.d.ts
@@ -4004,6 +4004,7 @@ interface Container {
   exec(cmd: string[], options?: ContainerExecOptions): Promise<ExecProcess>;
   interceptOutboundTcp(addr: string, binding: Fetcher): Promise<void>;
   inspect(): Promise<ContainerInfo | null>;
+  setLabels(labels: Record<string, string>): Promise<void>;
 }
 interface ContainerDirectorySnapshot {
   id: string;
diff --git a/types/generated-snapshot/experimental/index.ts b/types/generated-snapshot/experimental/index.ts
index 2ac8e8855d4..723e503ec27 100755
--- a/types/generated-snapshot/experimental/index.ts
+++ b/types/generated-snapshot/experimental/index.ts
@@ -4010,6 +4010,7 @@ export interface Container {
   exec(cmd: string[], options?: ContainerExecOptions): Promise<ExecProcess>;
   interceptOutboundTcp(addr: string, binding: Fetcher): Promise<void>;
   inspect(): Promise<ContainerInfo | null>;
+  setLabels(labels: Record<string, string>): Promise<void>;
 }
 export interface ContainerDirectorySnapshot {
   id: string;

From 5ba0ea4ef6f4f7c2bd048f75ea6b1ce812137266 Mon Sep 17 00:00:00 2001
From: Andrew Martinez <amartinez@cloudflare.com>
Date: Wed, 27 May 2026 22:29:26 -0500
Subject: [PATCH 2/2] containers: store local labels in memory

Keep the local ContainerClient label state entirely in memory so setLabels() reflects the real runtime behavior by actually replacing the current label set, without depending on Docker object labels.
---
 src/workerd/io/container.capnp                |   3 +-
 src/workerd/server/container-client.c++       |  70 +++--
 src/workerd/server/container-client.h         |   7 +
 .../server/tests/container-client/test.js     | 289 +++++++++++++++++-
 4 files changed, 329 insertions(+), 40 deletions(-)

diff --git a/src/workerd/io/container.capnp b/src/workerd/io/container.capnp
index 9d8eeac5f26..441577ae957 100644
--- a/src/workerd/io/container.capnp
+++ b/src/workerd/io/container.capnp
@@ -261,7 +261,8 @@ interface Container @0x9aaceefc06523bca {
       none @0 :Void;
       started :group {
         labels @1 :List(Label);
-        # Echo of StartParams.labels. Empty list means start() was called with no labels.
+        # Current in-memory label set. Initially populated from StartParams.labels and replaced by
+        # setLabels(). Empty list means the current set is empty.
       }
     }
   }
diff --git a/src/workerd/server/container-client.c++ b/src/workerd/server/container-client.c++
index 69f2f0c6201..50f9e500166 100644
--- a/src/workerd/server/container-client.c++
+++ b/src/workerd/server/container-client.c++
@@ -49,10 +49,6 @@ constexpr kj::StringPtr SNAPSHOT_CLONE_VOLUME_PREFIX = "workerd-snap-clone-"_kj;
 constexpr kj::StringPtr CONTAINER_SNAPSHOT_IMAGE_PREFIX = "workerd-container-snap-"_kj;
 constexpr kj::StringPtr SNAPSHOT_VOLUME_CREATED_AT_LABEL = "dev.workerd.snapshot-created-at"_kj;
 
-// Prefix applied to user-supplied labels when writing them to the Docker container, and
-// stripped back out when reading them via inspect(). Lets us distinguish labels the worker
-// set via start() from labels that came from the image (via Dockerfile LABEL) or engine.
-constexpr kj::StringPtr WORKERD_LABEL_PREFIX = "workerd-"_kj;
 constexpr auto SNAPSHOT_STALE_AGE = 30 * kj::DAYS;
 
 // Maximum size of a snapshot tar archive held in memory during snapshot create/restore.
@@ -1545,20 +1541,11 @@ kj::Promise<kj::Maybe<ContainerClient::InspectResponse>> ContainerClient::inspec
   bool running = status == "running" || status == "restarting";
 
   kj::Vector<Label> labels;
-  if (jsonRoot.hasConfig() && jsonRoot.getConfig().hasLabels()) {
-    auto labelsJson = jsonRoot.getConfig().getLabels();
-    if (labelsJson.isObject()) {
-      for (auto field: labelsJson.getObject()) {
-        kj::StringPtr name = field.getName();
-        if (!name.startsWith(WORKERD_LABEL_PREFIX)) continue;
-        auto value = field.getValue();
-        JSG_REQUIRE(value.isString(), Error, "Malformed ContainerInspect label value");
-        labels.add(Label{
-          .name = kj::str(name.slice(WORKERD_LABEL_PREFIX.size())),
-          .value = kj::str(value.getString()),
-        });
-      }
-    }
+  for (auto& entry: currentLabels) {
+    labels.add(Label{
+      .name = kj::str(entry.key),
+      .value = kj::str(entry.value),
+    });
   }
 
   co_return InspectResponse{.isRunning = running, .labels = labels.releaseAsArray()};
@@ -1686,17 +1673,6 @@ kj::Promise<void> ContainerClient::createContainer(kj::StringPtr effectiveImage,
     jsonEnv.set(envSize + i, defaultEnv[i]);
   }
 
-  // Pass user-supplied labels as Docker object labels, prefixed so we can distinguish
-  // them from image/engine labels when reading back via inspect().
-  if (params.hasLabels()) {
-    auto lbls = params.getLabels();
-    auto labelsObj = jsonRoot.initLabels().initObject(lbls.size());
-    for (auto i: kj::zeroTo(lbls.size())) {
-      labelsObj[i].setName(kj::str(WORKERD_LABEL_PREFIX, lbls[i].getName()));
-      labelsObj[i].initValue().setString(lbls[i].getValue());
-    }
-  }
-
   auto hostConfig = jsonRoot.initHostConfig();
   // We need to set a restart policy to avoid having ambiguous states
   // where the container we're managing is stuck at "exited" state.
@@ -2190,6 +2166,9 @@ kj::Promise<void> ContainerClient::status(StatusContext context) {
     isRunning = info.isRunning;
   }
   containerStarted.store(isRunning, std::memory_order_release);
+  if (!isRunning) {
+    currentLabels.clear();
+  }
   containerSidecarStarted.store(false, std::memory_order_release);
   this->sidecarIngressHostPort = kj::none;
 
@@ -2209,6 +2188,24 @@ kj::Promise<void> ContainerClient::status(StatusContext context) {
   context.getResults().setRunning(isRunning);
 }
 
+kj::Promise<void> ContainerClient::setLabels(SetLabelsContext context) {
+  auto [ready, done] = getRpcTurn();
+  co_await ready;
+  KJ_DEFER(done->fulfill());
+
+  JSG_REQUIRE(containerStarted.load(std::memory_order_acquire), Error,
+      "setLabels() requires a running container.");
+
+  auto params = context.getParams();
+  auto newLabels = params.getLabels();
+  currentLabels.clear();
+  for (auto i: kj::zeroTo(newLabels.size())) {
+    currentLabels.insert(kj::str(newLabels[i].getName()), kj::str(newLabels[i].getValue()));
+  }
+
+  co_return;
+}
+
 kj::Promise<void> ContainerClient::inspect(InspectContext context) {
   auto maybeResp = co_await inspectContainer();
   auto info = context.getResults().initInfo();
@@ -2247,6 +2244,14 @@ kj::Promise<void> ContainerClient::start(StartContext context) {
 
   internetEnabled = params.getEnableInternet();
 
+  currentLabels.clear();
+  if (params.hasLabels()) {
+    auto lbls = params.getLabels();
+    for (auto i: kj::zeroTo(lbls.size())) {
+      currentLabels.insert(kj::str(lbls[i].getName()), kj::str(lbls[i].getValue()));
+    }
+  }
+
   kj::String effectiveImage = kj::str(imageName);
   if (params.hasContainerSnapshotId()) {
     auto snapshotId = parseSnapshotId(params.getContainerSnapshotId());
@@ -2328,7 +2333,10 @@ kj::Promise<void> ContainerClient::monitor(MonitorContext context) {
   JSG_REQUIRE(containerStarted.load(std::memory_order_acquire), Error, "Container failed to start");
 
   auto results = context.getResults();
-  KJ_DEFER(containerStarted.store(false, std::memory_order_release));
+  KJ_DEFER({
+    containerStarted.store(false, std::memory_order_release);
+    currentLabels.clear();
+  });
 
   auto endpoint = kj::str("/containers/", containerName, "/wait");
   auto response = co_await dockerApiRequest(
@@ -2357,6 +2365,8 @@ kj::Promise<void> ContainerClient::destroy(DestroyContext context) {
   // in the destructor), or on the next start() if state is inconsistent (e.g. workerd
   // restart left an orphaned sidecar; status() recovery handles that case).
   co_await destroyContainer();
+  containerStarted.store(false, std::memory_order_release);
+  currentLabels.clear();
 }
 
 kj::Promise<void> ContainerClient::signal(SignalContext context) {
diff --git a/src/workerd/server/container-client.h b/src/workerd/server/container-client.h
index 1cc6c244bd2..899cc253ab9 100644
--- a/src/workerd/server/container-client.h
+++ b/src/workerd/server/container-client.h
@@ -88,6 +88,7 @@ class ContainerClient final: public rpc::Container::Server, public kj::Refcounte
   kj::Promise<void> snapshotDirectory(SnapshotDirectoryContext context) override;
   kj::Promise<void> snapshotContainer(SnapshotContainerContext context) override;
   kj::Promise<void> inspect(InspectContext context) override;
+  kj::Promise<void> setLabels(SetLabelsContext context) override;
 
   kj::Own<ContainerClient> addRef();
 
@@ -246,6 +247,12 @@ class ContainerClient final: public rpc::Container::Server, public kj::Refcounte
   std::atomic_bool egressListenerStarted = false;
   std::atomic_bool caCertInjected = false;
 
+  // Volatile in-memory label set for this container. Populated from StartParams.labels when
+  // start() runs, replaced wholesale by setLabels(), and cleared when the container stops.
+  // Labels are not recovered when a fresh ContainerClient reconnects to an already-running
+  // local Docker container.
+  kj::HashMap<kj::String, kj::String> currentLabels;
+
   // Writable clone volumes currently owned by the app container, or by an in-flight start()
   // that still needs failure cleanup.
   kj::Vector<kj::String> snapshotClones;
diff --git a/src/workerd/server/tests/container-client/test.js b/src/workerd/server/tests/container-client/test.js
index 17253588701..d0882c01be5 100644
--- a/src/workerd/server/tests/container-client/test.js
+++ b/src/workerd/server/tests/container-client/test.js
@@ -661,6 +661,200 @@ export class DurableObjectExample extends DurableObject {
     });
   }
 
+  async testSetLabels() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({ enableInternet: true });
+    const monitor = container.monitor().catch((_err) => {});
+    await this.waitUntilContainerIsHealthy();
+
+    const newLabels = { customer: 'figma', tier: 'enterprise' };
+    await container.setLabels(newLabels);
+
+    const info = await container.inspect();
+    assert.deepStrictEqual(info.labels, newLabels);
+
+    await container.destroy();
+    await monitor;
+  }
+
+  async testSetLabelsReplaces() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({ enableInternet: true, labels: { a: '1', b: '2' } });
+    const monitor = container.monitor().catch((_err) => {});
+    await this.waitUntilContainerIsHealthy();
+
+    await container.setLabels({ c: '3' });
+
+    const info = await container.inspect();
+    assert.deepStrictEqual(info.labels, { c: '3' });
+
+    await container.destroy();
+    await monitor;
+  }
+
+  async testSetLabelsClearsAll() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({ enableInternet: true, labels: { a: '1' } });
+    const monitor = container.monitor().catch((_err) => {});
+    await this.waitUntilContainerIsHealthy();
+
+    await container.setLabels({});
+
+    const info = await container.inspect();
+    assert.deepStrictEqual(info.labels, {});
+
+    await container.destroy();
+    await monitor;
+  }
+
+  async testSetLabelsBeforeStart() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    assert.throws(() => container.setLabels({ k: 'v' }), {
+      message:
+        /setLabels\(\) cannot be called on a container that is not running/,
+    });
+  }
+
+  async testSetLabelsAfterDestroy() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({ enableInternet: true });
+    const monitor = container.monitor().catch((_err) => {});
+    await this.waitUntilContainerIsHealthy();
+    await container.destroy();
+    await monitor;
+
+    assert.strictEqual(container.running, false);
+    assert.throws(() => container.setLabels({ k: 'v' }), {
+      message:
+        /setLabels\(\) cannot be called on a container that is not running/,
+    });
+  }
+
+  async testSetLabelsAfterDestroyWithoutMonitor() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({ enableInternet: true, labels: { a: '1' } });
+    await this.waitUntilContainerIsHealthy();
+
+    await container.destroy();
+    await assert.rejects(() => container.setLabels({ k: 'v' }), {
+      message: /setLabels\(\) requires a running container/,
+    });
+
+    // Clear the JS wrapper's running state after intentionally skipping monitor()
+    // before the setLabels() assertion above.
+    await container.monitor().catch((_err) => {});
+    assert.strictEqual(container.running, false);
+  }
+
+  async testSetLabelsValidation() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({ enableInternet: true });
+    const monitor = container.monitor().catch((_err) => {});
+    await this.waitUntilContainerIsHealthy();
+
+    // Empty label name
+    assert.throws(() => container.setLabels({ '': 'value' }), {
+      message: /Label names cannot be empty/,
+    });
+
+    // Label name with control character
+    assert.throws(() => container.setLabels({ 'bad\x01name': 'value' }), {
+      message: /Label names cannot contain control characters \(index 0\)/,
+    });
+
+    // Label value with control character
+    assert.throws(() => container.setLabels({ name: 'bad\x01value' }), {
+      message: /Label values cannot contain control characters \(index 0\)/,
+    });
+
+    await container.destroy();
+    await monitor;
+  }
+
+  async testSetLabelsSerialized() {
+    const container = this.ctx.container;
+    if (container.running) {
+      let monitor = container.monitor().catch((_err) => {});
+      await container.destroy();
+      await monitor;
+    }
+
+    assert.strictEqual(container.running, false);
+
+    container.start({ enableInternet: true });
+    const monitor = container.monitor().catch((_err) => {});
+    await this.waitUntilContainerIsHealthy();
+
+    // Issue two concurrent setLabels calls without awaiting between them. The server-side
+    // RpcTurn mechanism serializes them, so the final inspect() must equal whichever call
+    // was awaited last.
+    const first = container.setLabels({ a: '1' });
+    const second = container.setLabels({ b: '2' });
+    await Promise.all([first, second]);
+
+    const info = await container.inspect();
+    assert.deepStrictEqual(info.labels, { b: '2' });
+
+    await container.destroy();
+    await monitor;
+  }
+
   async testPidNamespace() {
     const container = this.ctx.container;
     if (container.running) {
@@ -2595,13 +2789,12 @@ export const testSetInactivityTimeout = {
   },
 };
 
-// Test that custom labels are passed through to the container
+// Test that custom labels round-trip through the JS API's in-memory label store.
 export const testLabels = {
   async test(_ctrl, env) {
-    const id = env.MY_CONTAINER.idFromName(
+    const stub = env.MY_CONTAINER.getByName(
       getRandomDurableObjectName('testLabels')
     );
-    const stub = env.MY_CONTAINER.get(id);
     await stub.testLabels();
   },
 };
@@ -2609,10 +2802,9 @@ export const testLabels = {
 // Test that invalid labels are rejected with clear error messages
 export const testLabelValidation = {
   async test(_ctrl, env) {
-    const id = env.MY_CONTAINER.idFromName(
+    const stub = env.MY_CONTAINER.getByName(
       getRandomDurableObjectName('testLabelValidation')
     );
-    const stub = env.MY_CONTAINER.get(id);
     await stub.testLabelValidation();
   },
 };
@@ -2629,24 +2821,103 @@ export const testInspectBeforeStart = {
 
 export const testInspectEmptyLabels = {
   async test(_ctrl, env) {
-    const id = env.MY_CONTAINER.idFromName(
+    const stub = env.MY_CONTAINER.getByName(
       getRandomDurableObjectName('testInspectEmptyLabels')
     );
-    const stub = env.MY_CONTAINER.get(id);
     await stub.testInspectEmptyLabels();
   },
 };
 
 export const testInspectAfterDestroy = {
   async test(_ctrl, env) {
-    const id = env.MY_CONTAINER.idFromName(
+    const stub = env.MY_CONTAINER.getByName(
       getRandomDurableObjectName('testInspectAfterDestroy')
     );
-    const stub = env.MY_CONTAINER.get(id);
     await stub.testInspectAfterDestroy();
   },
 };
 
+// Test that setLabels() updates labels on a running container and that subsequent
+// inspect() calls see the new set.
+export const testSetLabels = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabels')
+    );
+    await stub.testSetLabels();
+  },
+};
+
+// Test that setLabels() fully replaces (not merges) the label set.
+export const testSetLabelsReplaces = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabelsReplaces')
+    );
+    await stub.testSetLabelsReplaces();
+  },
+};
+
+// Test that setLabels({}) clears all labels.
+export const testSetLabelsClearsAll = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabelsClearsAll')
+    );
+    await stub.testSetLabelsClearsAll();
+  },
+};
+
+// Test that setLabels() throws when the container has not been started.
+export const testSetLabelsBeforeStart = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabelsBeforeStart')
+    );
+    await stub.testSetLabelsBeforeStart();
+  },
+};
+
+// Test that setLabels() throws after the container has been destroyed.
+export const testSetLabelsAfterDestroy = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabelsAfterDestroy')
+    );
+    await stub.testSetLabelsAfterDestroy();
+  },
+};
+
+// Test that destroy() immediately clears server-side running state even before monitor() resolves.
+export const testSetLabelsAfterDestroyWithoutMonitor = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabelsAfterDestroyWithoutMonitor')
+    );
+    await stub.testSetLabelsAfterDestroyWithoutMonitor();
+  },
+};
+
+// Test that setLabels() rejects invalid label names and values with the same rules as start().
+export const testSetLabelsValidation = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabelsValidation')
+    );
+    await stub.testSetLabelsValidation();
+  },
+};
+
+// Test that concurrent setLabels() calls are serialized and the last-completed call wins.
+export const testSetLabelsSerialized = {
+  async test(_ctrl, env) {
+    const stub = env.MY_CONTAINER.getByName(
+      getRandomDurableObjectName('testSetLabelsSerialized')
+    );
+    await stub.testSetLabelsSerialized();
+  },
+};
+
 // Test PID namespace isolation behavior
 // When containers_pid_namespace is ENABLED, the container has its own isolated PID namespace.
 // We verify this by checking that PID 1 in the container's namespace is the container's