chainlesschain 0.166.77 → 0.166.78

package/src/lib/process-execution-broker/index.js

@@ -46,6 +46,14 @@ import {
   SANDBOX_BOUNDARIES,
 } from "./platform-sandbox.js";
 import { normalizeLinuxCgroupPolicy } from "./linux-cgroup-v2.js";
+import { acquireLinuxSubreaperHelper } from "./linux-subreaper-helper.js";
+import { spawnLinuxSubreaperChild } from "./linux-subreaper-process.js";
+import {
+  assertProcessOwnershipAvailable,
+  getProcessOwnershipStatus,
+  observeProcessOwnership,
+  prepareProcessOwnership,
+} from "./process-ownership-quarantine.js";
 import {
   MACOS_MCP_LAUNCHER_INPUTS,
   isMacosMcpLauncherPackageVersion,
@@ -1187,6 +1195,7 @@ class ProcessExecutionBroker extends EventEmitter {
   _sanitizeOptions(options) {
     if (!options) return {};
     const safe = { ...options };
+    delete safe.linuxSubreaper;
     if (process.platform === "win32" && safe.shell === true) {
       safe.windowsHide = true;
     }
@@ -4479,6 +4488,7 @@ class ProcessExecutionBroker extends EventEmitter {
    * and durable evidence APIs.
    */
   beginWorkspaceTransaction(options = {}) {
+    assertProcessOwnershipAvailable();
     return this._workspaceTransactionManager(
       options.stateDir,
       options.lockDir,
@@ -4486,6 +4496,7 @@ class ProcessExecutionBroker extends EventEmitter {
   }
 
   recoverWorkspaceTransactions(options = {}) {
+    assertProcessOwnershipAvailable();
     return this._workspaceTransactionManager(
       options.stateDir,
       options.lockDir,
@@ -4499,6 +4510,10 @@ class ProcessExecutionBroker extends EventEmitter {
     ).inspect(id);
   }
 
+  getProcessOwnershipStatus() {
+    return getProcessOwnershipStatus();
+  }
+
   listWorkspaceTransactions(options = {}) {
     return this._workspaceTransactionManager(
       options.stateDir,
@@ -4507,6 +4522,7 @@ class ProcessExecutionBroker extends EventEmitter {
   }
 
   restoreWorkspaceTransaction(id, options = {}) {
+    assertProcessOwnershipAvailable();
     return this._workspaceTransactionManager(
       options.stateDir,
       options.lockDir,
@@ -4514,6 +4530,7 @@ class ProcessExecutionBroker extends EventEmitter {
   }
 
   undoWorkspaceTransactionRestore(id, options = {}) {
+    assertProcessOwnershipAvailable();
     return this._workspaceTransactionManager(
       options.stateDir,
       options.lockDir,
@@ -4569,6 +4586,7 @@ class ProcessExecutionBroker extends EventEmitter {
   }
 
   spawn(command, args, options = {}) {
+    assertProcessOwnershipAvailable();
     options = this._withAmbientProcessContext(command, options);
     const executionId = crypto.randomUUID();
     const startTime = Date.now();
@@ -4800,7 +4818,71 @@ class ProcessExecutionBroker extends EventEmitter {
         );
         auditEntry.mcpStdioExecutableIdentityDigest = admitted.identityDigest;
       }
-      proc = nativeSpawnFn(command, args, optsForSpawn);
+      if (
+        process.platform === "linux" &&
+        options.linuxSubreaper &&
+        !sandboxPlan.guarantees.includes(SANDBOX_BOUNDARIES.PROCESS_TREE)
+      ) {
+        const request = options.linuxSubreaper;
+        const stdio = optsForSpawn.stdio;
+        if (
+          !request ||
+          typeof request !== "object" ||
+          Array.isArray(request) ||
+          Object.keys(request).some((key) => key !== "graceMs") ||
+          !Number.isSafeInteger(request.graceMs) ||
+          request.graceMs < 0 ||
+          request.graceMs > 2147483647 ||
+          sandboxPlan.postSpawn.required ||
+          options.shell ||
+          optsForSpawn.shell ||
+          optsForSpawn.detached ||
+          (stdio !== undefined && stdio !== "pipe") ||
+          ["uid", "gid", "signal", "timeout", "input", "argv0"].some(
+            (key) => optsForSpawn[key] !== undefined,
+          ) ||
+          (sandboxPlan.applied && sandboxPlan.backend !== "linux-prlimit")
+        ) {
+          const error = new Error(
+            "Linux external-agent supervision cannot preserve this launch plan",
+          );
+          error.code = "EXTERNAL_AGENT_SUPERVISION_UNSUPPORTED_PLAN";
+          throw error;
+        }
+        const ownershipLease = prepareProcessOwnership(executionId);
+        let nativeEntered = false;
+        try {
+          const helper = acquireLinuxSubreaperHelper({
+            spawnSync: this._native?.spawnSync || nativeSpawnSync,
+          });
+          proc = spawnLinuxSubreaperChild(
+            command,
+            args,
+            {
+              cwd: path.resolve(optsForSpawn.cwd || cwd),
+              env: optsForSpawn.env || process.env,
+              graceMs: request.graceMs,
+              helper,
+            },
+            {
+              spawn: (...nativeArgs) => {
+                nativeEntered = true;
+                return nativeSpawnFn(...nativeArgs);
+              },
+            },
+          );
+        } catch (error) {
+          // Before native entry no process could exist. Once entered, retain
+          // the durable record even if a synchronous exception hides its handle.
+          if (!nativeEntered) ownershipLease?.settle();
+          else ownershipLease?.retain();
+          throw error;
+        }
+        auditEntry.processLifecycleOwner = "linux-subreaper";
+        observeProcessOwnership(proc, executionId, ownershipLease);
+      } else {
+        proc = nativeSpawnFn(command, args, optsForSpawn);
+      }
       if (builtInMacMcpPlan) {
         const callerLifeline = proc?.stdio?.[8];
         if (
@@ -4912,6 +4994,10 @@ class ProcessExecutionBroker extends EventEmitter {
 
       proc.on("exit", (code, signal) => {
         const endTime = Date.now();
+        if (proc.ownedProcessTreeEvidence) {
+          auditEntry.processLifecycleReceipt = proc.ownedProcessTreeEvidence;
+          auditEntry.sandboxTargetPid = proc.sandboxTargetPid;
+        }
         auditEntry.exitCode = code;
         auditEntry.signal = signal;
         auditEntry.endTime = endTime;
@@ -4929,6 +5015,10 @@ class ProcessExecutionBroker extends EventEmitter {
         this.emit("exit", auditEntry);
       });
       proc.on("error", (err) => {
+        if (proc.ownedProcessTreeEvidence) {
+          auditEntry.processLifecycleReceipt = proc.ownedProcessTreeEvidence;
+          auditEntry.sandboxTargetPid = proc.sandboxTargetPid;
+        }
         auditEntry.error = err.message;
         auditEntry.endTime = Date.now();
         auditEntry.durationMs = auditEntry.endTime - startTime;
@@ -4957,6 +5047,7 @@ class ProcessExecutionBroker extends EventEmitter {
   }
 
   spawnSync(command, args, options = {}) {
+    assertProcessOwnershipAvailable();
     options = this._withAmbientProcessContext(command, options);
     const executionId = crypto.randomUUID();
     const startTime = Date.now();
@@ -5203,6 +5294,7 @@ class ProcessExecutionBroker extends EventEmitter {
    * together with the descriptor-pinned generic bwrap plan.
    */
   spawnPty(ptyModule, command, args = [], options = {}) {
+    assertProcessOwnershipAvailable();
     if (!ptyModule || typeof ptyModule.spawn !== "function") {
       throw new TypeError("pty_module_spawn_unavailable");
     }

package/src/lib/process-execution-broker/linux-subreaper-artifact.js

@@ -0,0 +1,120 @@
+import crypto from "node:crypto";
+
+export const LINUX_SUBREAPER_SOURCE_DIGEST =
+  "sha256:e920e24b4a79121484f2e8e97886755f88eaa1af93b55326dfa68c7a7f571424";
+export const LINUX_SUBREAPER_ARCHITECTURES = Object.freeze(["x64", "arm64"]);
+export const MAX_SUBREAPER_IMAGE_BYTES = 4 * 1024 * 1024;
+export const MAX_SUBREAPER_MANIFEST_BYTES = 4096;
+
+export function subreaperDigest(bytes) {
+  return "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function invalid(reason) {
+  const error = new Error(
+    `Linux process supervision helper unavailable: ${reason}`,
+  );
+  error.code = "EXTERNAL_AGENT_HELPER_UNAVAILABLE";
+  return error;
+}
+
+/** Bounded ELF64 inspection; release images have no dynamic loader dependency. */
+export function validateLinuxSubreaperElf(bytes, { arch, staticOnly = false }) {
+  const machine = arch === "x64" ? 62 : arch === "arm64" ? 183 : null;
+  if (
+    !machine ||
+    !Buffer.isBuffer(bytes) ||
+    bytes.length < 64 ||
+    bytes.length > MAX_SUBREAPER_IMAGE_BYTES ||
+    !bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])) ||
+    bytes[4] !== 2 ||
+    bytes[5] !== 1 ||
+    bytes[6] !== 1 ||
+    bytes.readUInt16LE(18) !== machine ||
+    ![2, 3].includes(bytes.readUInt16LE(16)) ||
+    bytes.readUInt32LE(20) !== 1 ||
+    bytes.readUInt16LE(52) !== 64 ||
+    bytes.readUInt16LE(54) !== 56
+  )
+    throw invalid("unexpected-helper-image");
+  const offset = bytes.readBigUInt64LE(32);
+  const count = bytes.readUInt16LE(56);
+  if (
+    offset < 64n ||
+    count < 1 ||
+    count > 128 ||
+    offset + BigInt(count * 56) > BigInt(bytes.length)
+  )
+    throw invalid("invalid-helper-program-headers");
+  const entry = bytes.readBigUInt64LE(24);
+  let executableEntry = false;
+  for (let index = 0; index < count; index++) {
+    const at = Number(offset) + index * 56;
+    const type = bytes.readUInt32LE(at);
+    if (staticOnly && [2, 3].includes(type))
+      throw invalid("helper-is-not-static");
+    if (type !== 1) continue;
+    const fileOffset = bytes.readBigUInt64LE(at + 8);
+    const address = bytes.readBigUInt64LE(at + 16);
+    const fileSize = bytes.readBigUInt64LE(at + 32);
+    const memorySize = bytes.readBigUInt64LE(at + 40);
+    if (fileSize > memorySize || fileOffset + fileSize > BigInt(bytes.length))
+      throw invalid("invalid-helper-load-segment");
+    if (
+      bytes.readUInt32LE(at + 4) & 1 &&
+      entry >= address &&
+      entry < address + fileSize
+    )
+      executableEntry = true;
+  }
+  if (!executableEntry || (staticOnly && bytes.readUInt16LE(16) !== 2))
+    throw invalid("invalid-helper-entry");
+}
+
+export function validateLinuxSubreaperArtifact(
+  manifestBytes,
+  imageBytes,
+  { arch, commit } = {},
+) {
+  if (
+    !Buffer.isBuffer(manifestBytes) ||
+    manifestBytes.length > MAX_SUBREAPER_MANIFEST_BYTES
+  )
+    throw invalid("invalid-packaged-manifest");
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestBytes.toString("utf8"));
+  } catch {
+    throw invalid("invalid-packaged-manifest");
+  }
+  const keys = [
+    "schema",
+    "platform",
+    "arch",
+    "sourceDigest",
+    "imageDigest",
+    "bytes",
+    "linkage",
+    "commit",
+  ];
+  if (
+    !manifest ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    Object.keys(manifest).length !== keys.length ||
+    Object.keys(manifest).some((key) => !keys.includes(key)) ||
+    manifest.schema !== "chainlesschain.linux-subreaper-artifact/v1" ||
+    manifest.platform !== "linux" ||
+    !LINUX_SUBREAPER_ARCHITECTURES.includes(arch) ||
+    manifest.arch !== arch ||
+    manifest.sourceDigest !== LINUX_SUBREAPER_SOURCE_DIGEST ||
+    manifest.linkage !== "static" ||
+    !/^[a-f0-9]{40}$/.test(manifest.commit) ||
+    (commit !== undefined && manifest.commit !== commit) ||
+    manifest.bytes !== imageBytes.length ||
+    manifest.imageDigest !== subreaperDigest(imageBytes)
+  )
+    throw invalid("packaged-identity-mismatch");
+  validateLinuxSubreaperElf(imageBytes, { arch, staticOnly: true });
+  return Object.freeze({ ...manifest });
+}

package/src/lib/process-execution-broker/linux-subreaper-helper.js

@@ -0,0 +1,344 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import {
+  LINUX_SUBREAPER_SOURCE_DIGEST,
+  MAX_SUBREAPER_IMAGE_BYTES,
+  MAX_SUBREAPER_MANIFEST_BYTES,
+  validateLinuxSubreaperArtifact,
+  validateLinuxSubreaperElf,
+} from "./linux-subreaper-artifact.js";
+export { LINUX_SUBREAPER_SOURCE_DIGEST } from "./linux-subreaper-artifact.js";
+
+const MAX_SOURCE_BYTES = 128 * 1024;
+const MAX_IMAGE_BYTES = MAX_SUBREAPER_IMAGE_BYTES;
+const images = new Map();
+const leases = new WeakMap();
+const sha = (bytes) =>
+  "sha256:" + crypto.createHash("sha256").update(bytes).digest("hex");
+
+function failure(reason) {
+  const error = new Error(
+    `Linux process supervision helper unavailable: ${reason}`,
+  );
+  error.code = "EXTERNAL_AGENT_HELPER_UNAVAILABLE";
+  return error;
+}
+
+function readDescriptor(fd, maximum) {
+  const before = fs.fstatSync(fd, { bigint: true });
+  if (!before.isFile() || before.size < 1n || before.size > BigInt(maximum))
+    throw failure("invalid-file");
+  const bytes = Buffer.alloc(Number(before.size));
+  let offset = 0;
+  while (offset < bytes.length) {
+    const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+    if (count <= 0) throw failure("short-file-read");
+    offset += count;
+  }
+  const after = fs.fstatSync(fd, { bigint: true });
+  if (
+    before.dev !== after.dev ||
+    before.ino !== after.ino ||
+    before.size !== after.size ||
+    before.mtimeNs !== after.mtimeNs ||
+    before.ctimeNs !== after.ctimeNs
+  )
+    throw failure("file-changed");
+  return { bytes, stat: after };
+}
+
+function compilerPath() {
+  // Only the system toolchain is eligible. Do not consult PATH, CC, loader,
+  // include-path, or plugin-provided compiler settings.
+  const compiler = fs.realpathSync("/usr/bin/cc");
+  let current = compiler;
+  for (;;) {
+    const info = fs.lstatSync(current);
+    if (info.isSymbolicLink() || info.uid !== 0 || (info.mode & 0o022) !== 0)
+      throw failure("untrusted-system-compiler");
+    if (current === compiler && (!info.isFile() || (info.mode & 0o111) === 0))
+      throw failure("invalid-system-compiler");
+    if (current === "/") break;
+    current = path.dirname(current);
+  }
+  return compiler;
+}
+
+function packagedImage() {
+  const root = fileURLToPath(
+    new URL("../../assets/linux-subreaper/", import.meta.url),
+  );
+  // Only source checkouts with no packaged directory may use the development
+  // compiler path. A partial/corrupt installed payload must never fall back.
+  try {
+    if (!fs.lstatSync(root).isDirectory())
+      throw failure("invalid-packaged-directory");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  let rootFd = null;
+  let dirFd = null;
+  const read = (name, maximum) => {
+    const fd = fs.openSync(
+      `/proc/self/fd/${dirFd}/${name}`,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    try {
+      const snapshot = readDescriptor(fd, maximum);
+      if (snapshot.stat.nlink !== 1n) throw failure("invalid-packaged-file");
+      return snapshot.bytes;
+    } finally {
+      fs.closeSync(fd);
+    }
+  };
+  try {
+    rootFd = fs.openSync(
+      root,
+      fs.constants.O_RDONLY |
+        fs.constants.O_DIRECTORY |
+        fs.constants.O_NOFOLLOW,
+    );
+    dirFd = fs.openSync(
+      `/proc/self/fd/${rootFd}/linux-${process.arch}`,
+      fs.constants.O_RDONLY |
+        fs.constants.O_DIRECTORY |
+        fs.constants.O_NOFOLLOW,
+    );
+    const manifest = read("manifest.json", MAX_SUBREAPER_MANIFEST_BYTES);
+    const bytes = read("supervisor", MAX_IMAGE_BYTES);
+    const identity = validateLinuxSubreaperArtifact(manifest, bytes, {
+      arch: process.arch,
+    });
+    return { bytes, identity };
+  } catch (error) {
+    if (error.code === "EXTERNAL_AGENT_HELPER_UNAVAILABLE") throw error;
+    throw failure("packaged-helper-unavailable");
+  } finally {
+    if (dirFd !== null) fs.closeSync(dirFd);
+    if (rootFd !== null) fs.closeSync(rootFd);
+  }
+}
+
+function compileImage(spawnSync) {
+  let sourceFd = null;
+  let directoryFd = null;
+  let imageFd = null;
+  let temporaryRoot = null;
+  let imagePath = null;
+  try {
+    // Vite may import the Broker through an http: module URL on non-Linux
+    // hosts. Resolve this Linux-only asset only when native supervision runs.
+    const source = fileURLToPath(
+      new URL("./linux-subreaper-supervisor.c", import.meta.url),
+    );
+    sourceFd = fs.openSync(
+      source,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    const snapshot = readDescriptor(sourceFd, MAX_SOURCE_BYTES);
+    // npm/git may transport text with CRLF. Compile the exact canonical bytes
+    // that the source digest commits to, passed on stdin rather than reopened.
+    const sourceBytes = Buffer.from(
+      snapshot.bytes.toString("utf8").replace(/\r\n/g, "\n"),
+    );
+    if (
+      snapshot.stat.nlink !== 1n ||
+      sha(sourceBytes) !== LINUX_SUBREAPER_SOURCE_DIGEST
+    )
+      throw failure("source-digest-mismatch");
+    fs.closeSync(sourceFd);
+    sourceFd = null;
+    const packaged = packagedImage();
+    const compiler = packaged ? null : compilerPath();
+    temporaryRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), "cc-linux-subreaper-build-"),
+    );
+    fs.chmodSync(temporaryRoot, 0o700);
+    directoryFd = fs.openSync(
+      temporaryRoot,
+      fs.constants.O_RDONLY |
+        fs.constants.O_DIRECTORY |
+        fs.constants.O_NOFOLLOW,
+    );
+    const directory = fs.fstatSync(directoryFd);
+    if (
+      !directory.isDirectory() ||
+      directory.uid !== process.getuid() ||
+      (directory.mode & 0o777) !== 0o700
+    )
+      throw failure("untrusted-build-directory");
+    imagePath = path.join(temporaryRoot, "supervisor");
+    // The compiler writes through its inherited directory handle. An ancestor
+    // rename cannot redirect the build to a caller-supplied executable path.
+    if (packaged) {
+      fs.writeFileSync(
+        `/proc/self/fd/${directoryFd}/supervisor`,
+        packaged.bytes,
+        { flag: "wx", mode: 0o500 },
+      );
+    } else {
+      const built = spawnSync(
+        compiler,
+        [
+          "-std=c11",
+          "-Wall",
+          "-Wextra",
+          "-Werror",
+          "-O2",
+          "-fstack-protector-strong",
+          "-D_FORTIFY_SOURCE=2",
+          "-x",
+          "c",
+          "-",
+          "-o",
+          "/proc/self/fd/3/supervisor",
+        ],
+        {
+          cwd: temporaryRoot,
+          env: { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+          shell: false,
+          input: sourceBytes,
+          timeout: 30000,
+          maxBuffer: 1024 * 1024,
+          stdio: ["pipe", "pipe", "pipe", directoryFd],
+        },
+      );
+      if (built.error || built.status !== 0 || built.signal)
+        throw failure("native-build-failed");
+    }
+    imageFd = fs.openSync(
+      `/proc/self/fd/${directoryFd}/supervisor`,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    fs.fchmodSync(imageFd, 0o500);
+    const image = readDescriptor(imageFd, MAX_IMAGE_BYTES);
+    if (
+      image.stat.uid !== BigInt(process.getuid()) ||
+      image.stat.nlink !== 1n ||
+      (image.stat.mode & 0o777n) !== 0o500n
+    )
+      throw failure("untrusted-helper-image");
+    validateLinuxSubreaperElf(image.bytes, {
+      arch: process.arch,
+      staticOnly: Boolean(packaged),
+    });
+    if (packaged && sha(image.bytes) !== packaged.identity.imageDigest)
+      throw failure("packaged-copy-changed");
+    // Remove the name before granting a launch lease. The executable can only
+    // be reached through the held descriptor; a later pathname swap is inert.
+    fs.unlinkSync(`/proc/self/fd/${directoryFd}/supervisor`);
+    imagePath = null;
+    const held = fs.fstatSync(imageFd, { bigint: true });
+    if (
+      held.nlink !== 0n ||
+      held.dev !== image.stat.dev ||
+      held.ino !== image.stat.ino
+    )
+      throw failure("helper-unlink-unconfirmed");
+    const entry = {
+      fd: imageFd,
+      dev: held.dev,
+      ino: held.ino,
+      digest: sha(image.bytes),
+      distribution: packaged ? "packaged-static" : "local-build",
+    };
+    imageFd = null;
+    return entry;
+  } catch (error) {
+    if (error.code === "EXTERNAL_AGENT_HELPER_UNAVAILABLE") throw error;
+    // Do not expose compiler stdout/stderr, paths, environment, or native argv.
+    throw failure(
+      error.code === "ENOENT"
+        ? "system-compiler-or-source-missing"
+        : "native-build-setup-failed",
+    );
+  } finally {
+    if (sourceFd !== null) fs.closeSync(sourceFd);
+    if (imageFd !== null) fs.closeSync(imageFd);
+    if (imagePath && directoryFd !== null) {
+      try {
+        fs.unlinkSync(`/proc/self/fd/${directoryFd}/supervisor`);
+      } catch {
+        /* Preserve the admission failure. */
+      }
+    }
+    if (directoryFd !== null) fs.closeSync(directoryFd);
+    if (temporaryRoot) {
+      try {
+        fs.rmdirSync(temporaryRoot);
+      } catch {
+        /* Never recursively remove an unexpected build entry. */
+      }
+    }
+  }
+}
+
+/** Acquire a one-use descriptor lease from trusted packaged source. */
+export function acquireLinuxSubreaperHelper({ spawnSync }) {
+  if (process.platform !== "linux" || typeof spawnSync !== "function")
+    throw failure("unsupported-host");
+  let entry = images.get(spawnSync);
+  if (!entry) {
+    entry = compileImage(spawnSync);
+    images.set(spawnSync, entry);
+    // Outstanding leases hold their own duplicated descriptor. Bound cached
+    // native-seam variants without invalidating already-started children.
+    if (images.size > 4) {
+      const oldest = images.keys().next().value;
+      fs.closeSync(images.get(oldest).fd);
+      images.delete(oldest);
+    }
+  }
+  const held = readDescriptor(entry.fd, MAX_IMAGE_BYTES);
+  if (
+    held.stat.dev !== entry.dev ||
+    held.stat.ino !== entry.ino ||
+    held.stat.nlink !== 0n ||
+    sha(held.bytes) !== entry.digest
+  )
+    throw failure("cached-helper-changed");
+  const descriptor = fs.openSync(
+    `/proc/self/fd/${entry.fd}`,
+    fs.constants.O_RDONLY,
+  );
+  try {
+    const borrowed = fs.fstatSync(descriptor, { bigint: true });
+    if (
+      borrowed.dev !== entry.dev ||
+      borrowed.ino !== entry.ino ||
+      borrowed.nlink !== 0n
+    )
+      throw failure("helper-lease-changed");
+  } catch (error) {
+    fs.closeSync(descriptor);
+    throw error;
+  }
+  const lease = Object.freeze({ kind: "linux-subreaper-helper-lease/v1" });
+  leases.set(lease, {
+    descriptor,
+    sourceDigest: LINUX_SUBREAPER_SOURCE_DIGEST,
+    imageDigest: entry.digest,
+    distribution: entry.distribution,
+  });
+  return lease;
+}
+
+export function consumeLinuxSubreaperHelper(lease) {
+  const entry = leases.get(lease);
+  if (!entry) throw failure("invalid-or-consumed-helper-lease");
+  leases.delete(lease);
+  let released = false;
+  return Object.freeze({
+    ...entry,
+    release() {
+      if (!released) {
+        released = true;
+        fs.closeSync(entry.descriptor);
+      }
+    },
+  });
+}