totemlayer 0.1.63 → 0.1.67

package/bin/process-isolation.mjs

@@ -1,10 +1,11 @@
-import { access, realpath, stat } from "node:fs/promises";
+import { access, copyFile, cp, mkdir, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { dirname, isAbsolute, join, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isolationError } from "./inference-broker.mjs";
 
 const entry = fileURLToPath(new URL("./isolated-agent-entry.mjs", import.meta.url));
+const darwinSupervisor = fileURLToPath(new URL("./native/darwin-lifetime", import.meta.url));
 const safePath = (path) => isAbsolute(path) && !/[\x00-\x1f]/u.test(path);
 async function exists(path) {
   try {
@@ -105,8 +106,7 @@ export function seatbeltProfile({ root, readPaths, codeRoots = [], port }) {
   return (
     `(version 1)\n(deny default)\n` +
     `(allow process-fork process-exec)\n` +
-    // CoreFoundation's managed-preference checks need POSIX account lookup.
-    // This is libinfo only: preference daemons, Keychain and owner files stay denied.
+    // Account lookup only; preferences, Keychain and owner files remain denied.
     `(allow mach-lookup (global-name "com.apple.system.opendirectoryd.libinfo"))\n` +
     `(allow sysctl-read ${systemInfo.map((name) => `(sysctl-name ${quote(name)})`).join(" ")} (sysctl-name-prefix "hw.optional."))\n` +
     `(allow file-read-metadata ${[...metadata].map((path) => `(literal ${quote(path)})`).join(" ")})\n` +
@@ -130,12 +130,12 @@ export async function isolatedInvocation({
 }) {
   const backend = await isolationBackend(platform);
   root = await realpath(root);
-  const executable = await resolveAgentExecutable(command, environment);
-  const node = await realpath(process.execPath);
+  let executable = await resolveAgentExecutable(command, environment);
+  let node = await realpath(process.execPath);
   args = await Promise.all(
     args.map((arg) => (typeof arg === "string" && isAbsolute(arg) ? realpath(arg) : arg)),
   );
-  const readPaths = [
+  let readPaths = [
     ...new Set(
       await Promise.all(
         [
@@ -154,7 +154,38 @@ export async function isolatedInvocation({
   // Installed package code is a trusted executable dependency, never a user home
   // or project directory. Standalone scripts expose only their exact code files.
   const packageMatch = executable.match(/^(.*\/node_modules\/(?:@[^/]+\/)?[^/]+)\//u);
-  const codeRoots = packageMatch ? [packageMatch[1]] : [];
+  let codeRoots = packageMatch ? [packageMatch[1]] : [];
+  if (backend === "seatbelt") {
+    // launchd does not inherit the caller's access to TCC-protected folders.
+    // Stage only the code already approved above, preserving its relative layout.
+    const protectedCode =
+      /^\/(?:System\/Volumes\/Data\/)?Users\/[^/]+\/(?:Documents|Desktop|Downloads|Library\/(?:Mobile Documents|CloudStorage))(?:\/|$)/u;
+    const staged = new Map();
+    const destination = (path) => join(root, "code", path.slice(1));
+    for (const path of codeRoots.filter((path) => protectedCode.test(path))) {
+      await mkdir(dirname(destination(path)), { recursive: true });
+      // Do not dereference package symlinks into unapproved owner files.
+      await cp(path, destination(path), {
+        recursive: true,
+        dereference: false,
+        verbatimSymlinks: true,
+      });
+      staged.set(path, destination(path));
+    }
+    for (const path of readPaths.filter((path) => protectedCode.test(path))) {
+      const target = destination(path);
+      if (!codeRoots.some((parent) => path.startsWith(`${parent}/`) && staged.has(parent))) {
+        await mkdir(dirname(target), { recursive: true });
+        await copyFile(path, target);
+      }
+      staged.set(path, target);
+    }
+    executable = staged.get(executable) ?? executable;
+    node = staged.get(node) ?? node;
+    args = args.map((arg) => staged.get(arg) ?? arg);
+    readPaths = readPaths.map((path) => staged.get(path) ?? path);
+    codeRoots = codeRoots.map((path) => staged.get(path) ?? path);
+  }
   const childEnv = {
     PATH: `${dirname(node)}:/usr/local/bin:/usr/bin:/bin`,
     HOME: root,
@@ -168,10 +199,21 @@ export async function isolatedInvocation({
     LANG: "en_US.UTF-8",
     ...env,
   };
-  if (backend === "seatbelt")
+  if (backend === "seatbelt") {
+    try {
+      await access(darwinSupervisor, constants.X_OK);
+    } catch {
+      throw isolationError(
+        "ISOLATION_UNAVAILABLE",
+        "The macOS process lifetime supervisor is missing. Reinstall the CLI before running native agents.",
+      );
+    }
     return {
-      command: "/usr/bin/sandbox-exec",
+      command: darwinSupervisor,
       args: [
+        "--status-fd=3",
+        "--",
+        "/usr/bin/sandbox-exec",
         "-p",
         seatbeltProfile({ root, readPaths, codeRoots, port: broker?.port ?? null }),
         executable,
@@ -180,7 +222,9 @@ export async function isolatedInvocation({
       env: childEnv,
       cwd: root,
       inheritSystemEnvironment: false,
+      managedLifecycle: "darwin-coalition",
     };
+  }
   const bargs = [
     "--die-with-parent",
     "--new-session",

package/bin/runtime-archive.mjs

@@ -0,0 +1,131 @@
+import { gzipSync, gunzipSync } from "node:zlib";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+export const MAX_RUNTIME_BYTES = 256 * 1024 * 1024;
+const MAX_FILES = 12000;
+const invalid = () => new Error("Invalid runtime update archive.");
+function archivePath(value) {
+  if (
+    typeof value !== "string" ||
+    Buffer.byteLength(value) > 255 ||
+    !value.startsWith("node_modules/") ||
+    /[\\:\u0000-\u001f\u007f]/.test(value) ||
+    value.split("/").some((part) => !part || part === "." || part === "..")
+  )
+    throw invalid();
+  return value;
+}
+function octal(buffer, start, length, value) {
+  const text = value.toString(8);
+  if (text.length >= length) throw invalid();
+  buffer.write(text.padStart(length - 1, "0") + "\0", start, length, "ascii");
+}
+function checksum(header) {
+  let sum = 0;
+  for (let index = 0; index < 512; index++) sum += index >= 148 && index < 156 ? 32 : header[index];
+  return sum;
+}
+export async function buildRuntimeArchive(root) {
+  const chunks = [];
+  let count = 0,
+    total = 0;
+  async function walk(relative) {
+    const names = (await readdir(join(root, relative))).sort();
+    for (const name of names) {
+      const path = archivePath(relative + "/" + name);
+      const info = await lstat(join(root, path));
+      if (info.isSymbolicLink()) throw invalid();
+      if (info.isDirectory()) {
+        await walk(path);
+        continue;
+      }
+      if (!info.isFile() || ++count > MAX_FILES || (total += info.size) > MAX_RUNTIME_BYTES)
+        throw invalid();
+      const data = await readFile(join(root, path));
+      const header = Buffer.alloc(512);
+      const split = path.lastIndexOf("/");
+      const short = Buffer.byteLength(path) <= 100 ? path : path.slice(split + 1);
+      const prefix = short === path ? "" : path.slice(0, split);
+      if (Buffer.byteLength(short) > 100 || Buffer.byteLength(prefix) > 155) throw invalid();
+      header.write(short, 0, 100, "utf8");
+      octal(header, 100, 8, info.mode & 0o111 ? 0o700 : 0o600);
+      octal(header, 108, 8, 0);
+      octal(header, 116, 8, 0);
+      octal(header, 124, 12, data.length);
+      octal(header, 136, 12, 0);
+      header.write("0", 156);
+      header.write("ustar\0", 257);
+      header.write("00", 263);
+      header.write(prefix, 345, 155, "utf8");
+      octal(header, 148, 8, checksum(header));
+      chunks.push(header, data, Buffer.alloc((512 - (data.length % 512)) % 512));
+    }
+  }
+  await walk("node_modules");
+  chunks.push(Buffer.alloc(1024));
+  const tar = Buffer.concat(chunks);
+  if (tar.length > MAX_RUNTIME_BYTES) throw invalid();
+  const archive = gzipSync(tar, { level: 9 });
+  if (archive.length > MAX_ARCHIVE_BYTES) throw invalid();
+  return archive;
+}
+export async function extractRuntimeArchive(archive, destination) {
+  if (archive.length > MAX_ARCHIVE_BYTES) throw invalid();
+  const data = gunzipSync(archive, { maxOutputLength: MAX_RUNTIME_BYTES });
+  const seen = new Set();
+  let offset = 0,
+    ended = false;
+  const text = (buffer, start, size) =>
+    buffer
+      .subarray(start, start + size)
+      .toString("utf8")
+      .replace(/\0.*$/s, "");
+  const number = (buffer, start, size) => {
+    const value = text(buffer, start, size).trim();
+    if (!/^[0-7]+$/.test(value)) throw invalid();
+    const result = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(result) || result < 0) throw invalid();
+    return result;
+  };
+  while (offset + 512 <= data.length) {
+    const header = data.subarray(offset, offset + 512);
+    if (header.every((value) => value === 0)) {
+      ended = true;
+      break;
+    }
+    if (
+      text(header, 257, 6) !== "ustar" ||
+      ![0, 48].includes(header[156]) ||
+      text(header, 157, 100) ||
+      number(header, 148, 8) !== checksum(header)
+    )
+      throw invalid();
+    const prefix = text(header, 345, 155);
+    const path = archivePath((prefix ? prefix + "/" : "") + text(header, 0, 100));
+    const size = number(header, 124, 12);
+    const mode = number(header, 100, 8);
+    if (seen.has(path) || seen.size >= MAX_FILES || offset + 512 + size > data.length)
+      throw invalid();
+    seen.add(path);
+    const target = join(destination, path);
+    // Every parent is created inside a new, private staging directory.
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    const handle = await open(
+      target,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+      mode & 0o111 ? 0o700 : 0o600,
+    );
+    try {
+      await handle.writeFile(data.subarray(offset + 512, offset + 512 + size));
+    } finally {
+      await handle.close();
+    }
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  if (!ended || seen.size === 0 || data.subarray(offset).some((value) => value !== 0))
+    throw invalid();
+  return seen.size;
+}

package/bin/runtime-diagnostics.mjs

@@ -7,6 +7,9 @@ const MISSION_ERROR_CODES = new Map([
 ]);
 
 export const RUNTIME_ERROR_CODES = new Set([
+  "LISTENER_STARTUP_UNAVAILABLE",
+  "LISTENER_HEARTBEAT_TIMEOUT",
+  "LISTENER_PROCESS_UNVERIFIED",
   ...MISSION_ERROR_CODES.values(),
   "AGENT_START_FAILED",
   "AGENT_EXIT_FAILED",

package/bin/runtime-installation.mjs

@@ -60,15 +60,50 @@ export async function privateWrite(path, value) {
 export async function ensureInstalledRuntime(env = process.env) {
   const root = runtimeRoot(env);
   await privateDirectory(root);
+  await privateDirectory(join(root, "runtime"));
+  const { withRuntimeUpdateLock } = await import("./runtime-update.mjs");
+  return withRuntimeUpdateLock(root, () => installRuntimeUnlocked(env), { waitMs: 20000 });
+}
+async function installRuntimeUnlocked(env) {
+  const root = runtimeRoot(env);
+  const { compareRuntimeVersions } = await import("./runtime-update.mjs");
+  let previousRecord = {};
   let previousVersion;
   try {
-    previousVersion = (await privateRead(join(root, "runtime", "current.json"))).version;
+    previousRecord = await privateRead(join(root, "runtime", "current.json"));
+    previousVersion = previousRecord.version;
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
   const metadata = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
   if (!/^\d+\.\d+\.\d+$/.test(metadata.version)) throw new Error("Invalid runtime version.");
   const runtime = join(root, "runtime");
+  // A pinned bootstrap is still useful after an update; it must never downgrade the managed copy.
+  if (previousVersion && compareRuntimeVersions(previousVersion, metadata.version) > 0) {
+    const installed = JSON.parse(
+      await readFile(
+        join(
+          root,
+          "runtime-packages",
+          previousVersion,
+          "node_modules",
+          "totemlayer",
+          "package.json",
+        ),
+        "utf8",
+      ),
+    );
+    if (installed.name !== "totemlayer" || installed.version !== previousVersion)
+      throw new Error("Invalid managed runtime installation.");
+    return {
+      root,
+      cli: join(runtime, "totem.mjs"),
+      supervisor: join(runtime, "supervisor.mjs"),
+      directory: runtime,
+      version: previousVersion,
+      upgraded: false,
+    };
+  }
   const modules = join(root, "runtime-packages", metadata.version, "node_modules");
   const destination = join(modules, "totemlayer");
   await privateDirectory(runtime);
@@ -118,6 +153,11 @@ export async function ensureInstalledRuntime(env = process.env) {
       }
       if (!selected) throw new Error("Install Totem's runtime dependencies before starting it.");
       const dependencyManifest = JSON.parse(await readFile(join(selected, "package.json"), "utf8"));
+      if (
+        dependency.from === packageRoot &&
+        dependencyManifest.version !== metadata.dependencies[dependency.name]
+      )
+        throw new Error("Runtime dependency does not match the pinned release version.");
       if (copied.has(dependency.name)) {
         if (copied.get(dependency.name) !== dependencyManifest.version)
           throw new Error("Conflicting runtime dependency versions.");
@@ -169,7 +209,7 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
     catch (error) { if (error.code !== 'ENOENT') throw error; }
   }
   // Node reads proxy opt-in and extra CA configuration at process startup.
-  let stopping = false, child;
+  let stopping = false, child, failures = 0;
   const controller = new AbortController();
   const handlers = ['SIGTERM', 'SIGINT'].map((signal) => [signal, () => {
     stopping = true; controller.abort(); child?.kill(signal);
@@ -185,7 +225,22 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
       child.once('error', () => resolve(1));
       child.once('exit', (code) => resolve(code ?? 1));
     });
-    ${target === "automatic-runtime.mjs" ? `if (code === 0) break;\n    if (!stopping) await delay(Date.now() - started < 30000 ? 30000 : 1000, undefined, { signal: controller.signal }).catch(() => {});` : "process.exitCode = code;"}
+    ${
+      target === "automatic-runtime.mjs"
+        ? `if (code === 0) break;
+    if (!stopping && code !== 75 && Date.now() - started < 30000) failures++;
+    else failures = 0;
+    if (!stopping && failures >= 3) {
+      try {
+        const latest = JSON.parse(await readFile(file, 'utf8'));
+        const { rollbackRuntimeUpdate } = await import(pathToFileURL(join(root, '..', 'runtime-packages', version, 'node_modules', 'totemlayer', 'bin', 'runtime-update.mjs')));
+        await rollbackRuntimeUpdate(latest.version, { ...environment, TOTEM_CONFIG_DIR: join(root, '..') });
+      } catch {}
+      failures = 0;
+    }
+    if (!stopping) await delay(code === 75 ? 100 : Date.now() - started < 30000 ? 30000 : 1000, undefined, { signal: controller.signal }).catch(() => {});`
+        : "process.exitCode = code;"
+    }
   } while (${target === "automatic-runtime.mjs" ? "!stopping" : "false"});
   for (const [signal, handler] of handlers) process.removeListener(signal, handler);
 }
@@ -205,7 +260,11 @@ if (process.env.TOTEM_RUNTIME_ENV_LOADED === entry) {
       await handle.close();
     }
   }
-  await privateWrite(join(runtime, "current.json"), { version: metadata.version });
+  if (previousVersion !== metadata.version)
+    await privateWrite(join(runtime, "current.json"), {
+      version: metadata.version,
+      ...(previousVersion ? { previousVersion } : {}),
+    });
   return {
     root,
     cli,
@@ -503,6 +562,22 @@ export async function installRuntimeService(runtime, env = process.env, options
       await run("systemctl", ["--user", "daemon-reload"]);
       await run("systemctl", ["--user", "enable", "--now", unit]);
       if (runtime.upgraded) await run("systemctl", ["--user", "restart", unit]);
+      const enabled = await run("systemctl", ["--user", "is-enabled", unit]);
+      const active = await run("systemctl", ["--user", "is-active", unit]);
+      const loaded = await run("systemctl", [
+        "--user",
+        "show",
+        unit,
+        "--property=ExecStart",
+        "--value",
+      ]);
+      if (
+        enabled.stdout.trim() !== "enabled" ||
+        active.stdout.trim() !== "active" ||
+        !loaded.stdout.includes(node) ||
+        !loaded.stdout.includes(runtime.supervisor)
+      )
+        throw new Error("The exact persistent listener service is not enabled and active.");
       return acknowledged({ mode: "systemd-user", persistent: true, label: unit, path });
     }
     if (platform === "win32") {
@@ -513,6 +588,17 @@ export async function installRuntimeService(runtime, env = process.env, options
   } catch {
     /* Ephemeral/headless hosts often have no user service manager. */
   }
+  if (windowsRegistration?.mode !== "startup-shortcut")
+    return {
+      mode: "unavailable",
+      persistent: false,
+      code:
+        startupCode ??
+        windowsRegistration?.code ??
+        (platform === "darwin" || platform === "win32"
+          ? "STARTUP_REGISTRATION_FAILED"
+          : "LISTENER_STARTUP_UNAVAILABLE"),
+    };
   const child = (options.spawn ?? spawn)(node, [runtime.supervisor], {
     env: { ...env, TOTEM_CONFIG_DIR: runtime.root },
     stdio: "ignore",
@@ -521,13 +607,5 @@ export async function installRuntimeService(runtime, env = process.env, options
   });
   child.on("error", () => {});
   child.unref();
-  return windowsRegistration?.mode === "startup-shortcut"
-    ? acknowledged({ mode: "startup-shortcut", persistent: true, label: task })
-    : {
-        mode: "background-supervisor",
-        persistent: false,
-        ...(["win32", "darwin"].includes(platform)
-          ? { code: startupCode ?? windowsRegistration?.code ?? "STARTUP_REGISTRATION_FAILED" }
-          : {}),
-      };
+  return acknowledged({ mode: "startup-shortcut", persistent: true, label: task });
 }

package/bin/runtime-lock.mjs

@@ -0,0 +1,118 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { lstat, rename, readdir, unlink, rmdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { powershellInvocation } from "./platform-client.mjs";
+import { privateDirectory, privateRead, privateWrite } from "./runtime-installation.mjs";
+
+const execute = promisify(execFile);
+export async function processIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 1) return null;
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    if (error.code === "ESRCH") return null;
+    throw error;
+  }
+  // PID reuse across reboot must not make an abandoned lock permanent. A failed
+  // process inspection is uncertainty, never evidence that another owner died.
+  const invocation =
+    process.platform === "win32"
+      ? powershellInvocation(
+          `$p=Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}';if(!$p){exit 1};$p|Select-Object ProcessId,CreationDate,CommandLine|ConvertTo-Json -Compress`,
+          process.env,
+        )
+      : { command: "ps", args: ["-p", String(pid), "-o", "lstart=", "-o", "args="] };
+  const result = await execute(invocation.command, invocation.args, {
+    encoding: "utf8",
+    timeout: 3000,
+    maxBuffer: 8192,
+  });
+  if (!result.stdout.trim()) throw new Error("Cannot verify the supervisor process identity.");
+  return result.stdout.trim();
+}
+export async function readSupervisorOwner(lock) {
+  const info = await lstat(lock);
+  if (
+    !info.isDirectory() ||
+    info.isSymbolicLink() ||
+    (process.getuid && info.uid !== process.getuid()) ||
+    (process.platform !== "win32" && (info.mode & 0o777) !== 0o700)
+  )
+    throw new Error("Unsafe supervisor lock.");
+  const names = await readdir(lock);
+  if (!names.length) return null;
+  if (names.length !== 1 || !/^(?:owner|owner-[a-f0-9-]{36})\.json$/.test(names[0]))
+    throw new Error("The supervisor lock contains unrecognized state.");
+  const owner = await privateRead(join(lock, names[0]));
+  if (
+    !Number.isSafeInteger(owner?.pid) ||
+    owner.pid <= 1 ||
+    (names[0] !== "owner.json" &&
+      (names[0] !== `owner-${owner.token}.json` ||
+        typeof owner.identity !== "string" ||
+        !owner.identity))
+  )
+    throw new Error("Invalid supervisor owner.");
+  return { file: names[0], owner };
+}
+export async function acquireSupervisorLock(directory, options = {}) {
+  const lock = join(directory, "supervisor.lock");
+  const stage = join(directory, `supervisor-start-${randomUUID()}`);
+  const token = randomUUID();
+  const ownerFile = `owner-${token}.json`;
+  const identity = options.processIdentity ?? processIdentity;
+  await privateDirectory(directory);
+  const owner = { pid: process.pid, token, identity: await identity(process.pid) };
+  if (!owner.identity) throw new Error("Cannot verify this supervisor process.");
+  await privateDirectory(stage);
+  await privateWrite(join(stage, ownerFile), owner);
+  const removeObserved = async (file) => {
+    if (file)
+      await unlink(join(lock, file)).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    // Never recursively delete or rename the shared lock path. A replacement
+    // contains its own unique owner file and makes rmdir fail with ENOTEMPTY.
+    await rmdir(lock).catch((error) => {
+      if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error;
+    });
+  };
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const snapshot = await lstat(lock).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+        return null;
+      });
+      if (snapshot) {
+        const current = await readSupervisorOwner(lock).catch((error) => {
+          if (error.code !== "ENOENT") throw error;
+          return undefined;
+        });
+        if (current === undefined) continue;
+        if (!current) {
+          if (Date.now() - snapshot.mtimeMs < (options.emptyLockGraceMs ?? 30000))
+            throw new Error("Another supervisor is starting. Wait before retrying.");
+        } else {
+          const actual = await identity(current.owner.pid);
+          if (actual && (!current.owner.identity || current.owner.identity === actual))
+            throw Object.assign(new Error("The Totem supervisor is already running."), {
+              code: "SUPERVISOR_ALREADY_RUNNING",
+            });
+        }
+        await removeObserved(current?.file);
+      }
+      try {
+        // Publish owner and lock together. New installations never expose an empty lock.
+        await rename(stage, lock);
+        return () => removeObserved(ownerFile);
+      } catch (error) {
+        if (!["EEXIST", "ENOTEMPTY", "ENOENT"].includes(error.code)) throw error;
+      }
+    }
+    throw new Error("Another supervisor is starting. Wait before retrying.");
+  } finally {
+    await rm(stage, { recursive: true, force: true });
+  }
+}