@xemahq/repo-build-tooling 0.21.0 → 0.21.1

package/README.md

@@ -32,7 +32,7 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `pnpm-context`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
 | `xema-arm64-supplement-needed` | Decides whether an arm64 supplement is still owed at `REGISTRY/IMAGE:CONTENT_TAG` (env: `REGISTRY`, `IMAGE`, `CONTENT_TAG`, `REGISTRY_USER`, `REGISTRY_TOKEN`). `needed=false` only when the coordinate serves an index whose linux/arm64 child is proven by its own image config; any other resolvable state is `needed=true`; a 401/403/5xx or an unresolvable child is an error. Writes `needed=true\|false` to `$GITHUB_OUTPUT`. Replaces the generated `arm64-supplement-needed.mjs` copy. |
 | `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
-| `xema-buildx-builder ensure` | Ensures the runner's persistent, capped buildkitd container (`xema-buildkit-signed-<runner>`, state volume `-state`) is up and is the current buildx builder. Env: `RUNNER_NAME`, `BUILDKIT_IMAGE`, `BUILDKIT_LIMITS` (JSON `cpus`, `memory`, `maxParallelism`, `gcMaxUsedSpace`, all required and positive), optional `BUILDKIT_READY_DEADLINE_SECONDS` (positive integer, default 180). Pinned to the runner's cgroup cpuset; recreated once when the image, caps or config change. Prints `buildx-boot path= secs= builder=`. |
+| `xema-buildx-builder ensure` | Ensures the runner's persistent, capped buildkitd container (`xema-buildkit-signed-<runner>`, state volume `-state`) is up and is the current buildx builder. Env: `RUNNER_NAME`, `BUILDKIT_IMAGE`, `BUILDKIT_LIMITS` (JSON `cpus`, `memory`, `maxParallelism`, `gcMaxUsedSpace`, all required and positive), optional `BUILDKIT_READY_DEADLINE_SECONDS` (positive integer, default 180). The slot is `RUNNER_NAME` with a trailing `-<hostname>` stripped only when it equals this container's own hostname, so a recreated runner container reuses its builder and cache. Pinned to the runner's cgroup cpuset; caps are clamped so every `xema-buildkit-signed-*` builder on the host fits (memory at most half of `docker info` MemTotal divided by N, CPUs at most NCPU divided by N). On each run it removes this verb's labelled builders, and their `-state` volumes, whose recorded runner container is no longer running; unlabelled containers are never touched. Recreated once when the image, effective caps, config or runner container change. Prints `buildx-boot path= secs= builder=`. |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
 | `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents (root `lint` only without turbo; typecheck is CI-only there); CI is the proof |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -52,6 +52,6 @@
     "test": "node --test src/buildx-builder.test.mjs && node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/prepush-sanity.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:bc219d66a33857aaeb74bad77ae50b0f53228368249eb16803ecfd7ef6a8fe03"
+    "sourceDigest": "sha256:7c602b30aa27cb65d2c46fbe77f0c93da23bde8525e571943fb8ed5ea48dd924"
   }
 }

package/src/buildx-builder-host.mjs

@@ -0,0 +1,61 @@
+// Pure host-level decisions of xema-buildx-builder: the stable slot name, the host clamp on the caps and the
+// orphan selection. No docker and no I/O here; the verb feeds in what `docker` reported.
+
+export const BUILDER_PREFIX = 'xema-buildkit-signed-';
+export const OWNER_LABEL = 'xema.buildkit.owner';
+export const OWNER_VALUE = 'xema-buildx-builder';
+export const HOST_LABEL = 'xema.buildkit.runner-host';
+
+const UNIT = { '': 1, b: 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3 };
+const MEBIBYTE = 1024 ** 2;
+const MEMORY_SHARE = 0.5;
+const CONTAINER_ID = /^[0-9a-f]{12}$/;
+
+/**
+ * The runner's slot: RUNNER_NAME with a trailing `-<hostname>` stripped, only when that suffix is exactly this
+ * container's own hostname (the runner container id GitHub appends to the name). A recreated runner container
+ * then keeps its builder and cache. Anything else keeps RUNNER_NAME unchanged: never a guess.
+ */
+export function runnerSlot(runnerName, hostname) {
+  if (runnerName === undefined || runnerName === '') throw new Error('RUNNER_NAME is empty or unset: the builder key is derived from it');
+  const suffix = `-${hostname}`;
+  const stripped = hostname !== '' && runnerName.endsWith(suffix) && runnerName.length > suffix.length ? runnerName.slice(0, -suffix.length) : runnerName;
+  return stripped.toLowerCase().replace(/[^a-z0-9_.-]/g, '-');
+}
+
+export function builderName(slot) {
+  return `${BUILDER_PREFIX}${slot}`;
+}
+
+/** A validated size such as `8g` in bytes. */
+export function memoryBytes(size) {
+  const match = /^([0-9]+)([bkmgBKMG]?)$/.exec(size);
+  return Number(match[1]) * UNIT[match[2].toLowerCase()];
+}
+
+/**
+ * The caps actually applied: the configured limit, clamped so N builders together stay inside the host
+ * (half of its memory, all of its CPUs). N counts every signed builder on the host, this one included.
+ * Memory is whole MiB (docker's `m` unit); CPUs are rounded down to 2 decimals.
+ */
+export function effectiveCaps(limits, host, builders) {
+  if (!Number.isInteger(builders) || builders < 1) throw new Error(`builder count must be a positive integer, got ${builders}`);
+  const memoryMiB = Math.floor(Math.min(memoryBytes(limits.memory), (host.memTotal * MEMORY_SHARE) / builders) / MEBIBYTE);
+  const cpus = Math.floor(Math.min(Number(limits.cpus), host.ncpu / builders) * 100) / 100;
+  if (memoryMiB < 1 || cpus <= 0) throw new Error(`host (${host.memTotal} bytes, ${host.ncpu} cpus) is too small for ${builders} signed builders`);
+  return { cpus: String(cpus), memory: `${memoryMiB}m` };
+}
+
+/**
+ * Builders that carry this verb's labels and whose recorded runner container is no longer running.
+ * `known` rows: { name, owner, host }; `runningIds`: ids of the running containers on the host.
+ * A recorded host that is not a container id (a host-network runner records the machine's hostname) cannot
+ * be judged and is never an orphan. Unlabelled containers are never touched; `keep` is the caller's own.
+ */
+export function orphanBuilders(known, runningIds, keep) {
+  return known.filter((row) =>
+    row.name !== keep &&
+    row.owner === OWNER_VALUE &&
+    CONTAINER_ID.test(row.host) &&
+    !runningIds.some((id) => id.startsWith(row.host) || row.host.startsWith(id)));
+}

package/src/buildx-builder-limits.mjs

@@ -33,14 +33,8 @@ export function buildkitdToml(limits) {
   return `[worker.oci]\n  gc = true\n  maxUsedSpace = "${limits.gcMaxUsedSpace}"\n  max-parallelism = ${limits.maxParallelism}\n`;
 }
 
-/** The label value: a change of image, caps, cpuset or config recreates the container exactly once. */
-export function configHash(image, limits, cpuset, toml, sha256) {
-  const caps = `cpus=${limits.cpus} memory=${limits.memory} memory-swap=${limits.memory} cpuset=${cpuset}`;
-  return sha256(`${image}\n${caps}\n${toml}`);
-}
-
-/** The builder key: `xema-buildkit-signed-*` is reserved for signed lanes (T133), so a PR build can never share its cache mounts. The lowercased runner name with anything outside [a-z0-9_.-] mapped to '-'. */
-export function builderName(runnerName) {
-  if (runnerName === undefined || runnerName === '') throw new Error('RUNNER_NAME is empty or unset: the builder key is derived from it');
-  return `xema-buildkit-signed-${runnerName.toLowerCase().replace(/[^a-z0-9_.-]/g, '-')}`;
+/** The label value: `caps` are the EFFECTIVE caps (after the host clamp); a change of image, caps, cpuset or config recreates the container exactly once. */
+export function configHash(image, caps, cpuset, toml, sha256) {
+  const capText = `cpus=${caps.cpus} memory=${caps.memory} memory-swap=${caps.memory} cpuset=${cpuset}`;
+  return sha256(`${image}\n${capText}\n${toml}`);
 }

package/src/buildx-builder.mjs

@@ -13,11 +13,12 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { hostname as osHostname, tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { invokedDirectly } from './readiness.mjs';
-import { buildkitdToml, builderName, configHash, parseLimits } from './buildx-builder-limits.mjs';
+import { BUILDER_PREFIX, HOST_LABEL, OWNER_LABEL, OWNER_VALUE, builderName, effectiveCaps, orphanBuilders, runnerSlot } from './buildx-builder-host.mjs';
+import { buildkitdToml, configHash, parseLimits } from './buildx-builder-limits.mjs';
 
 const ADMITTED_EVENTS = ['push', 'workflow_dispatch'];
 const ADMITTED_REFS = ['refs/heads/main', 'refs/heads/develop'];
@@ -57,7 +58,8 @@ export async function ensure(env, log = console.log) {
   const image = env.BUILDKIT_IMAGE;
   if (image === undefined || image === '') throw new Error('BUILDKIT_IMAGE is required');
   const limits = parseLimits(env.BUILDKIT_LIMITS);
-  const key = builderName(env.RUNNER_NAME);
+  const hostname = osHostname();
+  const key = builderName(runnerSlot(env.RUNNER_NAME, hostname));
   const cpusetFile = env.BUILDKIT_CPUSET_FILE ?? DEFAULT_CPUSET_FILE;
   let cpuset = '';
   try {
@@ -68,31 +70,51 @@ export async function ensure(env, log = console.log) {
   if (cpuset === '') throw new Error(`${cpusetFile} is missing or empty: cannot bound the builder to the runner's cpuset (cgroup v2 required)`);
   const deadlineSeconds = parseDeadlineSeconds(env.BUILDKIT_READY_DEADLINE_SECONDS);
   const toml = buildkitdToml(limits);
-  const cfg = configHash(image, limits, cpuset, toml, sha256);
 
   const scratch = mkdtempSync(join(tmpdir(), 'xema-buildkitd-'));
   try {
     const configFile = join(scratch, 'buildkitd.toml');
     writeFileSync(configFile, toml);
     const start = Date.now();
+
+    // Orphans first: a builder whose runner container is gone keeps its caps on the host for ever otherwise.
+    const listed = () => docker(['ps', '-a', '--filter', `name=^/${BUILDER_PREFIX}`, '--format', `{{.Names}}|{{.Label "${OWNER_LABEL}"}}|{{.Label "${HOST_LABEL}"}}`]).stdout
+      .split('\n').filter((l) => l !== '').map((l) => { const [name, owner, host] = l.split('|'); return { name, owner, host }; });
+    const runningIds = docker(['ps', '--format', '{{.ID}}']).stdout.split('\n').filter((l) => l !== '');
+    for (const orphan of orphanBuilders(listed(), runningIds, key)) {
+      log(`::notice::removing orphaned builder ${orphan.name} (runner container ${orphan.host} is gone) and its state volume`);
+      docker(['rm', '-f', orphan.name], { allowFailure: true });
+      docker(['volume', 'rm', `${orphan.name}-state`], { allowFailure: true });
+    }
+
+    // Clamp to the host: N builders share it, this one included.
+    const info = docker(['info', '--format', '{{.MemTotal}} {{.NCPU}}']).stdout.split(' ').map(Number);
+    if (info.length !== 2 || !info.every((n) => Number.isInteger(n) && n > 0)) throw new Error(`docker info did not report MemTotal and NCPU: '${info.join(' ')}'`);
+    const present = listed();
+    const builders = present.some((row) => row.name === key) ? present.length : present.length + 1;
+    const caps = effectiveCaps(limits, { memTotal: info[0], ncpu: info[1] }, builders);
+    const cfg = configHash(image, caps, cpuset, toml, sha256);
+
     const create = () => {
       docker(['create', '--name', key, '--restart', 'unless-stopped', '--privileged',
-        '--cpus', limits.cpus, '--memory', limits.memory, '--memory-swap', limits.memory, '--cpuset-cpus', cpuset,
+        '--cpus', caps.cpus, '--memory', caps.memory, '--memory-swap', caps.memory, '--cpuset-cpus', cpuset,
         '-v', `${key}-state:/var/lib/buildkit`, '--label', `${LABEL}=${cfg}`,
+        '--label', `${OWNER_LABEL}=${OWNER_VALUE}`, '--label', `${HOST_LABEL}=${hostname}`,
         image, '--config', '/etc/buildkitd.toml']);
       docker(['cp', configFile, `${key}:/etc/buildkitd.toml`]);
       docker(['start', key]);
     };
 
     let path;
-    if (docker(['ps', '-a', '--filter', `name=^/${key}$`, '--format', '{{.Names}}']).stdout === '') {
+    if (!present.some((row) => row.name === key)) {
       path = 'created';
       create();
     } else {
       const have = docker(['inspect', '-f', `{{ index .Config.Labels "${LABEL}" }}`, key]).stdout;
       const haveImage = docker(['inspect', '-f', '{{.Config.Image}}', key]).stdout;
-      if (have !== cfg || haveImage !== image) {
-        log(`::notice::buildkitd ${key} config or image changed (${have || 'none'} ${haveImage} -> ${cfg} ${image}): recreating once, state volume kept`);
+      const haveHost = docker(['inspect', '-f', `{{ index .Config.Labels "${HOST_LABEL}" }}`, key]).stdout;
+      if (have !== cfg || haveImage !== image || haveHost !== hostname) {
+        log(`::notice::buildkitd ${key} config, image or runner container changed (${have || 'none'} ${haveImage} ${haveHost} -> ${cfg} ${image} ${hostname}): recreating once, state volume kept`);
         docker(['rm', '-f', key]);
         path = 'recreated';
         create();
@@ -103,7 +125,7 @@ export async function ensure(env, log = console.log) {
         docker(['start', key]);
       }
     }
-    log(`buildx-boot ${key}: ${path}; caps cpus=${limits.cpus} memory=${limits.memory} cpuset=${cpuset} max-parallelism=${limits.maxParallelism}; waiting for workers (deadline ${deadlineSeconds}s)`);
+    log(`buildx-boot ${key}: ${path}; caps cpus=${caps.cpus} memory=${caps.memory} (limit ${limits.cpus}/${limits.memory}, ${builders} builders on the host) cpuset=${cpuset} max-parallelism=${limits.maxParallelism}; waiting for workers (deadline ${deadlineSeconds}s)`);
 
     let check = 0;
     for (;;) {
@@ -131,7 +153,7 @@ export async function ensure(env, log = console.log) {
     docker(['buildx', 'inspect', '--bootstrap', key]);
 
     const secs = Math.floor((Date.now() - start) / 1000);
-    const line = `buildx-boot path=${path} secs=${secs} builder=${key}`;
+    const line = `buildx-boot path=${path} secs=${secs} builder=${key} cpus=${caps.cpus} memory=${caps.memory}`;
     log(line);
     return { path, secs, builder: key, line };
   } finally {

package/src/buildx-builder.test.mjs

@@ -1,12 +1,15 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { hostname, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 
 const BIN = fileURLToPath(new URL('./buildx-builder.mjs', import.meta.url));
+const HOST = hostname();
+const OWN = 'xema-buildkit-signed-owl-runner-1';
+const ownRow = (host = HOST) => `${OWN}|xema-buildx-builder|${host}`;
 const LIMITS = '{"cpus":"4","memory":"8g","maxParallelism":4,"gcMaxUsedSpace":"5GB"}';
 
 // A fake docker on PATH: appends every call to calls.log; `ps` answers $FAKE_PS, `inspect -f ...Labels...` answers $FAKE_LABEL,
@@ -18,8 +21,9 @@ function sandbox() {
   writeFileSync(fake, `#!/bin/sh
 echo "$@" >> "${log}"
 case "$1" in
-  ps) printf '%s' "$FAKE_PS" ;;
-  inspect) case "$*" in *Labels*) printf '%s' "$FAKE_LABEL" ;; *Config.Image*) printf '%s' "\${FAKE_IMAGE:-moby/buildkit:v0.1}" ;; *Running*) printf '%s' "$FAKE_RUNNING" ;; esac ;;
+  ps) case "$*" in *'{{.ID}}'*) printf '%s' "$FAKE_RUNNING_IDS" ;; *) printf '%s' "$FAKE_LIST" ;; esac ;;
+  info) printf '%s' "\${FAKE_INFO:-68719476736 10}" ;;
+  inspect) case "$*" in *runner-host*) printf '%s' "$FAKE_HOST" ;; *Labels*) printf '%s' "$FAKE_LABEL" ;; *Config.Image*) printf '%s' "\${FAKE_IMAGE:-moby/buildkit:v0.1}" ;; *Running*) printf '%s' "$FAKE_RUNNING" ;; esac ;;
   exec) if [ "\${FAKE_EXEC_FAIL:-0}" = 1 ]; then echo "no workers" >&2; exit 1; fi ;;
   buildx) [ "$2" = inspect ] && [ "$3" != --bootstrap ] && exit 1; exit 0 ;;
 esac
@@ -31,7 +35,7 @@ exit 0
   const run = (extra = {}) => {
     const env = {
       PATH: `${dir}:${process.env.PATH}`, RUNNER_NAME: 'Owl Runner/1', BUILDKIT_IMAGE: 'moby/buildkit:v0.1',
-      BUILDKIT_LIMITS: LIMITS, BUILDKIT_CPUSET_FILE: cpuset, GITHUB_EVENT_NAME: 'push', GITHUB_REF: 'refs/heads/develop', ...extra,
+      BUILDKIT_LIMITS: LIMITS, FAKE_HOST: HOST, BUILDKIT_CPUSET_FILE: cpuset, GITHUB_EVENT_NAME: 'push', GITHUB_REF: 'refs/heads/develop', ...extra,
     };
     for (const [k, v] of Object.entries(env)) if (v === undefined) delete env[k];
     const r = spawnSync(process.execPath, [BIN, 'ensure'], { env, encoding: 'utf8' });
@@ -97,32 +101,32 @@ test('missing or invalid limits, runner name, image and cpuset fail before any d
 test('first run creates the capped container pinned to the runner cpuset, then prints the buildx-boot line', () => {
   const s = sandbox();
   try {
-    const r = s.run({ FAKE_PS: '' });
+    const r = s.run({});
     assert.equal(r.status, 0, r.stderr);
     const create = r.calls.split('\n').find((l) => l.startsWith('create '));
     assert.match(create, /--name xema-buildkit-signed-owl-runner-1 /);
-    assert.match(create, /--cpus 4 --memory 8g --memory-swap 8g --cpuset-cpus 10-27/);
+    assert.match(create, /--cpus 4 --memory 8192m --memory-swap 8192m --cpuset-cpus 10-27/);
     assert.match(create, /--privileged/);
     assert.match(create, /-v xema-buildkit-signed-owl-runner-1-state:\/var\/lib\/buildkit/);
     assert.match(r.calls, /cp .*buildkitd\.toml xema-buildkit-signed-owl-runner-1:\/etc\/buildkitd\.toml/);
     assert.match(r.calls, /buildx create --name xema-buildkit-signed-owl-runner-1 --driver remote/);
     assert.match(r.calls, /buildx use xema-buildkit-signed-owl-runner-1/);
-    assert.match(r.stdout, /^buildx-boot path=created secs=\d+ builder=xema-buildkit-signed-owl-runner-1$/m);
+    assert.match(r.stdout, /^buildx-boot path=created secs=\d+ builder=xema-buildkit-signed-owl-runner-1 cpus=4 memory=8192m$/m);
   } finally { rmSync(s.dir, { recursive: true, force: true }); }
 });
 
 test('a changed hash recreates once, keeping the state volume; the same hash reuses', () => {
   const s = sandbox();
   try {
-    const first = s.run({ FAKE_PS: '' });
+    const first = s.run({});
     const label = /--label xema\.buildkit\.cfg=([0-9a-f]{64})/.exec(first.calls)[1];
     rmSync(join(s.dir, 'calls.log'));
-    const recreated = s.run({ FAKE_PS: 'xema-buildkit-signed-owl-runner-1', FAKE_LABEL: 'stale' });
+    const recreated = s.run({ FAKE_LIST: ownRow(), FAKE_LABEL: 'stale' });
     assert.match(recreated.calls, /rm -f xema-buildkit-signed-owl-runner-1/);
     assert.doesNotMatch(recreated.calls, /volume rm/);
     assert.match(recreated.stdout, /path=recreated/);
     rmSync(join(s.dir, 'calls.log'));
-    const reused = s.run({ FAKE_PS: 'xema-buildkit-signed-owl-runner-1', FAKE_LABEL: label, FAKE_RUNNING: 'true' });
+    const reused = s.run({ FAKE_LIST: ownRow(), FAKE_LABEL: label, FAKE_RUNNING: 'true' });
     assert.doesNotMatch(reused.calls, /^(create|rm) /m);
     assert.match(reused.stdout, /path=running/);
   } finally { rmSync(s.dir, { recursive: true, force: true }); }
@@ -131,19 +135,86 @@ test('a changed hash recreates once, keeping the state volume; the same hash reu
 test('a matching label but a different running image recreates once', () => {
   const s = sandbox();
   try {
-    const first = s.run({ FAKE_PS: '' });
+    const first = s.run({});
     const label = /--label xema\.buildkit\.cfg=([0-9a-f]{64})/.exec(first.calls)[1];
     rmSync(join(s.dir, 'calls.log'));
-    const r = s.run({ FAKE_PS: 'xema-buildkit-signed-owl-runner-1', FAKE_LABEL: label, FAKE_RUNNING: 'true', FAKE_IMAGE: 'moby/buildkit:old' });
+    const r = s.run({ FAKE_LIST: ownRow(), FAKE_LABEL: label, FAKE_RUNNING: 'true', FAKE_IMAGE: 'moby/buildkit:old' });
     assert.match(r.calls, /rm -f xema-buildkit-signed-owl-runner-1/);
     assert.match(r.stdout, /path=recreated/);
   } finally { rmSync(s.dir, { recursive: true, force: true }); }
 });
 
+test('a recreated runner container (new hostname) recreates its builder once, keeping the state volume', () => {
+  const s = sandbox();
+  try {
+    const first = s.run({});
+    const label = /--label xema\.buildkit\.cfg=([0-9a-f]{64})/.exec(first.calls)[1];
+    rmSync(join(s.dir, 'calls.log'));
+    const r = s.run({ FAKE_LIST: ownRow('0123456789ab'), FAKE_HOST: '0123456789ab', FAKE_LABEL: label, FAKE_RUNNING: 'true' });
+    assert.match(r.stdout, /path=recreated/);
+    assert.doesNotMatch(r.calls, /volume rm/);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('the slot strips a trailing -<hostname> only when it is exactly this container\'s hostname', () => {
+  const s = sandbox();
+  try {
+    const same = s.run({ RUNNER_NAME: `xema-fox1-${HOST}` });
+    assert.match(same.stdout, /builder=xema-buildkit-signed-xema-fox1 /);
+    assert.match(same.calls, /-v xema-buildkit-signed-xema-fox1-state:/);
+    const other = s.run({ RUNNER_NAME: 'xema-fox1-2f7dad65784b' });
+    assert.match(other.stdout, /builder=xema-buildkit-signed-xema-fox1-2f7dad65784b /);
+    const whole = s.run({ RUNNER_NAME: HOST });
+    assert.match(whole.stdout, new RegExp(`builder=xema-buildkit-signed-${HOST.toLowerCase().replace(/[^a-z0-9_.-]/g, '-')} `));
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('orphan GC removes only labelled builders whose runner container is gone, with their state volume', () => {
+  const s = sandbox();
+  try {
+    const list = [
+      ownRow(),
+      'xema-buildkit-signed-dead|xema-buildx-builder|aaaaaaaaaaaa',
+      'xema-buildkit-signed-alive|xema-buildx-builder|bbbbbbbbbbbb',
+      'xema-buildkit-signed-hostnet|xema-buildx-builder|fox-host',
+      'xema-buildkit-signed-foreign||cccccccccccc',
+    ].join('\n');
+    const r = s.run({ FAKE_LIST: list, FAKE_RUNNING_IDS: 'bbbbbbbbbbbb\ndddddddddddd', FAKE_HOST: HOST });
+    assert.match(r.calls, /^rm -f xema-buildkit-signed-dead$/m);
+    assert.match(r.calls, /^volume rm xema-buildkit-signed-dead-state$/m);
+    assert.doesNotMatch(r.calls, /rm -f xema-buildkit-signed-(alive|hostnet|foreign)/);
+    assert.doesNotMatch(r.stdout, /removing orphaned builder xema-buildkit-signed-owl-runner-1/);
+    assert.doesNotMatch(r.calls, /volume rm xema-buildkit-signed-(alive|hostnet|foreign)/);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('the caps are clamped so N signed builders fit the host, and the effective caps are printed', () => {
+  const s = sandbox();
+  try {
+    const list = [1, 2, 3].map((n) => `xema-buildkit-signed-other${n}|xema-buildx-builder|bbbbbbbbbbbb`).join('\n');
+    // 16 GiB, 8 cpus, 4 builders (3 others + this one): memory 16/2/4 = 2 GiB, cpus 8/4 = 2.
+    const r = s.run({ FAKE_LIST: list, FAKE_RUNNING_IDS: 'bbbbbbbbbbbb', FAKE_INFO: '17179869184 8' });
+    const create = r.calls.split('\n').find((l) => l.startsWith('create '));
+    assert.match(create, /--cpus 2 --memory 2048m --memory-swap 2048m/);
+    assert.match(r.stdout, /builder=xema-buildkit-signed-owl-runner-1 cpus=2 memory=2048m$/m);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
+test('changed effective caps recreate the builder once', () => {
+  const s = sandbox();
+  try {
+    const first = s.run({});
+    const label = /--label xema\.buildkit\.cfg=([0-9a-f]{64})/.exec(first.calls)[1];
+    rmSync(join(s.dir, 'calls.log'));
+    const r = s.run({ FAKE_LIST: ownRow(), FAKE_LABEL: label, FAKE_RUNNING: 'true', FAKE_INFO: '8589934592 8' });
+    assert.match(r.stdout, /path=recreated/);
+  } finally { rmSync(s.dir, { recursive: true, force: true }); }
+});
+
 test('a builder that never becomes ready fails at the deadline with the container logs', () => {
   const s = sandbox();
   try {
-    const r = s.run({ FAKE_PS: '', FAKE_EXEC_FAIL: '1', BUILDKIT_READY_DEADLINE_SECONDS: '1' });
+    const r = s.run({ FAKE_EXEC_FAIL: '1', BUILDKIT_READY_DEADLINE_SECONDS: '1' });
     assert.equal(r.status, 1);
     assert.match(r.stderr, /not ready after 1s/);
     assert.match(r.calls, /logs --tail 50/);