@robsonai/emilyremote 0.4.0 → 0.4.1

package/README.md

@@ -1,91 +1,125 @@
-# EmilyRemote 0.4.0
+# EmilyRemote 0.4.1
+
+EmilyRemote lets an authorized controller assign work to a device without
+installing a Claude or Codex agent there. This package contains the compiled
+**device runtime** for Linux x64 and Apple Silicon Macs. It requires **Node.js 22
+or newer and npm**; a separate Python interpreter is not required.
+
+## Supported systems
+
+| System | This release |
+| --- | --- |
+| Linux x64 servers, PCs and NUCs | Included; glibc 2.38 or newer required. |
+| Apple Silicon Macs, including M3 | Included; macOS 26.0 or newer required by the compiled dependencies. Tested on an M3 Max running macOS 27. |
+| Intel Macs | No qualified native build included. |
+| Raspberry Pi / Linux ARM | No native build included. |
+| Windows | No native build included. |
+| Android / iPhone | This npm package is not a mobile app. |
+| Arduino-class microcontrollers | Cannot run this host runtime; supported host-side serial/firmware workflows are a separate capability. |
+
+Use an arm64 Node.js 22+ installation on Apple Silicon. Running x64 Node under
+Rosetta selects the unbuilt Intel target. npm's OS/CPU filters cannot express
+every pair in this table; `emilyremote platforms` reports the exact runtime
+availability and setup rejects unbuilt pairs. Do not bypass those checks.
 
-EmilyRemote lets a controller assign work to an installed device runtime. This
-stable release packages the compiled **device-side** SDK for **Linux x64 with
-glibc 2.38 or newer**. Installation and launch require **Node.js 22 or newer and
-npm**. A separately installed Python interpreter is not needed.
+## Install and check
 
-The package contains a native archive and a small, intentionally readable
-JavaScript installer. The archive contains compiled SDK modules and required
-runtime libraries, including CPython. It carries no SDK Python source or wheel.
-Compiled binaries remain inspectable and can be reverse engineered.
+After installing Node.js and npm, run:
 
-## Install and check
+```sh
+npm install -g @robsonai/emilyremote@0.4.1
+emilyremote setup
+emilyremote self-check
+emilyremote status
+```
+
+Run setup as your normal user. Both `emilyremote` and `emilyremote-native` invoke
+the same launcher. Setup chooses the archive matching the host, verifies its
+pinned SHA-256 and complete inventory, and runs its native self-check before
+activation. It needs no network after npm installation. npm installation runs no
+lifecycle setup or native executable.
 
-Install into a separate local prefix so an existing deployment keeps its command
-and state. Both `emilyremote` and `emilyremote-native` invoke the same launcher.
+**Setup installs the device runtime. It does not enroll a device, start a
+service, connect to Emily, install a model or change system packages.** A
+controller URL and appropriate device credentials/configuration are still
+required. This package does not provide an end-user Emily login, terminal chat,
+or automatic binding to the user's clone.
+
+For an existing deployment, use a separate prefix to preserve its current CLI:
 
 ```sh
 umask 077
-install_root="$HOME/.local/share/robsonai/emilyremote-0.4"
-npm install --prefix "$install_root/npm" --registry=https://registry.npmjs.org \
-  --ignore-scripts --no-audit --no-fund @robsonai/emilyremote@0.4.0
+install_root="$HOME/.local/share/robsonai/emilyremote-0.4.1"
+npm install --prefix "$install_root/npm" --ignore-scripts --no-audit --no-fund \
+  @robsonai/emilyremote@0.4.1
 "$install_root/npm/node_modules/.bin/emilyremote" setup --home "$install_root/state"
-"$install_root/npm/node_modules/.bin/emilyremote" --home "$install_root/state" status
 "$install_root/npm/node_modules/.bin/emilyremote" --home "$install_root/state" self-check
 ```
 
-The stable npm channel is `@robsonai/emilyremote@latest`. The commands above pin
-this documented release. `setup` selects the packaged archive, checks its pinned
-SHA-256 and complete inventory, and runs the native self-check before activation.
-Setup needs no network after npm installation. npm installation runs no lifecycle
-setup or native executable. Setup does not enroll a device, start a service,
-connect to a controller, install a model or change system packages.
-
-## Upgrading from 0.3.0
-
-**Version 0.4.0 changes platform support and installation state.** A global npm
-upgrade replaces the existing `emilyremote` command with this native launcher.
-The separate-prefix installation above avoids replacing that command. This
-release does not migrate the Python runtime, service configuration, controller
-roles or state from 0.3.0. Setup refuses a home containing that installation;
-choose a new native home and configure it deliberately.
-
-The earlier `EMILYREMOTE_HOME` variable is not read. The native default remains
-`~/.local/share/robsonai/emilyremote-native`, or
-`$XDG_DATA_HOME/robsonai/emilyremote-native` when configured. `--home` or
-`EMILYREMOTE_NATIVE_HOME` selects another native location. Both command aliases
-use the same selected native home.
-
-npm rejects installation on macOS, Windows, Linux ARM and other unsupported
-platforms. These devices must retain their existing compatible release; no native
-build for them is included here. Do not use `--force` to bypass platform checks.
-Existing published versions, including 0.3.0, are not removed or revoked by this
-release. Arduino-class microcontrollers do not run this Linux host package.
-
-## Runtime and installation boundaries
-
-The device runtime supports shell/file tasks, PTY, tunnels, serial work and
-configured local-agent activity. It includes no hosted controller, Emily account
-credentials, model weights or optional `pymavlink` dependency. Device operation
-requires your controller configuration and authorization. The runtime uses its
-process owner's OS permissions; it is not a sandbox.
-
-Use a native home owned by your user with trustworthy, non-symlinked ancestors.
-Setup uses an exclusive lock, a private archive snapshot and isolated release
-directories. It rejects traversal, duplicate paths, links, special files, unlisted
-payloads and source-bearing extensions. Each launch verifies the active inventory.
-The active pointer changes only after native self-check succeeds. Caught
-activation failures restore the previous pointer; interrupted locks and failed
-release artifacts remain for inspection. Upgrading npm alone does not activate a
-different native runtime. There is no Python/source fallback.
-
-An explicit local archive remains supported, with a mandatory externally
-verified SHA-256:
+## Homes and upgrades
+
+The native default home is:
+
+- macOS: `~/Library/Application Support/RobsonAI/EmilyRemoteNative`
+- Linux: `~/.local/share/robsonai/emilyremote-native`, or
+  `$XDG_DATA_HOME/robsonai/emilyremote-native` when configured.
+
+`--home` or `EMILYREMOTE_NATIVE_HOME` selects another native location. Spaces in
+paths are supported. Apple's root-owned `/var`, `/tmp` and `/etc` aliases are
+recognized; arbitrary symlinks and unsafe ownership/permissions remain refused.
+
+A global npm upgrade replaces the `emilyremote` command. Updating npm alone does
+not activate a different native runtime: run setup to install the new bundled
+runtime. Native installation state is separate from the older Python-based
+0.3.0 home, and the earlier `EMILYREMOTE_HOME` variable is not read. No old
+service, controller role or enrollment configuration is migrated automatically.
+Setup refuses a home containing that older installation. Previously published
+versions are not removed or revoked by this release.
+
+## Device capabilities
+
+The runtime includes shell/file tasks, PTY, tunnels, serial and firmware helpers,
+configured local-agent activity, and signed update/supervisor machinery. Mac
+launchd integration has been exercised on the test Mac; ordinary setup does not
+start it. Operation needs your controller configuration and authorization. The
+runtime uses its process owner's OS permissions; it is not a sandbox.
+
+The package does not contain a hosted controller, Emily account credentials,
+model weights or the optional `pymavlink` dependency. Release tests use controlled
+fixtures and do not establish a live Emily-to-device task-and-recall loop or
+fleet-scale qualification.
+
+## Package and runtime integrity
+
+Each native archive contains compiled SDK modules and the needed runtime
+libraries, including CPython. It carries no SDK Python source or wheel. The
+small JavaScript installer is intentionally readable. Native binaries remain
+inspectable and can be reverse engineered.
+
+Setup uses a private archive snapshot, complete hashed inventory, exclusive
+lock and isolated release directory. It rejects unsafe paths, links, special
+files, unlisted payloads and source-bearing extensions. Every launch verifies
+the active inventory. The active pointer changes only after self-check succeeds;
+caught activation failures restore the previous pointer. Interrupted locks and
+failed artifacts remain for inspection.
+
+Mac binaries and dependencies have verified ad-hoc signatures; this is not
+Apple Developer ID signing or notarization. Mach-O architecture and deployment
+targets are checked, and the actual host macOS version must meet the manifest.
+The compiled Mac runtime includes a pinned public CA bundle for its default TLS
+context unless the operator supplies an explicit trust configuration. Explicit
+operator trust settings are preserved. Certificate and hostname verification
+remain enabled.
+
+An explicit local native archive requires a trusted external digest:
 
 ```sh
 emilyremote setup --bundle /absolute/path/to/reviewed-native.tar.gz \
   --sha256 THE_EXACT_EXTERNALLY_VERIFIED_SHA256 --home /your/private/native-home
 ```
 
-Replace the placeholder with a trusted 64-character digest. A hash verifies exact
-bytes, not the publisher. The packaged hash is pinned in this installer; explicit
-archives depend on your trusted digest source. No separate release-signature
-verification or automatic download/update endpoint is configured. Native command
-arguments are passed without a shell, and Python-path/dynamic-loader injection
-variables are removed from the child environment.
-
-The release includes the reviewed dependency inventory and upstream notices.
-Release validation covers actual bundled installation and native functional and
-security proofs. The stable channel is not a claim of qualification across
-unsupported platforms or every fleet configuration.
+A hash verifies exact bytes, not the publisher. The npm-bundled hash is pinned in
+this installer. No separate release signature or automatic download/update
+endpoint is configured by setup. Native command arguments are passed without a
+shell, and Python-path/dynamic-loader injection variables are removed from child
+environments. Dependency inventories and notices are included in each archive.

package/RUNTIME_FORMAT.md

@@ -14,12 +14,12 @@ runtime `version`. It must not require a separately installed Python interpreter
 ```json
 {
   "schema": "emilyremote.native-release/1",
-  "version": "0.4.0",
-  "platform": "linux",
-  "arch": "x64",
+  "version": "0.4.1",
+  "platform": "darwin",
+  "arch": "arm64",
   "entrypoint": "emilyremote-runtime",
   "build_manifest": "build-info.json",
-  "minimum_glibc": "2.38",
+  "minimum_macos": "26.0.0",
   "files": {
     "emilyremote-runtime": {"sha256": "ACTUAL_EXECUTABLE_SHA256", "mode": 493},
     "build-info.json": {"sha256": "ACTUAL_BUILD_MANIFEST_SHA256", "mode": 420}
@@ -28,8 +28,9 @@ runtime `version`. It must not require a separately installed Python interpreter
 ```
 
 This example is illustrative, not a valid signed or hashed release. Mode values
-are JSON integers (493 = octal 0755, 420 = octal 0644). The optional glibc value
-must come from actual build dependencies. The file inventory must contain every
+are JSON integers (493 = octal 0755, 420 = octal 0644). The example macOS minimum is illustrative, not a supported-OS promise. The
+actual minimum must come from all native build dependencies; Linux uses the
+optional `minimum_glibc` field instead. The file inventory must contain every
 regular archive file except `native-release.json` itself, including all library
 files and the build manifest. Directory entries must be parents of listed files.
 All hashes are lowercase SHA-256. ELF class, byte order and machine type must
@@ -48,3 +49,39 @@ Receipt fields retain that archive digest, release-manifest digest and
 build-manifest digest, and distinguish bundled from operator-supplied archives.
 There is no separate signed manifest or release key verification; no independent
 publisher-authentication claim is made.
+
+## macOS native extension
+
+For a Darwin bundle the manifest uses `platform: "darwin"`, `arch: "arm64"`
+and the exact release version `0.4.1`. It requires top-level
+`minimum_macos`, derived from the highest macOS deployment target across all
+native files. `minimum_glibc` is forbidden for Darwin. The build manifest records
+the same target/version, `minimum_macos`, and `signing_verified: true` only after
+actual code-signature checks pass.
+
+The entrypoint must be a thin little-endian 64-bit Mach-O executable with the
+matching generic CPU subtype. Load command bounds and macOS deployment metadata
+are validated before execution. Each Mach-O dependency must have the same CPU
+architecture and a minimum macOS version no higher than the manifest. Fat,
+32-bit, arm64e-only and non-macOS Apple binaries are not qualified by this
+release. On a real Mac the host product version is obtained using
+`/usr/bin/sw_vers -productVersion`, rather than comparing Darwin kernel versions.
+
+Native files may not use symbolic links inside the archive; packaging must
+materialize or otherwise safely arrange dependencies before the final inventory
+and signature verification. Required dependency notices remain ordinary hashed
+payload files. The npm build availability list must remain `unbuilt` until a
+real artifact has passed native execution and publication-content review.
+
+The development-only `validation/check-release.cjs` gate consumes
+`validation/native-qualification-darwin-arm64.json` with schema
+`emilyremote.native-qualification/1`, exact `version`, `target`,
+`bundle_sha256`, a detailed `evidence_path`, and checks marked `passed` for
+`compiled_self_check`, `fresh_npm_install`, `both_cli_aliases`,
+`without_host_python`, `source_and_secret_audit`, `dependency_notices`,
+`codesign_verified`, and `native_arm64_host`. Such a receipt is an evidence index,
+not a cryptographic attestation: a reviewer must examine the actual logs.
+
+Mach-O constants and layout are defined in Apple's published headers:
+- https://github.com/apple-oss-distributions/xnu/blob/main/EXTERNAL_HEADERS/mach-o/loader.h
+- https://github.com/apple-oss-distributions/xnu/blob/main/osfmk/mach/machine.h

package/lib/cli.cjs

@@ -9,16 +9,19 @@ const crypto = require('node:crypto');
 const zlib = require('node:zlib');
 const { spawn, spawnSync } = require('node:child_process');
 
-const VERSION = '0.4.0';
+const VERSION = '0.4.1';
 const MAX_BUNDLE = 256 * 1024 * 1024;
 const MAX_EXPANDED = 512 * 1024 * 1024;
 const MANIFEST = 'native-release.json';
-const BUILDS = Object.freeze({ 'linux-x64': 'available', 'linux-arm64': 'unbuilt', 'darwin-x64': 'unbuilt', 'darwin-arm64': 'unbuilt', 'win32-x64': 'unbuilt', 'win32-arm64': 'unbuilt' });
-// This digest is pinned from the separately reviewed native release artifact.
-// Publishing a new bundle requires updating this pin and qualifying the package.
+const BUILDS = Object.freeze({ 'linux-x64': 'available', 'linux-arm64': 'unbuilt', 'darwin-x64': 'unbuilt', 'darwin-arm64': 'available', 'win32-x64': 'unbuilt', 'win32-arm64': 'unbuilt' });
+// A target is enabled only after its same-version runtime is built and qualified.
+// Never fill this map from a previous-version or different-platform archive.
 const BUNDLED = Object.freeze({ 'linux-x64': Object.freeze({
-  file: 'vendor/robsonai-emilyremote-native-0.4.0-linux-x64.tar.gz',
-  sha256: 'dea2851f6a06203ca0512e0c994ac73b94c4b019fa14cf16a4bf090bc4aafffc',
+  file: 'vendor/robsonai-emilyremote-native-0.4.1-linux-x64.tar.gz',
+  sha256: '306da696df794b9a0a97a856bd3373fe9d060da6e7215d40b5b2000b4c0452f8',
+}), 'darwin-arm64': Object.freeze({
+  file: 'vendor/robsonai-emilyremote-native-0.4.1-darwin-arm64.tar.gz',
+  sha256: '827043510d73113b288861838dc914df5f4442e7a8012538b096affaf3bf5e40',
 }) });
 const HELP = `EmilyRemote native runtime installer ${VERSION}
 
@@ -30,7 +33,8 @@ const HELP = `EmilyRemote native runtime installer ${VERSION}
 
 emilyremote-native is an alias for the same command and native installation.
 
-Setup selects the packaged Linux x64 native bundle and checks its pinned SHA-256.
+Setup chooses the matching qualified native bundle and checks its pinned SHA-256.
+Only targets reported as available by 'emilyremote platforms' may be installed.
 An explicit local --bundle requires an externally supplied --sha256. No host
 Python interpreter, wheel, download host, or source fallback is used. Installing
 this npm package runs no lifecycle setup. Other platform builds are unavailable
@@ -53,7 +57,7 @@ function platformTarget(platform = process.platform, arch = process.arch) {
   return target;
 }
 function requireBuilt(target) {
-  if (BUILDS[target] !== 'available') throw new Error(`Native build ${target} is unavailable in this release. Only Linux x64 is packaged; no source fallback is available`);
+  if (BUILDS[target] !== 'available') throw new Error(`Native build ${target} is unavailable in this release. No matching qualified runtime is packaged; no source fallback is available`);
 }
 function resolveBundle(options, target = platformTarget(), packageRoot = path.resolve(__dirname, '..')) {
   if (options.bundle !== undefined || options.sha256 !== undefined) {
@@ -64,14 +68,27 @@ function resolveBundle(options, target = platformTarget(), packageRoot = path.re
   if (!bundled) throw new Error(`No bundled native runtime is available for ${target}; no source fallback is available`);
   return { bundle: path.join(packageRoot, bundled.file), sha256: bundled.sha256 };
 }
-function defaultHome(env = process.env) {
+function defaultHome(env = process.env, platform = process.platform, userHome = os.homedir()) {
   if (env.EMILYREMOTE_NATIVE_HOME) return path.resolve(env.EMILYREMOTE_NATIVE_HOME);
-  if (process.platform === 'win32') return path.join(env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'RobsonAI', 'EmilyRemoteNative');
-  if (process.platform === 'darwin') return path.join(os.homedir(), 'Library', 'Application Support', 'RobsonAI', 'EmilyRemoteNative');
-  return path.join(env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), 'robsonai', 'emilyremote-native');
+  if (platform === 'win32') return path.join(env.LOCALAPPDATA || path.join(userHome, 'AppData', 'Local'), 'RobsonAI', 'EmilyRemoteNative');
+  if (platform === 'darwin') return path.join(userHome, 'Library', 'Application Support', 'RobsonAI', 'EmilyRemoteNative');
+  return path.join(env.XDG_DATA_HOME || path.join(userHome, '.local', 'share'), 'robsonai', 'emilyremote-native');
 }
-function checkPath(target, { ownerLeaf = true, missing = true } = {}) {
+function canonicalPath(target, platform = process.platform, filesystem = fs) {
   target = path.resolve(target);
+  // macOS ships these root-owned links. Resolve only these exact aliases;
+  // calling realpath on an arbitrary user path would conceal unsafe symlinks.
+  const match = platform === 'darwin' && target.match(/^\/(var|tmp|etc)(?=\/|$)/);
+  if (!match) return target;
+  const alias = `/${match[1]}`, parent = filesystem.lstatSync('/');
+  const link = filesystem.lstatSync(alias);
+  if (!link.isSymbolicLink()) return target;
+  const resolved = path.resolve('/', filesystem.readlinkSync(alias));
+  if (!parent.isDirectory() || parent.uid !== 0 || (parent.mode & 0o022) || link.uid !== 0 || resolved !== `/private/${match[1]}`) throw new Error(`Unsafe macOS system alias: ${alias}`);
+  return resolved + target.slice(alias.length);
+}
+function checkPath(target, { ownerLeaf = true, missing = true } = {}) {
+  target = canonicalPath(target);
   const chain = [];
   for (let current = target;; current = path.dirname(current)) { chain.unshift(current); if (path.dirname(current) === current) break; }
   for (const current of chain) {
@@ -103,7 +120,7 @@ function syncDir(directory) {
   if (process.platform !== 'win32') { const fd = fs.openSync(directory, 'r'); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } }
 }
 function atomicWrite(file, bytes) {
-  checkPath(file); ensureDir(path.dirname(file));
+  file = checkPath(file); ensureDir(path.dirname(file));
   const temporary = `${file}.${crypto.randomBytes(10).toString('hex')}.tmp`;
   let fd;
   try {
@@ -186,7 +203,61 @@ function parseTar(gzip) {
   if (!ended || data.subarray(offset).some((byte) => byte !== 0)) throw new Error('Native tar archive has missing end markers or trailing content');
   return entries;
 }
-function verifyManifest(entries, target = platformTarget(), expectedVersion = VERSION) {
+function versionParts(value) {
+  if (typeof value !== 'string' || !/^\d+\.\d+(?:\.\d+)?$/.test(value)) throw new Error(`Invalid macOS version: ${JSON.stringify(value)}`);
+  const result = value.split('.').map(Number);
+  if (result.some((part) => !Number.isSafeInteger(part) || part > 65535) || result[0] < 10) throw new Error('Invalid macOS version components');
+  while (result.length < 3) result.push(0);
+  return result;
+}
+function compareVersions(left, right) {
+  const a = versionParts(left), b = versionParts(right);
+  for (let index = 0; index < 3; index++) if (a[index] !== b[index]) return Math.sign(a[index] - b[index]);
+  return 0;
+}
+function hostMacosVersion(runner = spawnSync) {
+  const result = runner('/usr/bin/sw_vers', ['-productVersion'], { shell: false, encoding: 'utf8', timeout: 5000, maxBuffer: 16384, env: { ...cleanEnv(), SYSTEM_VERSION_COMPAT: '0' } });
+  if (result.error || result.status !== 0) throw new Error('Cannot determine macOS product version; native runtime was not executed');
+  const version = String(result.stdout).trim();
+  versionParts(version);
+  return version;
+}
+function verifyMachO(data, arch, executable = true) {
+  const cpu = { arm64: 0x0100000c, x64: 0x01000007 }[arch];
+  if (!cpu || data.length < 32 || data.readUInt32LE(0) !== 0xfeedfacf || data.readUInt32LE(4) !== cpu) throw new Error('Native entrypoint is not the expected thin 64-bit Mach-O architecture');
+  const subtype = data.readUInt32LE(8) & 0x00ffffff;
+  if (subtype !== (arch === 'arm64' ? 0 : 3)) throw new Error('Specialized Mach-O CPU subtypes are not qualified');
+  const type = data.readUInt32LE(12);
+  if (executable ? type !== 2 : ![2, 6, 8].includes(type)) throw new Error('Unexpected Mach-O file type');
+  const count = data.readUInt32LE(16), size = data.readUInt32LE(20), end = 32 + size;
+  if (!count || count > 65536 || size < count * 8 || end > data.length) throw new Error('Invalid Mach-O load command table');
+  let offset = 32, minimum;
+  const unpack = (packed) => `${packed >>> 16}.${(packed >>> 8) & 0xff}.${packed & 0xff}`;
+  for (let index = 0; index < count; index++) {
+    if (offset + 8 > end) throw new Error('Truncated Mach-O load command');
+    const command = data.readUInt32LE(offset), length = data.readUInt32LE(offset + 4);
+    if (length < 8 || length % 8 || offset + length > end) throw new Error('Invalid Mach-O load command size');
+    let required;
+    if (command === 0x32) {
+      if (length < 24 || data.readUInt32LE(offset + 8) !== 1 || length !== 24 + 8 * data.readUInt32LE(offset + 20)) throw new Error('Mach-O LC_BUILD_VERSION must describe macOS');
+      required = unpack(data.readUInt32LE(offset + 12));
+    } else if (command === 0x24) {
+      if (length !== 16) throw new Error('Invalid Mach-O macOS version command');
+      required = unpack(data.readUInt32LE(offset + 8));
+    } else if ([0x25, 0x2f, 0x30].includes(command)) {
+      throw new Error('Mach-O runtime targets a non-macOS Apple platform');
+    }
+    if (required) {
+      versionParts(required);
+      if (minimum !== undefined) throw new Error('Duplicate Mach-O deployment target commands');
+      minimum = required;
+    }
+    offset += length;
+  }
+  if (offset !== end || minimum === undefined) throw new Error('Mach-O load commands do not identify a macOS deployment target');
+  return { minimum_macos: minimum };
+}
+function verifyManifest(entries, target = platformTarget(), expectedVersion = VERSION, host = {}) {
   const entry = entries.get(MANIFEST);
   if (!entry || entry.type !== '0' || entry.data.length > 2 * 1024 * 1024) throw new Error('Native release manifest is missing or too large');
   let manifest; try { manifest = JSON.parse(entry.data.toString('utf8')); } catch { throw new Error('Native release manifest is not valid JSON'); }
@@ -211,11 +282,33 @@ function verifyManifest(entries, target = platformTarget(), expectedVersion = VE
   const executable = entries.get(manifest.entrypoint);
   if (!executable || !(executable.mode & 0o100)) throw new Error('Native entrypoint is missing or not executable');
   if (manifest.platform === 'linux' && (executable.data.length < 20 || !executable.data.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])) || executable.data[4] !== 2 || executable.data[5] !== 1 || executable.data.readUInt16LE(18) !== (manifest.arch === 'x64' ? 62 : 183))) throw new Error('Native entrypoint is not the expected ELF architecture');
+  if (manifest.platform === 'darwin') {
+    const native = verifyMachO(executable.data, manifest.arch);
+    versionParts(manifest.minimum_macos);
+    if (manifest.minimum_glibc !== undefined) throw new Error('A macOS runtime cannot require glibc');
+    if (compareVersions(manifest.minimum_macos, native.minimum_macos) < 0) throw new Error('Manifest understates the Mach-O minimum macOS version');
+    // Validate every Mach-O dependency, including a higher deployment target.
+    for (const file of entries.values()) {
+      if (file.type !== '0') continue;
+      if (file.data.length < 4) {
+        if (/\.(?:dylib|so)$/.test(file.name)) throw new Error(`Unsupported Mach-O dependency format: ${file.name}`);
+        continue;
+      }
+      const magic = file.data.readUInt32LE(0);
+      if (magic === 0xfeedfacf) {
+        const dependency = verifyMachO(file.data, manifest.arch, file.name === manifest.entrypoint);
+        if (compareVersions(manifest.minimum_macos, dependency.minimum_macos) < 0) throw new Error(`Manifest understates dependency minimum macOS version: ${file.name}`);
+      } else if (/\.(?:dylib|so)$/.test(file.name) || [0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca, 0xfeedface, 0xcefaedfe, 0xcffaedfe].includes(magic)) {
+        throw new Error(`Unsupported Mach-O dependency format: ${file.name}`);
+      }
+    }
+    if (compareVersions(host.macosVersion ?? hostMacosVersion(), manifest.minimum_macos) < 0) throw new Error(`Native bundle requires macOS >=${manifest.minimum_macos}`);
+  } else if (manifest.minimum_macos !== undefined) throw new Error('Only a macOS runtime may declare minimum_macos');
   if (manifest.minimum_glibc) {
-    const host = process.report?.getReport().header.glibcVersionRuntime;
+    const glibc = host.glibcVersion ?? process.report?.getReport().header.glibcVersionRuntime;
     const parts = (text) => String(text).split('.').map(Number);
-    if (!/^\d+\.\d+$/.test(manifest.minimum_glibc) || !host) throw new Error('This native bundle requires a compatible glibc host');
-    const required = parts(manifest.minimum_glibc), actual = parts(host);
+    if (!/^\d+\.\d+$/.test(manifest.minimum_glibc) || !glibc || !/^\d+\.\d+$/.test(glibc)) throw new Error('This native bundle requires a compatible glibc host');
+    const required = parts(manifest.minimum_glibc), actual = parts(glibc);
     if (actual[0] < required[0] || (actual[0] === required[0] && actual[1] < required[1])) throw new Error(`Native bundle requires glibc >=${manifest.minimum_glibc}`);
   }
   return { manifest, manifest_sha256: hash(entry.data), build_manifest_sha256: manifest.files[manifest.build_manifest].sha256 };
@@ -245,6 +338,7 @@ function installedEntries(root) {
   visit(root); return entries;
 }
 function verifyInstalled(home) {
+  home = checkPath(home);
   const activePath = path.join(home, 'native', 'active.json'); checkPath(activePath, { missing: false });
   const active = JSON.parse(fs.readFileSync(activePath, 'utf8'));
   if (active.schema !== 'emilyremote.native-installation/1' || active.state !== 'READY' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(active.version || '')) throw new Error('Native installation is not READY with an exact version');
@@ -265,7 +359,7 @@ function selfCheck(runtime, runner) {
   return info;
 }
 async function setup(home, options, { runner = spawnSync, log = console.log } = {}) {
-  const target = platformTarget(); requireBuilt(target); home = path.resolve(home);
+  const target = platformTarget(); requireBuilt(target); home = checkPath(home);
   const selectedBundle = resolveBundle(options, target);
   checkPath(home);
   for (const legacy of ['active.json', 'receipts', 'runtimes']) {
@@ -343,4 +437,4 @@ async function main(argv = process.argv.slice(2)) {
   if (parsed.command === 'status') { console.log(JSON.stringify({ ...installed.active, installer_version: VERSION, runtime: installed.root }, null, 2)); return 0; }
   return delegate(path.join(installed.root, installed.manifest.entrypoint), [parsed.command, ...parsed.args]);
 }
-module.exports = { VERSION, BUILDS, BUNDLED, main, parseArgs, platformTarget, resolveBundle, cleanEnv, checkPath, atomicWrite, snapshotBundle, parseTar, verifyManifest, verifyInstalled, setup };
+module.exports = { VERSION, BUILDS, BUNDLED, main, parseArgs, platformTarget, requireBuilt, resolveBundle, cleanEnv, defaultHome, canonicalPath, checkPath, atomicWrite, snapshotBundle, parseTar, verifyMachO, compareVersions, hostMacosVersion, verifyManifest, verifyInstalled, setup };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@robsonai/emilyremote",
-  "version": "0.4.0",
-  "description": "RobsonAI EmilyRemote compiled device runtime for Linux x64",
+  "version": "0.4.1",
+  "description": "RobsonAI EmilyRemote compiled device runtime for Linux x64 and Apple Silicon macOS",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=22"
@@ -15,10 +15,12 @@
     "lib/cli.cjs",
     "README.md",
     "RUNTIME_FORMAT.md",
-    "vendor/robsonai-emilyremote-native-0.4.0-linux-x64.tar.gz"
+    "vendor/robsonai-emilyremote-native-0.4.1-linux-x64.tar.gz",
+    "vendor/robsonai-emilyremote-native-0.4.1-darwin-arm64.tar.gz"
   ],
   "scripts": {
-    "test": "node --test test/*.test.cjs"
+    "test": "node --test test/*.test.cjs",
+    "check-release": "node validation/check-release.cjs"
   },
   "publishConfig": {
     "access": "public",
@@ -26,9 +28,11 @@
   },
   "author": "RobsonAI",
   "os": [
-    "linux"
+    "linux",
+    "darwin"
   ],
   "cpu": [
-    "x64"
+    "x64",
+    "arm64"
   ]
 }