@north-light/cli 0.0.0-stage → 0.3.413

package/scripts/install-runtime.mjs

@@ -0,0 +1,614 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rename, rm, symlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ENTRY_NAMES, GENERATION_ID, GENERATION_PACKAGE_NAME, MANIFEST_KEYS, MANIFEST_SCHEMA, contained, isKnownPackageName, isSealed, publishedMarkerPath, runtimeHome, sortInventory, validateManifestShape } from '../bin/runtime-generation-manifest.mjs';
+import { patchPiTreeRootOrdering } from './patch-pi-tree-root-ordering.mjs';
+import { smokeValidate } from './runtime-smoke.mjs';
+import { scrubInheritedBrokerEnv, unsafeIsolationReason } from './lib/isolation-env.mjs';
+import { packArgs } from './lib/pack-args.mjs';
+import { runtimeDepsKeyFromFiles } from './lib/runtime-deps-key.mjs';
+
+scrubInheritedBrokerEnv();
+// CI has no account store to protect, and its checkout sits inside the runner's
+// home while the lanes move HOME elsewhere; test-env-scrub skips CI the same way.
+const unsafeReason = process.env.CI ? null : unsafeIsolationReason();
+if (unsafeReason) throw new Error(`Unsafe crouter runtime install: ${unsafeReason}`);
+
+const SHARED_FLAG = '--shared-node-modules=';
+const positional = process.argv.slice(2).filter((arg) => !arg.startsWith(SHARED_FLAG));
+const sharedArg = process.argv.slice(2).find((arg) => arg.startsWith(SHARED_FLAG));
+const PACKAGE_ROOT = positional[0] ? resolve(positional[0]) : resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const RUNTIME_HOME = runtimeHome();
+const GENERATIONS = join(RUNTIME_HOME, 'generations');
+const LOCK = join(RUNTIME_HOME, 'install.lock');
+// --shared-node-modules=<dir>, image builds only (docker/unit.Dockerfile): the generation installs no
+// node_modules of its own and resolves its dependencies from this directory,
+// installed once in the shared base image (docker/base.Dockerfile). Node finds
+// it by walking up from the generation, so it must sit in an ancestor of the
+// runtime home, and its stamp must name the tree this package's lockfile pins.
+const SHARED_NODE_MODULES = sharedArg ? resolve(sharedArg.slice(SHARED_FLAG.length)) : undefined;
+const SHARED_DEPS_STAMP = '.crtr-deps-key';
+const LOCK_OWNER_FILE = 'owner.json';
+const RUNTIME_LOCK = 'runtime.lock.json';
+// The selected generation plus one prior, so a bad selection can be rolled
+// back by hand. Anything older is reinstallable from npm and is not worth the
+// ~500MB/generation it costs on disk.
+const KEEP_RECENT_GENERATIONS = 2;
+const FS_CONCURRENCY = 64;
+// How long an install.lock with no readable owner record is given the
+// benefit of the doubt (the owner is mid-write, or on an ancient version of
+// this script that never wrote one) before it is treated as abandoned.
+const STALE_LOCK_RECORD_THRESHOLD_MS = 15 * 60 * 1000;
+// How long a `.staging-*`/`.archive-*` temp dir sits before the sweep in
+// step 4 treats it as wreckage from an earlier killed install rather than
+// work in progress under a lock we don't hold (impossible while we hold the
+// lock, but a conservative margin costs nothing).
+const STALE_TEMP_DIR_THRESHOLD_MS = 60 * 60 * 1000;
+const LOCK_ACQUIRE_MAX_ATTEMPTS = 50;
+
+function run(command, args, cwd, capture = false, env = process.env) {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: capture ? ['ignore', 'pipe', 'inherit'] : 'inherit' });
+    let output = '';
+    if (capture) child.stdout.on('data', (chunk) => { output += chunk; });
+    child.on('error', reject);
+    child.on('exit', (code, signal) => code === 0 ? resolveRun(output) : reject(new Error(`${command} ${args.join(' ')} failed (${code ?? signal})`)));
+  });
+}
+
+/** Capture a probe's stdout even when a candidate process exits during the probe. */
+function probe(command, args, cwd) {
+  return new Promise((resolveRun) => {
+    const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    let output = '';
+    child.stdout.on('data', (chunk) => { output += chunk; });
+    child.on('error', () => resolveRun(output));
+    child.on('exit', () => resolveRun(output));
+  });
+}
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+async function mapConcurrent(items, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(FS_CONCURRENCY, items.length) }, worker));
+  return results;
+}
+
+async function treeEntries(root) {
+  const entries = [];
+  const directories = [root];
+  while (directories.length > 0) {
+    const batch = directories.splice(0, FS_CONCURRENCY);
+    const listings = await Promise.all(batch.map(async (dir) => [dir, await readdir(dir, { withFileTypes: true })]));
+    for (const [dir, children] of listings) {
+      for (const entry of children) {
+        const absolute = join(dir, entry.name);
+        entries.push({ absolute, path: relative(root, absolute).replaceAll(sep, '/'), entry });
+        if (entry.isDirectory()) directories.push(absolute);
+      }
+    }
+  }
+  return entries;
+}
+
+async function inventory(root) {
+  const entries = (await treeEntries(root)).filter(({ path }) => path !== 'generation.json');
+  const files = await mapConcurrent(entries, async ({ absolute, path, entry }) => {
+    if (entry.isFile()) {
+      const [stat, content] = await Promise.all([lstat(absolute), readFile(absolute)]);
+      return { path, size: stat.size, sha256: digest(content) };
+    }
+    if (entry.isSymbolicLink()) {
+      const target = await readlink(absolute);
+      if (isAbsolute(target) || !contained(root, resolve(dirname(absolute), target))) throw new Error(`generation symlink escapes root: ${path}`);
+      return { path, size: Buffer.byteLength(target), sha256: digest(target), symlink: true };
+    }
+    if (entry.isDirectory()) return undefined;
+    throw new Error(`unsupported generation file: ${path}`);
+  });
+  return sortInventory(files.filter(Boolean));
+}
+
+async function seal(root) {
+  const entries = await treeEntries(root);
+  const files = entries.filter(({ entry }) => entry.isFile());
+  const directories = entries.filter(({ entry }) => entry.isDirectory());
+  await mapConcurrent(files, async ({ absolute }) => {
+    const stat = await lstat(absolute);
+    await chmod(absolute, (stat.mode & 0o111) === 0 ? 0o444 : 0o555);
+  });
+  await mapConcurrent(directories, ({ absolute }) => chmod(absolute, 0o555));
+  await chmod(root, 0o555);
+}
+
+async function removeStage(root) {
+  try {
+    const entries = await treeEntries(root);
+    await mapConcurrent(entries, ({ absolute, entry }) => {
+      if (entry.isDirectory()) return chmod(absolute, 0o755);
+      if (entry.isFile()) return chmod(absolute, 0o644);
+    });
+    await chmod(root, 0o755);
+  } catch {
+    // Cleanup cannot obscure the operation that caused it.
+  }
+  await rm(root, { recursive: true, force: true });
+}
+
+
+/** Refuse to select a generation whose migration chain ends before the live
+ * canvas database. A higher package version is not proof of schema ancestry:
+ * builds from divergent branches can otherwise make `daemon restart` replace a
+ * healthy daemon with code that silently treats an unknown `user_version` as
+ * current, then crash-loops on columns/tables its older schema still expects.
+ *
+ * This runs before the atomic `selected` swap, so a rejected install leaves the
+ * currently serving generation selected. The daemon-side migration guard is a
+ * second line of defense for generations installed by older installers. */
+async function assertCanvasSchemaCompatible(stage) {
+  const migrationsUrl = pathToFileURL(join(stage, 'dist', 'core', 'canvas', 'migrations.js')).href;
+  const candidate = await import(migrationsUrl);
+  const supported = candidate.MIGRATIONS?.length;
+  if (!Number.isSafeInteger(supported) || supported < 0) {
+    throw new Error('candidate runtime does not expose a valid canvas migration version');
+  }
+
+  const canvasHome = process.env.CRTR_HOME || join(homedir(), '.crouter', 'canvas');
+  const dbPath = join(canvasHome, 'canvas.db');
+  try {
+    await lstat(dbPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return; // no live database yet
+    throw error;
+  }
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    const { user_version: current } = db.prepare('PRAGMA user_version').get();
+    if (current > supported) {
+      throw new Error(
+        `refusing to select runtime with canvas schema ${supported}: ` +
+        `the live database is already at version ${current}; install a descendant build instead`,
+      );
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/** Atomically mark generation `id` eligible as a sibling-fallback candidate
+ *  (see `runtime-generation-manifest.mjs`'s `publishedMarkerPath` for the
+ *  invariant this establishes) — write via temp file + rename IN
+ *  `generationsRoot` (never inside the sealed generation root, so no
+ *  unsealing is needed), and ONLY call this after `validatePublished()` has
+ *  already succeeded for this exact id. */
+async function markPublished(generationsRoot, id) {
+  const marker = publishedMarkerPath(generationsRoot, id);
+  const temporary = `${marker}.${process.pid}-${Date.now()}.tmp`;
+  await writeFile(temporary, `${id}\n`);
+  await rename(temporary, marker);
+}
+
+async function validatePublished(root, id) {
+  // Sealed check is shared with the bootstrap selector's fallback scan
+  // (`bin/runtime-generation-manifest.mjs`'s `isSealed`) so both apply the
+  // exact same rule for what counts as a genuinely published generation.
+  if (!isSealed(root)) throw new Error(`published generation is not sealed: ${root}`);
+  const manifestPath = join(root, 'generation.json');
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  for (const entryName of ENTRY_NAMES) {
+    const shape = validateManifestShape(manifest, { id, entryName });
+    if (!shape.ok) throw new Error(`published generation integrity mismatch: ${shape.error}`);
+  }
+  if (JSON.stringify(sortInventory(await inventory(root))) !== JSON.stringify(sortInventory(manifest.files))) {
+    throw new Error(`published generation integrity mismatch: ${root}`);
+  }
+}
+
+async function pack(archiveDir) {
+  // Errors still print; the prepack/postpack banners and notices do not, because
+  // on a fresh install this runs inside the user's first `crtr` command.
+  const output = await run('npm', packArgs(archiveDir, PACKAGE_ROOT), PACKAGE_ROOT, true);
+  const packed = JSON.parse(output);
+  if (!Array.isArray(packed) || typeof packed[0]?.filename !== 'string') throw new Error('npm pack did not report an archive');
+  return join(archiveDir, packed[0].filename);
+}
+
+/** Generation ids named anywhere in a `ps` or `lsof` dump. */
+function generationIdsIn(text) {
+  return [...text.matchAll(/generations\/([a-f0-9]{64})(?:[/\s]|$)/g)].map((match) => match[1]);
+}
+
+/** Every generation a running process is using — named in its argv, or held as
+ *  an open entry-file lease (how a stable `crtr`/`crtrd` shim, whose argv names
+ *  no generation, keeps the one it resolved; see `holdGenerationEntryFd` in
+ *  bin/runtime-selector.mjs and the matching open in src/cli.ts).
+ *
+ *  Detection is positive-only and that is deliberate: a generation nothing here
+ *  names is prunable. An earlier revision also tracked whether every stable shim
+ *  had exposed a lease and skipped the whole GC when one had not. That made one
+ *  unidentifiable process veto all pruning permanently — a single pre-upgrade
+ *  viewer, which could never hold a lease the mechanism predated, silently
+ *  stopped GC forever and grew this directory by ~500MB per install. */
+async function liveGenerationIds() {
+  const output = await run('ps', ['-axww', '-o', 'pid=,command='], RUNTIME_HOME, true);
+  const live = new Set(generationIdsIn(output));
+  const nodePids = [];
+  for (const line of output.split('\n')) {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (!match) continue;
+    const [, pid, command] = match;
+    if (/(?:^|[\s/])(?:node|crtrd?|crouter)(?:[\s]|$)/.test(command)) nodePids.push(pid);
+  }
+  if (nodePids.length === 0) return live;
+
+  // One lsof invocation resolves cwd references and the runtime entry-file
+  // lease held by each stable CLI process without a per-process startup penalty.
+  const open = await probe('lsof', ['-n', '-P', '-a', '-p', nodePids.join(','), '-Fn'], RUNTIME_HOME);
+  for (const line of open.split('\n')) {
+    for (const id of generationIdsIn(line)) live.add(id);
+  }
+  return live;
+}
+
+async function selectedGenerationId() {
+  const target = await readlink(join(RUNTIME_HOME, 'selected'));
+  const match = /^generations\/([a-f0-9]{64})$/.exec(target);
+  if (!match) throw new Error(`selected runtime target is invalid: ${JSON.stringify(target)}`);
+  return match[1];
+}
+
+async function pruneGenerations() {
+  const selected = await selectedGenerationId();
+  const live = await liveGenerationIds();
+  const entries = await readdir(GENERATIONS, { withFileTypes: true });
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !GENERATION_ID.test(entry.name)) continue;
+    try {
+      const manifest = JSON.parse(await readFile(join(GENERATIONS, entry.name, 'generation.json'), 'utf8'));
+      const createdAt = Date.parse(manifest.createdAt);
+      if (Number.isNaN(createdAt)) continue;
+      candidates.push({ id: entry.name, createdAt });
+    } catch {
+      // A generation whose age cannot be established remains protected.
+    }
+  }
+  candidates.sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const retained = new Set([selected, ...candidates.slice(0, KEEP_RECENT_GENERATIONS).map(({ id }) => id), ...live]);
+  for (const { id } of candidates) {
+    if (!retained.has(id)) {
+      await removeStage(join(GENERATIONS, id));
+      await rm(publishedMarkerPath(GENERATIONS, id), { force: true });
+    }
+  }
+}
+
+/** A process's start time as `ps` reports it — the cheap, boot-unique-enough
+ *  fellow-traveler of a pid that lets a reused pid be told apart from the
+ *  process that actually wrote a lock owner record. Empty string when the
+ *  pid does not exist (or `ps` cannot be run), never rejects. */
+async function pidStartTime(pid) {
+  const output = await probe('ps', ['-o', 'lstart=', '-p', String(pid)], RUNTIME_HOME);
+  return output.trim();
+}
+
+/** Whether `pid` currently identifies a live process, from this user's
+ *  vantage point. `EPERM` means the pid exists but is owned by someone
+ *  else — still alive, just not ours to signal. */
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+/** Write the lock owner record via temp-file + rename so a concurrent reader
+ *  never observes a half-written file. Must be called only once `LOCK` is
+ *  known to be ours (immediately after `mkdir(LOCK)` succeeds). */
+async function writeLockOwner(lockDir) {
+  const owner = { pid: process.pid, startTime: await pidStartTime(process.pid), hostname: hostname(), startedAt: new Date().toISOString() };
+  const temporary = join(lockDir, `.${LOCK_OWNER_FILE}.${process.pid}-${Date.now()}.tmp`);
+  await writeFile(temporary, JSON.stringify(owner));
+  await rename(temporary, join(lockDir, LOCK_OWNER_FILE));
+}
+
+async function readLockOwner(lockDir) {
+  try {
+    const owner = JSON.parse(await readFile(join(lockDir, LOCK_OWNER_FILE), 'utf8'));
+    return Number.isInteger(owner?.pid) ? owner : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True only when `owner`'s pid is both alive AND (when a start time was
+ *  recorded) still the same process that wrote the record — a recycled pid
+ *  must not masquerade as a live owner. */
+async function ownerIsAlive(owner) {
+  if (!owner || !pidAlive(owner.pid)) return false;
+  if (!owner.startTime) return true;
+  const currentStartTime = await pidStartTime(owner.pid);
+  return currentStartTime === '' || currentStartTime === owner.startTime;
+}
+
+/** Take `LOCK`, reclaiming it first if its owner is provably dead. A dead
+ *  owner is reclaimed unconditionally; a missing/corrupt owner record is
+ *  reclaimed only once the lock dir is older than a conservative threshold
+ *  (it may belong to a process that has not written its record yet). The
+ *  reclaim itself is race-safe: the stale dir is renamed to a private,
+ *  unique path first, and only the process whose rename wins takes the
+ *  fresh lock — a loser simply retries the ordinary contended path rather
+ *  than deleting a dir a concurrent winner might still be reading. */
+async function acquireLock() {
+  for (let attempt = 0; attempt < LOCK_ACQUIRE_MAX_ATTEMPTS; attempt++) {
+    try {
+      await mkdir(LOCK);
+      await writeLockOwner(LOCK);
+      return;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const owner = await readLockOwner(LOCK);
+      if (owner && (await ownerIsAlive(owner))) {
+        throw new Error(`runtime installer lock is held by a live process: pid=${owner.pid} started=${owner.startTime || 'unknown'} host=${owner.hostname || 'unknown'}; refusing to install concurrently`);
+      }
+      if (!owner) {
+        let stat;
+        try {
+          stat = await lstat(LOCK);
+        } catch (statError) {
+          if (statError?.code === 'ENOENT') continue; // lock vanished between mkdir and lstat; retry
+          throw statError;
+        }
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs < STALE_LOCK_RECORD_THRESHOLD_MS) {
+          throw new Error(`runtime installer lock exists without a readable owner record and is only ${Math.round(ageMs / 1000)}s old: ${LOCK}; inspect and remove only after confirming no installation is running`);
+        }
+      }
+      const graveyard = join(RUNTIME_HOME, `.lock-stale-${process.pid}-${Date.now()}`);
+      try {
+        await rename(LOCK, graveyard);
+      } catch (renameError) {
+        if (renameError?.code === 'ENOENT') continue; // another process already reclaimed it; fall back to the contended path
+        throw renameError;
+      }
+      process.stderr.write(`runtime installer: reclaimed a stale lock (dead owner pid=${owner?.pid ?? 'unknown'})\n`);
+      await removeStage(graveyard);
+      // Loop back and take the now-vacant lock.
+    }
+  }
+  throw new Error(`runtime installer lock: gave up after ${LOCK_ACQUIRE_MAX_ATTEMPTS} contended attempts: ${LOCK}`);
+}
+
+/** Sweep `.staging-*`/`.archive-*` temp dirs left behind by an install that
+ *  was killed before its own `finally` (or signal handler) could run. Only
+ *  called once this process holds `LOCK`, so any dir old enough to clear
+ *  the threshold cannot belong to a still-running install. */
+async function sweepOrphanTempDirs() {
+  let entries;
+  try {
+    entries = await readdir(RUNTIME_HOME, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^\.(?:staging|archive)-/.test(entry.name)) continue;
+    const absolute = join(RUNTIME_HOME, entry.name);
+    let stat;
+    try {
+      stat = await lstat(absolute);
+    } catch {
+      continue;
+    }
+    if (Date.now() - stat.mtimeMs < STALE_TEMP_DIR_THRESHOLD_MS) continue;
+    process.stderr.write(`runtime installer: sweeping orphan temp dir from an earlier aborted install: ${absolute}\n`);
+    await removeStage(absolute);
+  }
+}
+
+// Populated as install() proceeds so a SIGINT/SIGTERM handler can undo
+// exactly what the normal `finally` below would have undone. SIGKILL
+// remains uncatchable, which is exactly why acquireLock() can reclaim.
+const cleanupState = { lockTaken: false, stage: undefined, archiveDir: undefined, publishedRoot: undefined, committed: false, temporary: undefined, id: undefined, exiting: false };
+
+async function cleanupOnSignal(signal) {
+  if (cleanupState.exiting) return;
+  cleanupState.exiting = true;
+  process.stderr.write(`runtime installer: received ${signal}, cleaning up before exit\n`);
+  try {
+    if (cleanupState.temporary) await rm(cleanupState.temporary, { force: true });
+    if (cleanupState.stage) await removeStage(cleanupState.stage);
+    if (cleanupState.publishedRoot && !cleanupState.committed) {
+      await removeStage(cleanupState.publishedRoot);
+      if (cleanupState.id) await rm(publishedMarkerPath(GENERATIONS, cleanupState.id), { force: true });
+    }
+    if (cleanupState.archiveDir) await rm(cleanupState.archiveDir, { recursive: true, force: true });
+    if (cleanupState.lockTaken) await rm(LOCK, { recursive: true, force: true });
+  } catch (error) {
+    process.stderr.write(`runtime installer: cleanup on ${signal} failed: ${error?.message ?? error}\n`);
+  }
+  process.exit(1);
+}
+
+process.on('SIGINT', () => { cleanupOnSignal('SIGINT'); });
+process.on('SIGTERM', () => { cleanupOnSignal('SIGTERM'); });
+
+/** Shared-dependency mode: refuse a shared tree that Node would not find from
+ *  the generation or that was installed from a different lockfile, then link
+ *  the packed workspace packages inside the generation the way `npm ci` does. */
+async function linkSharedNodeModules(stage) {
+  if (basename(SHARED_NODE_MODULES) !== 'node_modules' || !contained(dirname(SHARED_NODE_MODULES), RUNTIME_HOME)) {
+    throw new Error(`--shared-node-modules must name a node_modules directory in an ancestor of ${RUNTIME_HOME}: ${SHARED_NODE_MODULES}`);
+  }
+  const expected = runtimeDepsKeyFromFiles(join(stage, 'package.json'), join(stage, 'package-lock.json'));
+  let stamped;
+  try {
+    stamped = (await readFile(join(SHARED_NODE_MODULES, SHARED_DEPS_STAMP), 'utf8')).trim();
+  } catch (error) {
+    throw new Error(`shared node_modules has no ${SHARED_DEPS_STAMP} stamp: ${SHARED_NODE_MODULES}`, { cause: error });
+  }
+  if (stamped !== expected) {
+    throw new Error(`shared node_modules was installed for dependency key ${stamped}, but this package needs ${expected}; rebuild the base image`);
+  }
+  const lock = JSON.parse(await readFile(join(stage, 'package-lock.json'), 'utf8'));
+  for (const [path, entry] of Object.entries(lock.packages ?? {})) {
+    if (!entry?.link || typeof entry.resolved !== 'string' || !path.startsWith('node_modules/')) continue;
+    const target = join(stage, entry.resolved);
+    try {
+      await lstat(join(target, 'package.json'));
+    } catch {
+      continue; // a workspace npm pack omitted; `npm ci` skips it the same way
+    }
+    const link = join(stage, path);
+    await mkdir(dirname(link), { recursive: true });
+    await symlink(relative(dirname(link), target), link);
+  }
+}
+
+/** On Linux the runtime loads a native addon (openat2, peer credentials) from
+ *  dist/native/linux/<process.arch>/addon.node. A release ships a prebuilt one
+ *  for x64 and arm64 (scripts/ensure-native-linux.mjs, glibc-linked). A package
+ *  packed locally, built on a non-Linux host without Docker, or run on an
+ *  architecture or libc (musl) the prebuilt does not fit has no loadable addon,
+ *  so compile it into the staged tree rather than stage a generation that cannot
+ *  start. */
+async function ensureLinuxNativeAddon(stage) {
+  if (process.platform !== 'linux') return;
+  const target = join(stage, 'dist', 'native', 'linux', process.arch, 'addon.node');
+  if (existsSync(target) && await loads(target)) return;
+  try {
+    await run(process.execPath, [join(stage, 'scripts', 'build-native-linux.mjs'), target], stage);
+  } catch (error) {
+    throw new Error(`this package ships no Linux native addon that loads on ${process.arch} here, and compiling src/native/linux/addon.c failed (reason above). Install a C compiler and the Node development headers (Debian/Ubuntu: \`sudo apt-get install build-essential\`), then run \`crtr\` again.`, { cause: error });
+  }
+}
+
+/** Whether this process's libc and Node accept the addon at `path`. */
+function loads(path) {
+  return new Promise((resolveLoads) => {
+    const child = spawn(process.execPath, ['-e', 'process.dlopen({ exports: {} }, process.argv[1])', path], { stdio: 'ignore' });
+    child.on('error', () => resolveLoads(false));
+    child.on('exit', (code) => resolveLoads(code === 0));
+  });
+}
+
+async function install() {
+  await mkdir(GENERATIONS, { recursive: true });
+  await acquireLock();
+  cleanupState.lockTaken = true;
+  await sweepOrphanTempDirs();
+  let stage;
+  let archiveDir;
+  let publishedRoot;
+  let committed = false;
+  let temporary;
+  let id;
+  try {
+    archiveDir = await mkdtemp(join(RUNTIME_HOME, '.archive-'));
+    cleanupState.archiveDir = archiveDir;
+    const archive = await pack(archiveDir);
+    const archiveHash = digest(await readFile(archive));
+    stage = await mkdtemp(join(RUNTIME_HOME, '.staging-'));
+    cleanupState.stage = stage;
+    await run('tar', ['-xzf', archive, '--strip-components=1', '-C', stage], PACKAGE_ROOT);
+    await copyFile(join(stage, RUNTIME_LOCK), join(stage, 'package-lock.json'));
+    // Humanloop's postinstall only prewarms its external termrender cache; runtime rendering retries lazily with a plaintext fallback.
+    const installEnv = { ...process.env };
+    delete installEnv.npm_config_allow_scripts;
+    // stdout is captured and dropped (npm's "added N packages" summary); errors keep stderr.
+    if (SHARED_NODE_MODULES) await linkSharedNodeModules(stage);
+    else await run('npm', ['ci', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'], stage, true, installEnv);
+    await patchPiTreeRootOrdering(stage);
+    await ensureLinuxNativeAddon(stage);
+    await smokeValidate(stage, { sharedNodeModules: SHARED_NODE_MODULES });
+    await assertCanvasSchemaCompatible(stage);
+    const pkg = JSON.parse(await readFile(join(stage, 'package.json'), 'utf8'));
+    const files = sortInventory(await inventory(stage));
+    id = digest(`${archiveHash}\n${digest(await readFile(join(stage, 'package-lock.json')))}\n${digest(JSON.stringify(files))}\n${process.version}\n${process.platform}\n${process.arch}\ninstaller-schema-1`);
+    cleanupState.id = id;
+    const finalRoot = join(GENERATIONS, id);
+    const manifest = {
+      schema: MANIFEST_SCHEMA,
+      id,
+      packageName: GENERATION_PACKAGE_NAME,
+      packageVersion: pkg.version,
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      createdAt: new Date().toISOString(),
+      entries: { cli: 'dist/cli.js', daemon: 'dist/daemon/crtrd-cli.js', broker: 'dist/core/runtime/broker-cli.js', launcher: 'dist/launcher/main.js' },
+      files,
+    };
+    if (JSON.stringify(Object.keys(manifest).sort()) !== JSON.stringify(MANIFEST_KEYS) || !isKnownPackageName(manifest.packageName)) throw new Error('generated runtime manifest has an invalid schema or package identity');
+    for (const entry of Object.values(manifest.entries)) {
+      const stat = await lstat(join(stage, entry));
+      if (!stat.isFile()) throw new Error(`runtime entry is missing: ${entry}`);
+    }
+    await writeFile(join(stage, 'generation.json'), `${JSON.stringify(manifest)}\n`);
+    await seal(stage);
+    try {
+      await lstat(finalRoot);
+      await validatePublished(finalRoot, id);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      // macOS requires write permission on a directory being renamed. It is resealed before selection can observe it.
+      await chmod(stage, 0o755);
+      await rename(stage, finalRoot);
+      publishedRoot = finalRoot;
+      cleanupState.publishedRoot = publishedRoot;
+      await chmod(finalRoot, 0o555);
+      stage = undefined;
+      cleanupState.stage = undefined;
+      await validatePublished(finalRoot, id);
+    }
+    // Only after the full-hash check above has succeeded for this exact id —
+    // see `publishedMarkerPath`'s doc comment for the ordering invariant.
+    await markPublished(GENERATIONS, id);
+    const selected = join(RUNTIME_HOME, 'selected');
+    temporary = join(RUNTIME_HOME, `.selected-${process.pid}-${Date.now()}`);
+    cleanupState.temporary = temporary;
+    await symlink(`generations/${id}`, temporary);
+    await rename(temporary, selected);
+    committed = true;
+    cleanupState.committed = true;
+    try {
+      await pruneGenerations();
+    } catch (error) {
+      process.stderr.write(`runtime generation GC skipped: ${error.message}\n`);
+    }
+    // stderr, not stdout: on a fresh install this runs inside the user's first `crtr` command, which may be `--json`.
+    process.stderr.write(`Installed immutable crouter runtime generation ${id}\n`);
+    return { generation: id, version: pkg.version, selected };
+  } finally {
+    if (temporary) await rm(temporary, { force: true });
+    if (stage) await removeStage(stage);
+    if (publishedRoot && !committed) {
+      await removeStage(publishedRoot);
+      await rm(publishedMarkerPath(GENERATIONS, id), { force: true });
+    }
+    if (archiveDir) await rm(archiveDir, { recursive: true, force: true });
+    await rm(LOCK, { recursive: true, force: true });
+  }
+}
+
+install().catch((error) => {
+  process.stderr.write(`runtime installation failed: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/scripts/lib/isolation-env.mjs

@@ -0,0 +1,48 @@
+import { realpathSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+
+// A node's shell inherits broker identity and pi paths. Neither an installer
+// nor a test lane is that broker; nested processes must resolve their own roots.
+export function scrubInheritedBrokerEnv(env = process.env) {
+  for (const key of Object.keys(env)) {
+    if (key.startsWith('PI_') || (key.startsWith('CRTR_') &&
+      key !== 'CRTR_HOME' && key !== 'CRTR_RUNTIME_HOME' && key !== 'CRTR_NO_DAEMON_AUTOSTART' && key !== 'CRTR_BROKER_SIGNAL_LONG_PROOF')) {
+      delete env[key];
+    }
+  }
+}
+
+// A normal host install uses the account HOME. When HOME is overridden, no
+// working directory or configured write root may still point into that account.
+// A node's shell runs with HOME at its app-space home (`~/.crouter/apps/<app>/home`);
+// that is the account acting through a node, not an isolated home.
+function isAccountAppSpaceHome(home, accountHome) {
+  return basename(home) === 'home' && dirname(dirname(home)) === join(accountHome, '.crouter', 'apps');
+}
+
+export function unsafeIsolationReason({ requireTemporaryHome = false, requireCrtrHome = false } = {}) {
+  const inside = (home, target) => {
+    const rel = relative(home, target);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+  };
+  try {
+    const home = realpathSync(process.env.HOME);
+    const accountHome = realpathSync(userInfo().homedir);
+    if (home === accountHome || isAccountAppSpaceHome(home, accountHome)) return requireTemporaryHome ? 'HOME is the account home' : null;
+    if (requireCrtrHome && !process.env.CRTR_HOME) return 'CRTR_HOME is missing';
+    for (const [name, path] of [
+      ['cwd', process.cwd()], ['TMPDIR', tmpdir()],
+      ...(process.env.CRTR_HOME ? [['CRTR_HOME', process.env.CRTR_HOME]] : []),
+      ...(process.env.CRTR_RUNTIME_HOME ? [['CRTR_RUNTIME_HOME', process.env.CRTR_RUNTIME_HOME]] : []),
+    ]) {
+      const target = realpathSync(path);
+      if (inside(accountHome, target) && !inside(home, target)) {
+        return `${name} is inside the account home but outside HOME`;
+      }
+    }
+    return null;
+  } catch {
+    return 'HOME, account home, cwd, TMPDIR, CRTR_HOME, or CRTR_RUNTIME_HOME cannot be resolved';
+  }
+}

package/scripts/lib/pack-args.mjs

@@ -0,0 +1,19 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** A published tarball is already built: it ships dist (minified when released),
+ *  runtime.lock.json, and no devDependencies, so `prepack` has nothing left to do
+ *  and cannot run — it imports esbuild, which an unpacked tarball (the
+ *  `crtr sys update --target self` temp dir) does not have. Only a git checkout
+ *  needs `prepack`, to copy package-lock.json to runtime.lock.json. */
+export function isPublishedTarball(root) {
+  return !existsSync(join(root, '.git')) && existsSync(join(root, 'runtime.lock.json'));
+}
+
+/** `npm pack` arguments install-runtime uses to turn a package root into the
+ *  archive a generation is staged from. */
+export function packArgs(archiveDir, root) {
+  const args = ['pack', '--json', '--loglevel=error', '--foreground-scripts=false'];
+  if (isPublishedTarball(root)) args.push('--ignore-scripts');
+  return [...args, '--pack-destination', archiveDir];
+}