chainlesschain 0.166.85 → 0.166.87

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

@@ -53,6 +53,7 @@ import {
   getProcessOwnershipStatus,
   observeProcessOwnership,
   prepareProcessOwnership,
+  recoverProcessOwnership,
 } from "./process-ownership-quarantine.js";
 import {
   MACOS_MCP_LAUNCHER_INPUTS,
@@ -4525,6 +4526,10 @@ class ProcessExecutionBroker extends EventEmitter {
     return getProcessOwnershipStatus();
   }
 
+  recoverProcessOwnership(executionId, options) {
+    return recoverProcessOwnership(executionId, options);
+  }
+
   listWorkspaceTransactions(options = {}) {
     return this._workspaceTransactionManager(
       options.stateDir,
@@ -4873,6 +4878,9 @@ class ProcessExecutionBroker extends EventEmitter {
               cwd: path.resolve(optsForSpawn.cwd || cwd),
               env: optsForSpawn.env || process.env,
               graceMs: request.graceMs,
+              ...(ownershipLease?.beforeLaunch
+                ? { beforeLaunch: ownershipLease.beforeLaunch }
+                : {}),
               helper,
             },
             {

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

@@ -96,10 +96,22 @@ export function spawnLinuxSubreaper(command, args, options, native) {
     if (
       Object.keys(options).some(
         (key) =>
-          !["cwd", "env", "graceMs", "helperPath", "helper"].includes(key),
+          ![
+            "cwd",
+            "env",
+            "graceMs",
+            "helperPath",
+            "helper",
+            "beforeLaunch",
+          ].includes(key),
       )
     )
       throw new TypeError("Unsupported Linux subreaper option");
+    if (
+      options.beforeLaunch !== undefined &&
+      typeof options.beforeLaunch !== "function"
+    )
+      throw new TypeError("Invalid trusted before-launch hook");
     launch = encodeLinuxSubreaperLaunch(command, args, options);
     child = native.spawn(helper ? "/proc/self/fd/4" : options.helperPath, [], {
       cwd: options.cwd,
@@ -249,7 +261,17 @@ export function spawnLinuxSubreaper(command, args, options, native) {
       });
     });
   });
-  control.write(launch);
+  try {
+    const result = options.beforeLaunch?.(child);
+    if (result && typeof result.then === "function")
+      throw new TypeError("Before-launch hook must be synchronous");
+    control.write(launch);
+  } catch (error) {
+    // No launch frame was sent. Closing the private control channel releases
+    // the blocked supervisor without executing the target.
+    control.destroy();
+    throw error;
+  }
   return Object.freeze({ child, terminate, completion });
 }
 

package/src/lib/process-execution-broker/process-ownership-journal.js

@@ -4,11 +4,17 @@ import { randomUUID } from "node:crypto";
 import { withFileLock } from "../with-file-lock.js";
 import { writeSecurityStore } from "../durable-security-store.js";
 import { ensurePrivateDirectory } from "../secure-fs.js";
+import { performance } from "node:perf_hooks";
+import {
+  openRecoveryCgroup,
+  validateRecoveryCgroup,
+} from "./process-recovery-cgroup.js";
 
 export const PROCESS_OWNERSHIP_PENDING = "BROKER_PROCESS_OWNERSHIP_PENDING";
 export const PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE =
   "BROKER_PROCESS_OWNERSHIP_JOURNAL_UNAVAILABLE";
 const SCHEMA = "chainlesschain.process-ownership-journal/v1";
+const RECOVERY_SCHEMA = "chainlesschain.process-ownership-journal/v2";
 const MAX_BYTES = 1024 * 1024;
 const MAX_PENDING = 1024;
 const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
@@ -27,8 +33,12 @@ function unavailable(cause) {
 function validate(state) {
   if (
     !state ||
-    Object.keys(state).sort().join() !== "pending,schema" ||
-    state.schema !== SCHEMA ||
+    !(
+      (state.schema === SCHEMA &&
+        Object.keys(state).sort().join() === "pending,schema") ||
+      (state.schema === RECOVERY_SCHEMA &&
+        Object.keys(state).sort().join() === "pending,recoveries,schema")
+    ) ||
     !Array.isArray(state.pending) ||
     state.pending.length > MAX_PENDING
   )
@@ -37,7 +47,12 @@ function validate(state) {
   for (const entry of state.pending) {
     if (
       !entry ||
-      Object.keys(entry).sort().join() !== "executionId,ownerPid,token" ||
+      ![
+        "executionId,ownerPid,token",
+        ...(state.schema === RECOVERY_SCHEMA
+          ? ["executionId,ownerPid,recovery,token"]
+          : []),
+      ].includes(Object.keys(entry).sort().join()) ||
       !UUID.test(entry.executionId) ||
       !UUID.test(entry.token) ||
       !Number.isSafeInteger(entry.ownerPid) ||
@@ -45,8 +60,31 @@ function validate(state) {
       ids.has(entry.executionId)
     )
       throw new Error("Invalid ownership journal entry");
+    if (Object.hasOwn(entry, "recovery"))
+      validateRecoveryCgroup(entry.recovery, entry.executionId);
     ids.add(entry.executionId);
   }
+  if (state.schema === RECOVERY_SCHEMA) {
+    if (
+      !Array.isArray(state.recoveries) ||
+      state.recoveries.length > MAX_PENDING
+    )
+      throw new Error("Invalid recovery audit inventory");
+    for (const receipt of state.recoveries) {
+      if (
+        !receipt ||
+        Object.keys(receipt).sort().join() !==
+          "completedAt,executionId,group,killIssued,populated,token" ||
+        !UUID.test(receipt.executionId) ||
+        !UUID.test(receipt.token) ||
+        receipt.killIssued !== true ||
+        receipt.populated !== false ||
+        !Number.isFinite(Date.parse(receipt.completedAt))
+      )
+        throw new Error("Invalid recovery audit receipt");
+      validateRecoveryCgroup(receipt.group, receipt.executionId);
+    }
+  }
   return state;
 }
 
@@ -211,6 +249,13 @@ export class ProcessOwnershipJournal {
     }
   }
 
+  #write(file, state, label = "Process ownership") {
+    validate(state);
+    if (Buffer.byteLength(`${JSON.stringify(state, null, 2)}\n`) > MAX_BYTES)
+      throw new Error("Ownership journal byte capacity is exhausted");
+    writeSecurityStore(file, label, state);
+  }
+
   assertAvailable() {
     if (this.#fault) throw this.#fault;
     this.#withDirectory(false, (file) => this.#assertState(this.#read(file)));
@@ -222,6 +267,9 @@ export class ProcessOwnershipJournal {
       const state = this.#read(file);
       return {
         pendingExecutionIds: state.pending.map((entry) => entry.executionId),
+        recoverableExecutionIds: state.pending
+          .filter((entry) => entry.recovery)
+          .map((entry) => entry.executionId),
         blocked: state.pending.some(
           (entry) => this.#local.get(entry.executionId)?.token !== entry.token,
         ),
@@ -229,24 +277,34 @@ export class ProcessOwnershipJournal {
     });
   }
 
-  prepare(executionId) {
+  prepare(executionId, recovery = null) {
     if (!UUID.test(executionId))
       throw new TypeError("Invalid ownership execution id");
     if (this.#fault) throw this.#fault;
-    const entry = { executionId, ownerPid: process.pid, token: randomUUID() };
+    if (recovery) validateRecoveryCgroup(recovery, executionId);
+    const entry = {
+      executionId,
+      ownerPid: process.pid,
+      token: randomUUID(),
+      ...(recovery ? { recovery: { ...recovery } } : {}),
+    };
     this.#withDirectory(true, (file) =>
       withFileLock(
         file,
         () => {
           const state = this.#read(file);
           this.#assertState(state);
+          if (recovery && state.schema === SCHEMA) {
+            state.schema = RECOVERY_SCHEMA;
+            state.recoveries = [];
+          }
           if (
             state.pending.length >= MAX_PENDING ||
             state.pending.some((item) => item.executionId === executionId)
           )
             throw new Error("Ownership journal admission limit");
           state.pending.push(entry);
-          writeSecurityStore(file, "Process ownership", state);
+          this.#write(file, state);
           this.#initialized = true;
           this.#local.set(executionId, entry);
         },
@@ -284,7 +342,7 @@ export class ProcessOwnershipJournal {
               state.pending = state.pending.filter(
                 (item) => item.executionId !== executionId,
               );
-              writeSecurityStore(file, "Process ownership", state);
+              this.#write(file, state);
               this.#local.delete(executionId);
               settled = true;
             },
@@ -294,4 +352,107 @@ export class ProcessOwnershipJournal {
       },
     });
   }
+
+  /** Explicitly cancel an orphaned, identity-bound cgroup. Old PID-only records
+   * remain quarantined. Neither process death nor age is a cleanup authority.
+   */
+  async recover(executionId, { timeoutMs = 5000, pollMs = 10 } = {}) {
+    if (
+      !UUID.test(executionId) ||
+      !Number.isSafeInteger(timeoutMs) ||
+      timeoutMs < 1 ||
+      timeoutMs > 30000 ||
+      !Number.isSafeInteger(pollMs) ||
+      pollMs < 1 ||
+      pollMs > 1000
+    )
+      throw new TypeError("Invalid process recovery request");
+    if (this.#fault) throw this.#fault;
+    if (this.#local.has(executionId))
+      throw unavailable(
+        new Error(
+          "A locally owned live launch must use its normal cancellation fence",
+        ),
+      );
+    const entry = this.#withDirectory(false, (file) => {
+      const state = this.#read(file);
+      const found = state.pending.find(
+        (item) => item.executionId === executionId,
+      );
+      if (!found?.recovery) {
+        const error = new Error(
+          "This pending execution has no recoverable kernel group identity",
+        );
+        error.code = PROCESS_OWNERSHIP_PENDING;
+        error.recoveryRequired = true;
+        throw error;
+      }
+      if (state.recoveries.length >= MAX_PENDING)
+        throw new Error("Recovery audit capacity is exhausted");
+      return { ...found, recovery: { ...found.recovery } };
+    });
+    const group = openRecoveryCgroup(entry.recovery, executionId);
+    let settled = false;
+    try {
+      group.kill();
+      const deadline = performance.now() + timeoutMs;
+      while (group.populated()) {
+        if (performance.now() >= deadline) {
+          const error = new Error(
+            "Recovered process group has not reached its empty kernel fence",
+          );
+          error.code = PROCESS_OWNERSHIP_PENDING;
+          error.recoveryRequired = true;
+          throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+      }
+      const receipt = {
+        executionId,
+        token: entry.token,
+        group: entry.recovery,
+        killIssued: true,
+        populated: false,
+        completedAt: new Date().toISOString(),
+      };
+      this.#withDirectory(false, (file) =>
+        withFileLock(
+          file,
+          () => {
+            const state = this.#read(file);
+            const current = state.pending.find(
+              (item) => item.executionId === executionId,
+            );
+            if (
+              !current ||
+              current.token !== entry.token ||
+              JSON.stringify(current.recovery) !==
+                JSON.stringify(entry.recovery)
+            )
+              throw new Error("Ownership recovery lost its original record");
+            if (state.recoveries.length >= MAX_PENDING)
+              throw new Error("Recovery audit capacity is exhausted");
+            // Check the kernel fence again while committing the durable receipt.
+            group.confirmEmpty();
+            state.pending = state.pending.filter(
+              (item) => item.executionId !== executionId,
+            );
+            state.recoveries.push(receipt);
+            this.#write(file, state, "Process ownership recovery");
+            settled = true;
+          },
+          { failIfUnavailable: true, timeoutMs: 2000 },
+        ),
+      );
+      return { ...receipt, cleanupConfirmed: true, executionResumed: false };
+    } finally {
+      // Publish settlement before removing the empty group. If journal IO
+      // fails, its kernel identity remains available for a safe retry.
+      try {
+        group.close({ remove: settled });
+      } catch {
+        group.close(); /* Empty directory leftovers never certify a run. */
+      }
+    }
+  }
 }

package/src/lib/process-execution-broker/process-ownership-quarantine.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { getMachineSecurityAnchorDir } from "../paths.js";
 import { ProcessOwnershipJournal } from "./process-ownership-journal.js";
+import { prepareRecoveryCgroup } from "./process-recovery-cgroup.js";
 
 // Shared by every Broker in this JS runtime. A new Broker, different cwd or
 // cleared audit history cannot turn a lost process owner into cleanup evidence.
@@ -18,7 +19,60 @@ function durableJournal() {
 }
 
 export function prepareProcessOwnership(executionId) {
-  return durableJournal()?.prepare(executionId) ?? null;
+  const authority = durableJournal();
+  if (!authority) return null;
+  const group = prepareRecoveryCgroup(
+    executionId,
+    process.env.CHAINLESSCHAIN_PROCESS_RECOVERY_CGROUP_ROOT,
+  );
+  if (!group) return authority.prepare(executionId);
+  let lease;
+  try {
+    lease = authority.prepare(executionId, group.identity);
+  } catch (error) {
+    group.close({ remove: true });
+    throw error;
+  }
+  let settled = false,
+    retained = false;
+  return Object.freeze({
+    beforeLaunch: (proc) => group.attachBeforeLaunch(proc),
+    settle() {
+      if (settled) return;
+      if (retained)
+        throw new Error("Retained recovery group requires explicit recovery");
+      try {
+        group.confirmEmpty();
+        lease.settle();
+      } catch (error) {
+        retained = true;
+        lease.retain();
+        group.close();
+        throw error;
+      }
+      settled = true;
+      try {
+        group.close({ remove: true });
+      } catch {
+        group.close();
+      }
+    },
+    retain() {
+      if (settled || retained) return;
+      retained = true;
+      lease.retain();
+      group.close();
+    },
+  });
+}
+
+export async function recoverProcessOwnership(executionId, options) {
+  const authority = durableJournal();
+  if (!authority)
+    throw new Error("Kernel process ownership recovery requires Linux");
+  const receipt = await authority.recover(executionId, options);
+  unresolvedOwners.delete(executionId);
+  return receipt;
 }
 
 export const PROCESS_OWNERSHIP_UNCONFIRMED =
@@ -73,6 +127,7 @@ export function getProcessOwnershipStatus() {
       !!durable &&
       [...unresolvedOwners.values()].every((owner) => owner.durable),
     restartSafe: false,
+    recoverableExecutionIds: durable?.recoverableExecutionIds || [],
   };
 }
 

package/src/lib/process-execution-broker/process-recovery-cgroup.js

@@ -0,0 +1,272 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const PROCESS_RECOVERY_CGROUP_SCHEMA =
+  "chainlesschain.process-recovery-cgroup/v1";
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+const CGROUP2_MAGIC = 0x63677270n;
+const BOOT_ID = "/proc/sys/kernel/random/boot_id";
+
+function denied(message, cause) {
+  return Object.assign(
+    new Error(
+      `Process recovery cgroup is unavailable: ${message}`,
+      cause ? { cause } : undefined,
+    ),
+    {
+      code: "BROKER_PROCESS_RECOVERY_UNAVAILABLE",
+      recoveryRequired: true,
+    },
+  );
+}
+function requireValue(value, reason) {
+  if (!value) throw denied(reason);
+}
+function identity(stat) {
+  return { dev: String(stat.dev), ino: String(stat.ino) };
+}
+function same(stat, expected, prefix = "") {
+  return (
+    String(stat.dev) === expected[`${prefix}dev`] &&
+    String(stat.ino) === expected[`${prefix}ino`]
+  );
+}
+function rootPath(root) {
+  requireValue(
+    typeof root === "string" &&
+      path.posix.isAbsolute(root) &&
+      root !== "/" &&
+      !root.includes("\0") &&
+      !root.split("/").includes(".."),
+    "invalid delegated root",
+  );
+  return path.posix.normalize(root).replace(/\/+$/u, "");
+}
+
+export function validateRecoveryCgroup(value, executionId) {
+  requireValue(
+    value &&
+      Object.keys(value).sort().join() ===
+        "bootId,dev,ino,name,root,rootdev,rootino,schema" &&
+      value.schema === PROCESS_RECOVERY_CGROUP_SCHEMA &&
+      UUID.test(value.bootId) &&
+      UUID.test(executionId) &&
+      value.name === `cc-owner-${executionId}` &&
+      rootPath(value.root) === value.root &&
+      [value.dev, value.ino, value.rootdev, value.rootino].every(
+        (part) => typeof part === "string" && /^\d{1,30}$/u.test(part),
+      ),
+    "invalid persisted group identity",
+  );
+  return value;
+}
+
+function openDirectory(io, directory) {
+  const before = io.lstatSync(directory, { bigint: true });
+  requireValue(
+    before.isDirectory() && !before.isSymbolicLink(),
+    "cgroup path is not a directory",
+  );
+  requireValue(
+    io.realpathSync(directory) === directory,
+    "cgroup path traverses a link",
+  );
+  const fd = io.openSync(
+    directory,
+    io.constants.O_RDONLY | io.constants.O_DIRECTORY | io.constants.O_NOFOLLOW,
+  );
+  try {
+    const opened = io.fstatSync(fd, { bigint: true });
+    requireValue(
+      same(opened, identity(before)),
+      "cgroup directory changed while opening",
+    );
+    requireValue(
+      BigInt(io.statfsSync(`/proc/self/fd/${fd}`, { bigint: true }).type) ===
+        CGROUP2_MAGIC,
+      "not a kernel cgroup v2 filesystem",
+    );
+    return { fd, stat: opened, pinned: `/proc/self/fd/${fd}` };
+  } catch (error) {
+    io.closeSync(fd);
+    throw error;
+  }
+}
+
+/** Kernel object identities, not PIDs, establish the recovery target. The root
+ * must be explicitly delegated by the host. This is cooperative lifecycle
+ * recovery, not confinement against same-UID code that can move cgroup members.
+ */
+export function openRecoveryCgroup(value, executionId, runtime = {}) {
+  const io = runtime.fs || fs;
+  requireValue(
+    (runtime.platform || process.platform) === "linux",
+    "Linux cgroup v2 is required",
+  );
+  validateRecoveryCgroup(value, executionId);
+  requireValue(
+    String(io.readFileSync(BOOT_ID, "utf8")).trim() === value.bootId,
+    "boot identity changed",
+  );
+  const root = openDirectory(io, value.root);
+  let group;
+  try {
+    requireValue(
+      same(root.stat, value, "root"),
+      "delegated root identity changed",
+    );
+    group = openDirectory(io, path.posix.join(value.root, value.name));
+    requireValue(same(group.stat, value), "recovery group identity changed");
+  } catch (error) {
+    if (group) io.closeSync(group.fd);
+    io.closeSync(root.fd);
+    throw error;
+  }
+  let closed = false;
+  const assertIdentity = () => {
+    requireValue(!closed, "group lease was closed");
+    requireValue(
+      String(io.readFileSync(BOOT_ID, "utf8")).trim() === value.bootId,
+      "boot identity changed",
+    );
+    const currentRoot = io.lstatSync(value.root, { bigint: true });
+    const currentGroup = io.lstatSync(path.posix.join(value.root, value.name), {
+      bigint: true,
+    });
+    requireValue(
+      currentRoot.isDirectory() &&
+        !currentRoot.isSymbolicLink() &&
+        same(currentRoot, value, "root") &&
+        currentGroup.isDirectory() &&
+        !currentGroup.isSymbolicLink() &&
+        same(currentGroup, value),
+      "cgroup authority was replaced",
+    );
+  };
+  const populated = () => {
+    assertIdentity();
+    const bytes = io.readFileSync(`${group.pinned}/cgroup.events`, "utf8");
+    requireValue(
+      typeof bytes === "string" && bytes.length <= 4096,
+      "invalid cgroup event payload",
+    );
+    const lines = bytes
+      .trim()
+      .split(/\n/u)
+      .map((line) => line.trim().split(/\s+/u));
+    const entries = lines.filter(([key]) => key === "populated");
+    requireValue(
+      entries.length === 1 &&
+        entries[0].length === 2 &&
+        ["0", "1"].includes(entries[0][1]),
+      "missing or invalid populated fence",
+    );
+    return entries[0][1] === "1";
+  };
+  return Object.freeze({
+    identity: Object.freeze({ ...value }),
+    attachBeforeLaunch(proc) {
+      assertIdentity();
+      requireValue(
+        Number.isSafeInteger(proc?.pid) && proc.pid > 0,
+        "supervisor PID is unavailable",
+      );
+      requireValue(!populated(), "new recovery group was already populated");
+      // The native supervisor is still blocked on its private launch socket.
+      // No target can fork before this write and membership check complete.
+      io.writeFileSync(`${group.pinned}/cgroup.procs`, `${proc.pid}\n`, "utf8");
+      const members = String(
+        io.readFileSync(`${group.pinned}/cgroup.procs`, "utf8"),
+      )
+        .trim()
+        .split(/\s+/u);
+      requireValue(
+        members.includes(String(proc.pid)),
+        "supervisor membership was not observed",
+      );
+    },
+    kill() {
+      assertIdentity();
+      io.writeFileSync(`${group.pinned}/cgroup.kill`, "1\n", "utf8");
+    },
+    populated,
+    confirmEmpty() {
+      requireValue(!populated(), "recovery group remains populated");
+      return true;
+    },
+    close({ remove = false } = {}) {
+      if (closed) return;
+      try {
+        if (remove) {
+          requireValue(
+            !populated(),
+            "cannot remove a populated recovery group",
+          );
+          io.rmdirSync(`${root.pinned}/${value.name}`);
+        }
+      } finally {
+        closed = true;
+        io.closeSync(group.fd);
+        io.closeSync(root.fd);
+      }
+    },
+  });
+}
+
+export function prepareRecoveryCgroup(executionId, rootInput, runtime = {}) {
+  if (!rootInput) return null;
+  const io = runtime.fs || fs;
+  requireValue(
+    (runtime.platform || process.platform) === "linux",
+    "Linux cgroup v2 is required",
+  );
+  requireValue(UUID.test(executionId), "invalid execution identity");
+  const root = rootPath(rootInput);
+  const opened = openDirectory(io, root);
+  const name = `cc-owner-${executionId}`;
+  let created = false;
+  try {
+    const bootId = String(io.readFileSync(BOOT_ID, "utf8")).trim();
+    requireValue(UUID.test(bootId), "boot identity is unavailable");
+    // The unique group is created through the pinned delegated root.
+    io.mkdirSync(`${opened.pinned}/${name}`, { mode: 0o700 });
+    created = true;
+    const directory = path.posix.join(root, name);
+    const stat = io.lstatSync(directory, { bigint: true });
+    const value = {
+      schema: PROCESS_RECOVERY_CGROUP_SCHEMA,
+      root,
+      name,
+      bootId,
+      rootdev: String(opened.stat.dev),
+      rootino: String(opened.stat.ino),
+      ...identity(stat),
+    };
+    const group = openRecoveryCgroup(value, executionId, runtime);
+    try {
+      group.confirmEmpty();
+      // Require the real kernel primitive before a recoverable launch is armed.
+      const killFd = io.openSync(
+        `${directory}/cgroup.kill`,
+        io.constants.O_WRONLY | io.constants.O_NOFOLLOW,
+      );
+      io.closeSync(killFd);
+      return group;
+    } catch (error) {
+      group.close({ remove: true });
+      created = false;
+      throw error;
+    }
+  } catch (error) {
+    if (created) {
+      try {
+        io.rmdirSync(`${opened.pinned}/${name}`);
+      } catch {
+        /* No process was launched into this group. */
+      }
+    }
+    throw denied("preparation failed", error);
+  } finally {
+    io.closeSync(opened.fd);
+  }
+}