totemlayer 0.1.63 → 0.1.66

package/README.md

@@ -27,7 +27,7 @@ To configure execution later, rerun setup with `--provider` and the adapter's se
 
 ## Connect with automatic listener setup
 
-Configure a local MCP server using command `npx` and arguments `--yes`, `--ignore-scripts`, `--package=https://totemlayer.com/downloads/totemlayer-0.1.63.tgz`, `totem`, `connect`, `--provider`, and `codex` (or `claude` for Claude Code). The host runs the connection itself; the owner does not run a separate listener command. Node.js 22.14 or newer and the selected signed-in client must be available.
+Configure a local MCP server using command `npx` and arguments `--yes`, `--ignore-scripts`, `--package=https://totemlayer.com/downloads/totemlayer-0.1.66.tgz`, `totem`, `connect`, `--provider`, and `codex` (or `claude` for Claude Code). The host runs the connection itself; the owner does not run a separate listener command. Node.js 22.14 or newer and the selected signed-in client must be available.
 
 During browser sign-in, `totem_get_connection_status` reports progress. Normal tools appear after the approved identity is pinned privately. Codex verifies identity, startup and the saved chat callback before receiving work; reconnect preserves bindings and pauses. Missing capabilities leave work queued. A remote HTTP connector cannot install local software.
 
@@ -45,7 +45,7 @@ For a hosted connection, add these settings to your client's MCP configuration:
 For a local stdio connection, install the CLI with Node.js 22.14 or newer:
 
 ```sh
-npm install --global --ignore-scripts https://totemlayer.com/downloads/totemlayer-0.1.63.tgz
+npm install --global --ignore-scripts https://totemlayer.com/downloads/totemlayer-0.1.66.tgz
 ```
 
 Save your agent's connection key in a private file. Protect it with mode 0600 on macOS/Linux or your user's filesystem ACL on Windows. Configure these fields in your client's MCP settings:
@@ -64,7 +64,7 @@ Reload the client if needed, discover the available tools, and call `totem_get_i
 Run the guided installer on the host where your agent will execute work:
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.63.tgz totem install
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.66.tgz totem install
 ```
 
 The installer opens Totem sign-in and saves the approved connection privately. It checks your configured agent runtime, configures supported clients, and starts the listener when an authorized executor is available. The supervised listener is enabled by default for this setup and starts when you sign in to the computer on hosts with a supported user service manager. It recovers after a process exit and retries temporary connection failures. An explicit stop stays paused across restarts.
@@ -74,7 +74,7 @@ For manual setup, use `totem mcp install` with a supported client and the privat
 For a host without a browser:
 
 ```sh
-npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.63.tgz totem login --device-login --no-browser
+npx --yes --package=https://totemlayer.com/downloads/totemlayer-0.1.66.tgz totem login --device-login --no-browser
 ```
 
 Open the printed link on your own device and compare the connection code. Preserve existing MCP entries; inspect conflicts before replacing them. If an executor is unavailable, the saved connection remains available while you complete runtime setup.
@@ -146,3 +146,33 @@ An AI app such as Instinct or Codex may reject a setup, start, or listener tool
 Ask the owner to inspect the host app's approval or review controls for that operation. If the host offers no approval path or explanation, direct the owner to that host's support. Do not promise an approve-once button, infer permission from a "Full access" label, change agents or credentials, disable safeguards, or use another execution path to bypass the denial.
 
 A command denied before execution cannot write Totem status. Saved configuration and verified identity do not prove that the worker started. Keep startup and message delivery marked unverified. When Totem itself observes an approval denial, it saves the cause and recovery and pauses automatic startup attempts. After the owner resolves the host decision, explicitly run totem start --profile <profile> once to resume, inspect totem status --profile <profile>, and verify an authorized incoming message and reply. Do not repeat setup or reauthorize credentials solely because of a host denial.
+
+### Native turn cleanup
+
+On macOS 13 or later, the CLI's bundled native supervisor starts a temporary
+launchd job for each turn. Its descendants remain in one kernel resource
+coalition even if they change sessions or process groups. Completion, cancellation,
+timeouts, output limits, and loss of the calling process trigger cleanup; Totem
+waits for the kernel to reap the coalition before settling the turn. Ordinary
+subprocesses remain available within the same filesystem and network sandbox.
+No VM or permanently installed launch service is needed. macOS must permit the
+temporary job to start. A missing supervisor stops execution; a failure to confirm
+cleanup does not become a successful result. Force-killing the trusted supervisor
+itself is outside this guarantee.
+When approved code is in a macOS protected folder such as Documents, the parent
+copies only its explicit code files and approved executable package into the
+temporary turn folder. Relative code layout is preserved and command arguments
+are updated; unrelated owner files remain unavailable. Code that hardcodes its
+original protected location must use its staged path instead.
+
+Build the universal supervisor on macOS with `node packages/cli/scripts/build-native.mjs`. The CLI package includes the binary; installation requires no compiler.
+
+## Automatic MCP and receiver updates
+
+Install version 0.1.66 or newer once, or update the local plugin to that version. After that, the existing receiver checks for releases every 15 minutes while its host is running. Local MCP connections also check in the background. Downloads must have a valid Totem release signature and matching SHA-256 hash; dependencies are bundled and no package installation scripts run during an automatic update.
+
+An update changes only the managed code directory. Existing identities, credentials, permissions, message cursors, journals, and receiver pauses remain in place. Receiver workers finish active work before upgrading. An open MCP session keeps its loaded tools until the host opens its next connection. Hosted MCP tools continue to update on the server.
+
+`totem update status` shows the installed version and last check. `totem update check` checks now. `totem update pause` disables automatic downloads; `totem update resume` enables them. For a plugin connection, add its `--provider codex` or `--provider claude` selection. `TOTEM_AUTO_UPDATE=0` also disables checks. Pausing updates does not pause message receiving.
+
+Unverified downloads and failed health checks leave working code installed. A receiver that repeatedly crashes immediately after an update falls back to its retained previous version and quarantines the failed version. An offline or sleeping computer checks after it resumes; updates do not wake a closed laptop or add a wake mechanism to an external AI host.

package/bin/automatic-runtime.mjs

@@ -1,18 +1,16 @@
+import { checkRuntimeUpdate } from "./runtime-update.mjs";
+import { acquireSupervisorLock } from "./runtime-lock.mjs";
+export { acquireSupervisorLock, processIdentity, readSupervisorOwner } from "./runtime-lock.mjs";
 import { startupDiagnostic } from "./startup-diagnostics.mjs";
 import { DEFAULT_LISTENER_POLL_MS } from "./sdk/listener.js";
-import { opendir, rm, readFile, lstat, rename, readdir, unlink, rmdir } from "node:fs/promises";
+import { opendir, rm, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { randomUUID } from "node:crypto";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { powershellInvocation } from "./platform-client.mjs";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { Totem } from "./sdk/index.js";
 import { readAgentCredential, readAgentProfile } from "./agent-profile.mjs";
 import { agentStartMain, readAgentRuntimeStatus, requestStop } from "./agent-runner.mjs";
 import {
-  privateDirectory,
   privateRead,
   privateWrite,
   runtimeRoot,
@@ -194,116 +192,6 @@ export async function superviseOnce(env = process.env, options = {}) {
   }
   return results;
 }
-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 });
-  }
-}
 export async function automaticRuntimeMain(env = process.env, options = {}) {
   const directory = join(runtimeRoot(env), "runtime");
   const releaseLock = await acquireSupervisorLock(directory, options);
@@ -336,6 +224,13 @@ export async function automaticRuntimeMain(env = process.env, options = {}) {
         updatedAt: new Date().toISOString(),
       });
       await superviseOnce(environment, options);
+      await (options.checkUpdate ?? checkRuntimeUpdate)(environment).catch(() => {});
+      const installed = await privateRead(join(directory, "current.json")).catch(() => ({}));
+      if (installed.version && installed.version !== (options.packageVersion ?? PACKAGE_VERSION)) {
+        // The launcher reloads the supervisor; existing workers finish their active work first.
+        process.exitCode = 75;
+        return;
+      }
       await sleep(options.intervalMs ?? DEFAULT_LISTENER_POLL_MS, undefined, {
         signal: options.signal
           ? AbortSignal.any([controller.signal, options.signal])

package/bin/managed-mcp.mjs

@@ -0,0 +1,68 @@
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readFile } from "node:fs/promises";
+import { pluginConnectionOptions } from "./plugin-connect.mjs";
+import { ensureInstalledRuntime, privateRead, runtimeRoot } from "./runtime-installation.mjs";
+import {
+  checkRuntimeUpdate,
+  compareRuntimeVersions,
+  readRuntimeUpdateStatus,
+  setRuntimeAutoUpdates,
+} from "./runtime-update.mjs";
+
+function selectedEnvironment(args, env) {
+  if (args[0] !== "connect") return env;
+  const selection = pluginConnectionOptions(args.slice(1), env);
+  return selection.help ? env : { ...env, TOTEM_CONFIG_DIR: selection.configDirectory };
+}
+export async function managedMcpMain(args, env = process.env) {
+  const managed = selectedEnvironment(args, env);
+  // Help is independent of installation and never starts a receive process.
+  if (args.includes("--help") || args.includes("-h")) {
+    const { pluginConnectMain } = await import("./plugin-connect.mjs");
+    return pluginConnectMain(args.slice(1), { env });
+  }
+  await ensureInstalledRuntime(managed);
+  const current = await privateRead(join(runtimeRoot(managed), "runtime", "current.json"));
+  compareRuntimeVersions(current.version, current.version);
+  const packageDirectory = join(
+    runtimeRoot(managed),
+    "runtime-packages",
+    current.version,
+    "node_modules",
+    "totemlayer",
+  );
+  const metadata = JSON.parse(await readFile(join(packageDirectory, "package.json"), "utf8"));
+  if (metadata.name !== "totemlayer" || metadata.version !== current.version)
+    throw new Error("Invalid managed MCP installation.");
+  const target = args[0] === "connect" ? "plugin-connect.mjs" : "local-mcp.mjs";
+  const implementation = await import(pathToFileURL(join(packageDirectory, "bin", target)));
+  if (args[0] === "connect") await implementation.pluginConnectMain(args.slice(1), { env });
+  else await implementation.mcpMain(env);
+  // Long-lived sessions stage code without replacing handlers during an active tool call.
+  // The next MCP connection loads that code; receiver services reload themselves when idle.
+  const controller = new AbortController();
+  const check = () => checkRuntimeUpdate(managed, { signal: controller.signal }).catch(() => {});
+  void check();
+  const timer = setInterval(() => {
+    void check();
+  }, 60000);
+  timer.unref();
+  process.stdin.once("end", () => {
+    clearInterval(timer);
+    controller.abort();
+  });
+}
+export async function runtimeUpdateMain(args, env = process.env) {
+  const command = args[0] ?? "check";
+  if (!["check", "status", "pause", "resume"].includes(command))
+    throw new Error("Use totem update check, status, pause, or resume.");
+  const rest = args.slice(1).filter((arg) => arg !== "--json");
+  const managed = rest.length ? selectedEnvironment(["connect", ...rest], env) : env;
+  await ensureInstalledRuntime(managed);
+  if (command === "pause" || command === "resume")
+    await setRuntimeAutoUpdates(command === "resume", managed);
+  if (command === "check" || command === "resume")
+    await checkRuntimeUpdate(managed, { force: true });
+  process.stdout.write(JSON.stringify(await readRuntimeUpdateStatus(managed)) + "\n");
+}

package/bin/native/darwin-lifetime.json

@@ -0,0 +1 @@
+{"sourceSha256":"e15dc6cfd6f828dbcb829fc6fa3f5f6ef51062f45462ec6532b8c52f532c7951","binarySha256":"fa6dad0474b12a9e8d4ba11ec1032166939ea330817a13de6cbdece265edbadf","architectures":["arm64","x86_64"],"minimumMacOS":"13.0"}

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-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,