feat: support macOS arm64 remote Agent hosts

Extend GoodBuddy Agent packaging, installation, SSH attachment, Runtime lifecycle, and Desktop package management to macOS arm64. Linux x64, Linux arm64, and Darwin arm64 share the existing signed catalog. Preserve Ask read-only behavior and Execute account permissions, and stop detached tool descendants during Mac cancellation.

Upgrade Desktop before publishing the first mixed-platform catalog because older Linux-only readers reject Darwin entries. Intel Macs are not supported; no launchd service or administrator access is required. This commit does not publish a release.

Validation: 3520 tests passed, 57 skipped; typecheck, lint, and development build passed. Real Mac installation, Ask/Execute, cancellation and reconnect passed; final Linux installation, Ask and reconnect passed. Nine real model requests were recorded.

Release note: 支持将 Apple Silicon Mac 用作远程项目 Host，可安装 macOS arm64 Agent 并使用 Ask、Execute 和断线重连；与 Linux 共用一个包目录，发布混合目录前需升级 Desktop。

src/agent-daemon/bundle-file-verification.ts

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto'
 import { createReadStream } from 'node:fs'
 import { open } from 'node:fs/promises'
+import { binaryTargetArchitecture } from '../shared/node/binary-target'
+import type { AgentPlatform } from '../shared/agent-target'
 import type {
   AgentArchitecture
 } from '../shared/agent-installation-contracts'
@@ -16,7 +18,8 @@ export async function sha256File(filePath: string): Promise<string> {
 export async function assertElfArchitecture(
   filePath: string,
   expected: AgentArchitecture,
-  label: string
+  label: string,
+  platform: AgentPlatform = 'linux'
 ): Promise<void> {
   const handle = await open(filePath, 'r')
   try {
@@ -27,8 +30,8 @@ export async function assertElfArchitecture(
       header.length,
       0
     )
-    const actual = detectElfArchitecture(
-      header.subarray(0, bytesRead)
+    const actual = binaryTargetArchitecture(
+      header.subarray(0, bytesRead), platform
     )
     if (actual !== expected) {
       throw new Error(
@@ -39,25 +42,3 @@ export async function assertElfArchitecture(
     await handle.close()
   }
 }
-
-function detectElfArchitecture(
-  header: Buffer
-): AgentArchitecture | undefined {
-  if (
-    header.length < 20 ||
-    header[0] !== 0x7f ||
-    header.toString('ascii', 1, 4) !== 'ELF' ||
-    (header[5] !== 1 && header[5] !== 2)
-  ) {
-    return undefined
-  }
-  const machine =
-    header[5] === 2
-      ? header.readUInt16BE(18)
-      : header.readUInt16LE(18)
-  return machine === 62
-    ? 'x64'
-    : machine === 183
-      ? 'arm64'
-      : undefined
-}

src/agent-daemon/cli.test.ts

@@ -449,7 +449,7 @@ describe('Agent CLI fixed command contract', () => {
         homeDirectory: 'C:\\Users\\tester',
         uid: 1234
       })
-    ).toThrow('current Linux UID')
+    ).toThrow('current Unix UID')
   })
 
   it('rejects injected installation IDs before lifecycle dispatch', async () => {

src/agent-daemon/cli.ts

@@ -842,13 +842,13 @@ export function deriveManagedInstallationPaths(
   const platform = options.platform ?? process.platform
   const uid = options.uid ?? process.getuid?.()
   if (
-    platform !== 'linux' ||
+    !['linux', 'darwin'].includes(platform) ||
     uid === undefined ||
     !Number.isSafeInteger(uid) ||
     uid < 0
   ) {
     throw new AgentUnsupportedError(
-      'Managed Agent paths require a current Linux UID',
+      'Managed Agent paths require a current Unix UID',
       'platform-incompatible'
     )
   }
@@ -860,7 +860,7 @@ export function deriveManagedInstallationPaths(
     .digest('hex')
     .slice(0, 20)
   const socketRoot = posix.join(
-    '/tmp',
+    platform === 'darwin' ? '/private/tmp' : '/tmp',
     `goodbuddy-${uid}-${homeHash}`
   )
   const socketName = createHash('sha256')

src/agent-daemon/daemon.ts

@@ -100,6 +100,7 @@ export class AgentDaemon {
   readonly #agentVersion: string
   readonly #protocol: AttachPreface['protocol']
   readonly #architecture: 'x64' | 'arm64'
+  readonly #platform = process.platform
   readonly #remoteUserIdentity: string
   readonly #stateDirectory: string
   readonly #socketPath: string
@@ -171,7 +172,7 @@ export class AgentDaemon {
       daemonBootId: this.#bootId,
       agentVersion: this.#agentVersion,
       protocol: this.#protocol,
-      platform: 'linux',
+      platform: this.#platform,
       architecture: this.#architecture,
       supervisor: 'detached-on-demand',
       remoteUserIdentity: this.#remoteUserIdentity,
@@ -180,9 +181,12 @@ export class AgentDaemon {
   }
 
   async start(): Promise<void> {
-    if (process.platform !== 'linux') {
+    if (
+      this.#platform !== 'linux' &&
+      !(this.#platform === 'darwin' && process.arch === 'arm64')
+    ) {
       throw new AgentUnsupportedError(
-        'GoodBuddy Agent daemon is certified only on Linux',
+        'GoodBuddy Agent daemon requires Linux or macOS arm64',
         'platform-incompatible'
       )
     }

src/agent-daemon/darwin-process-identity.test.ts

@@ -0,0 +1,57 @@
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+import { realpathSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import {
+  darwinBootId,
+  inspectDarwinProcess,
+  listDarwinProcessGroup,
+  stopDarwinDescendants
+} from './darwin-process-identity'
+
+describe('Darwin process identity', () => {
+  const native = process.platform === 'darwin' && process.arch === 'arm64' ? it : it.skip
+  native('reads actual process identity and enumerates a dedicated child group', async () => {
+    const current = inspectDarwinProcess(process.pid)
+    expect(current?.pid).toBe(process.pid)
+    expect(current?.executablePath).toBe(realpathSync(process.execPath))
+    expect(BigInt(current!.starttime)).toBeGreaterThan(0n)
+    expect(darwinBootId()).toMatch(/^[a-f0-9-]{36}$/u)
+    const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
+      detached: true, stdio: 'ignore'
+    })
+    await once(child, 'spawn')
+    try {
+      const identity = inspectDarwinProcess(child.pid!)
+      expect(identity?.processGroupId).toBe(child.pid)
+      expect(listDarwinProcessGroup(child.pid!)).toContain(child.pid)
+      expect(listDarwinProcessGroup(child.pid!)).not.toContain(process.pid)
+    } finally {
+      const exited = once(child, 'exit')
+      child.kill()
+      await exited
+    }
+    expect(inspectDarwinProcess(child.pid!)).toBeUndefined()
+  })
+  native('stops a tool child that starts its own process group', async () => {
+    const parent = spawn(process.execPath, ['-e', `
+      const {spawn}=require('node:child_process');
+      const child=spawn(process.execPath,['-e','setInterval(()=>{},1000)'],{detached:true,stdio:'ignore'});
+      child.on('spawn',()=>console.log(child.pid));
+      setInterval(()=>{},1000);
+    `], { detached: true, stdio: ['ignore', 'pipe', 'ignore'] })
+    const [output] = await once(parent.stdout!, 'data')
+    const childPid = Number(String(output).trim())
+    try {
+      expect(inspectDarwinProcess(childPid)?.processGroupId).toBe(childPid)
+      await stopDarwinDescendants(parent.pid!, Date.now() + 3000)
+      expect(inspectDarwinProcess(childPid)).toBeUndefined()
+      expect(inspectDarwinProcess(parent.pid!)).toBeDefined()
+    } finally {
+      await stopDarwinDescendants(parent.pid!, Date.now() + 3000)
+      const exited = once(parent, 'exit')
+      parent.kill()
+      await exited
+    }
+  })
+})

src/agent-daemon/darwin-process-identity.ts

@@ -0,0 +1,139 @@
+import koffi from 'koffi'
+import { realpathSync } from 'node:fs'
+
+export type DarwinProcessIdentity = {
+  pid: number
+  starttime: string
+  executablePath: string
+  processGroupId: number
+  parentPid: number
+}
+
+let binding: ReturnType<typeof createBinding> | undefined
+
+function createBinding() {
+  const library = koffi.load('/usr/lib/libSystem.B.dylib')
+  return {
+    info: library.func('proc_pidinfo', 'int', [
+      'int', 'int', 'uint64_t', 'void *', 'int'
+    ]),
+    path: library.func('proc_pidpath', 'int', ['int', 'void *', 'uint32_t']),
+    list: library.func('proc_listpids', 'int', ['uint32_t', 'uint32_t', 'void *', 'int']),
+    sysctl: library.func('sysctlbyname', 'int', [
+      'str', 'void *', 'void *', 'void *', 'size_t'
+    ])
+  }
+}
+
+function native() {
+  if (process.platform !== 'darwin' || process.arch !== 'arm64') {
+    throw new Error('Darwin process inspection requires macOS arm64')
+  }
+  return binding ??= createBinding()
+}
+
+export function inspectDarwinProcess(pid: number): DarwinProcessIdentity | undefined {
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('Invalid process ID')
+  const api = native()
+  const info = Buffer.alloc(136)
+  const size = api.info(pid, 3, 0, info, info.length) as number
+  if (size === 0 && [3, 2].includes(koffi.errno())) return undefined
+  if (size !== info.length || info.readUInt32LE(12) !== pid) {
+    throw new Error(`proc_pidinfo failed (${koffi.errno()})`)
+  }
+  const path = Buffer.alloc(4096)
+  if ((api.path(pid, path, path.length) as number) <= 0) {
+    if ([3, 2].includes(koffi.errno())) return undefined
+    throw new Error(`proc_pidpath failed (${koffi.errno()})`)
+  }
+  const starttime = info.readBigUInt64LE(120) * 1_000_000n +
+    info.readBigUInt64LE(128)
+  return {
+    pid,
+    starttime: starttime.toString(),
+    executablePath: realpathSync(path.subarray(0, path.indexOf(0)).toString('utf8')),
+    processGroupId: info.readUInt32LE(100),
+    parentPid: info.readUInt32LE(16)
+  }
+}
+
+export function darwinBootId(): string {
+  const bytes = Buffer.alloc(128)
+  const size = Buffer.alloc(8)
+  size.writeBigUInt64LE(BigInt(bytes.length))
+  if (native().sysctl('kern.bootsessionuuid', bytes, size, null, 0) !== 0) {
+    throw new Error(`Boot session lookup failed (${koffi.errno()})`)
+  }
+  const value = bytes.subarray(0, bytes.indexOf(0)).toString('ascii').toLowerCase()
+  if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/u.test(value)) {
+    throw new Error('Invalid Darwin boot session identity')
+  }
+  return value
+}
+
+export function listDarwinProcessGroup(groupId: number): number[] {
+  return listDarwinPids(2, groupId)
+}
+
+function listDarwinPids(kind: number, parent: number): number[] {
+  const api = native()
+  if (!Number.isSafeInteger(parent) || parent <= 0) throw new Error('Invalid process group')
+  const required = api.list(kind, parent, null, 0) as number
+  if (required < 0) throw new Error('Process group enumeration failed')
+  const buffer = Buffer.alloc(required + 4096)
+  const size = api.list(kind, parent, buffer, buffer.length) as number
+  if (size < 0 || size >= buffer.length || size % 4 !== 0) {
+    throw new Error('Process group enumeration was incomplete')
+  }
+  const pids: number[] = []
+  for (let offset = 0; offset < size; offset += 4) {
+    const pid = buffer.readInt32LE(offset)
+    if (pid > 0) pids.push(pid)
+  }
+  return pids
+}
+
+export async function stopDarwinDescendants(
+  ownerPid: number,
+  deadline: number
+): Promise<void> {
+  const descendants: DarwinProcessIdentity[] = []
+  const pending = [ownerPid]
+  const seen = new Set(pending)
+  while (pending.length > 0) {
+    const parentPid = pending.pop()!
+    for (const pid of listDarwinPids(6, parentPid)) {
+      if (seen.has(pid)) continue
+      seen.add(pid)
+      const identity = inspectDarwinProcess(pid)
+      if (!identity || identity.parentPid !== parentPid) continue
+      descendants.push(identity)
+      pending.push(pid)
+    }
+  }
+  const matches = (identity: DarwinProcessIdentity): boolean => {
+    const current = inspectDarwinProcess(identity.pid)
+    return current !== undefined &&
+      current.starttime === identity.starttime &&
+      current.executablePath === identity.executablePath
+  }
+  const signal = (identity: DarwinProcessIdentity, value: NodeJS.Signals): void => {
+    if (!matches(identity)) return
+    try { process.kill(identity.pid, value) }
+    catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ESRCH')) throw error
+    }
+  }
+  for (const identity of [...descendants].reverse()) signal(identity, 'SIGTERM')
+  const grace = Math.min(deadline, Date.now() + 500)
+  while (Date.now() < grace && descendants.some(matches)) {
+    await new Promise(resolve => setTimeout(resolve, 25))
+  }
+  for (const identity of [...descendants].reverse()) signal(identity, 'SIGKILL')
+  while (Date.now() < deadline && descendants.some(matches)) {
+    await new Promise(resolve => setTimeout(resolve, 25))
+  }
+  if (descendants.some(matches)) {
+    throw new Error('Runtime child process cleanup could not be verified')
+  }
+}

src/agent-daemon/direct-linux-stdio-process-owner.ts

@@ -28,6 +28,7 @@ import {
   sameLinuxRuntimeProcessIdentity,
   type LinuxRuntimeProcessIdentity
 } from './runtime-process-identity'
+import { listDarwinProcessGroup, stopDarwinDescendants } from './darwin-process-identity'
 
 const DEFAULT_MAXIMUM_STDIN_WRITE_BYTES = 1024 * 1024
 const DEFAULT_MAXIMUM_OUTPUT_QUEUE_CHUNKS = 128
@@ -401,6 +402,9 @@ export class DirectLinuxStdioProcessOwner {
       throw identityError('Runtime PID identity changed before signal')
     }
     this.#registry.markStopping(this.ownerId)
+    if (process.platform === 'darwin') {
+      await stopDarwinDescendants(this.processIdentity.pid, Date.parse(deadlineAt))
+    }
     this.#stdinClosed = true
     this.#child.stdin.end()
     this.#sendSignal(-record.processIdentity.processGroupId, 'SIGTERM')
@@ -540,9 +544,9 @@ export class DirectLinuxStdioProcessOwner {
 export async function launchDirectLinuxStdioProcessOwner(
   options: DirectLinuxStdioProcessOwnerOptions
 ): Promise<DirectLinuxStdioProcessOwner> {
-  if ((options.platform ?? process.platform) !== 'linux') {
+  if (!['linux', 'darwin'].includes(options.platform ?? process.platform)) {
     throw new DirectLinuxStdioProcessOwnerError(
-      'Direct Runtime ownership is Linux-only',
+      'Direct Runtime ownership requires Linux or macOS',
       'platform'
     )
   }
@@ -786,6 +790,18 @@ export async function listLinuxPidNamespaceMembers(
   >,
   options: { procRoot?: string } = {}
 ): Promise<LinuxRuntimeProcessIdentity[]> {
+  if (process.platform === 'darwin') {
+    const identities: LinuxRuntimeProcessIdentity[] = []
+    for (const pid of listDarwinProcessGroup(owner.processGroupId)) {
+      try {
+        const identity = await readLinuxRuntimeProcessIdentity(pid, { bootId: owner.bootId })
+        if (identity.processGroupId === owner.processGroupId) identities.push(identity)
+      } catch (error) {
+        if (!isMissingProcess(error)) throw error
+      }
+    }
+    return identities.sort((left, right) => left.pid - right.pid)
+  }
   const procRoot = options.procRoot ?? '/proc'
   const entries = await readdir(procRoot, { withFileTypes: true })
   const identities: LinuxRuntimeProcessIdentity[] = []

src/agent-daemon/installed-bundle-verifier.ts

@@ -230,7 +230,8 @@ export async function verifyPublishedAgentBundle(
   await assertElfArchitecture(
     join(installationDirectory, manifest.entrypoint.runtimePath),
     manifest.arch,
-    'Agent Node runtime'
+    'Agent Node runtime',
+    manifest.platform
   )
   const manifestSha256 = sha256Bytes(manifestBytes)
   return {

src/agent-daemon/linux-process-identity.ts

@@ -7,6 +7,7 @@ import {
 import { isAbsolute, join, resolve } from 'node:path'
 import { z } from 'zod'
 import { assertAbsoluteManagedPath } from './managed-paths'
+import { inspectDarwinProcess } from './darwin-process-identity'
 
 const linuxProcessIdentitySchema = z
   .object({
@@ -45,6 +46,14 @@ export class LinuxProcessInspector {
 
   inspect(pidInput: number): LinuxProcessIdentity | undefined {
     const pid = positivePid(pidInput)
+    if (process.platform === 'darwin') {
+      const identity = inspectDarwinProcess(pid)
+      return identity === undefined ? undefined : {
+        pid: identity.pid,
+        starttime: identity.starttime,
+        executablePath: identity.executablePath
+      }
+    }
     try {
       const starttime = parseStarttime(
         this.#fileSystem.readText(

src/agent-daemon/managed-paths.ts

@@ -287,20 +287,20 @@ export function derivePrivateTemporaryRoot(options: {
   const platform = options.platform ?? process.platform
   const uid = options.uid ?? process.getuid?.()
   if (
-    platform !== 'linux' ||
+    !['linux', 'darwin'].includes(platform) ||
     uid === undefined ||
     !Number.isSafeInteger(uid) ||
     uid < 0
   ) {
     throw new ManagedPathError(
-      'Private Agent endpoint root requires a current Linux UID'
+      'Private Agent endpoint root requires a current Unix UID'
     )
   }
   const canonicalHomeDirectory = resolve(
     options.homeDirectory ?? homedir()
   )
   const temporaryDirectory = resolve(
-    options.temporaryDirectory ?? '/tmp'
+    options.temporaryDirectory ?? (platform === 'darwin' ? '/private/tmp' : '/tmp')
   )
   assertAbsoluteManagedPath(canonicalHomeDirectory)
   assertAbsoluteManagedPath(temporaryDirectory)

src/agent-daemon/peer-identity-provider.ts

@@ -67,23 +67,39 @@ export async function createLinuxPeerIdentityProvider(
     byteOrder?: 'BE' | 'LE'
     loadKoffi?: () => Promise<Koffi>
   } = {}
-): Promise<LinuxPeerIdentityProvider> {
+): Promise<UnixPeerIdentityProvider> {
   const platform = options.platform ?? process.platform
   const architecture = options.architecture ?? arch()
   const byteOrder = options.byteOrder ?? endianness()
   if (
-    platform !== 'linux' ||
+    (platform !== 'linux' && !(platform === 'darwin' && architecture === 'arm64')) ||
     !SUPPORTED_ARCHITECTURES.has(architecture) ||
     byteOrder !== 'LE'
   ) {
     throw unavailable(
-      'SO_PEERCRED is certified only on little-endian Linux x64 and arm64'
+      'Unix peer credentials require little-endian Linux or macOS arm64'
     )
   }
   try {
     const koffi =
       await (options.loadKoffi?.() ??
         import('koffi').then((module) => module.default))
+    if (platform === 'darwin') {
+      const library = koffi.load('/usr/lib/libSystem.B.dylib')
+      const getpeereid = library.func('getpeereid', 'int', [
+        'int', 'void *', 'void *'
+      ])
+      return {
+        async getPeerIdentity(socket) {
+          const uid = Buffer.alloc(4)
+          const gid = Buffer.alloc(4)
+          if (getpeereid(socketDescriptor(socket), uid, gid) !== 0) {
+            throw new Error(`getpeereid failed with errno ${koffi.errno()}`)
+          }
+          return { uid: uid.readUInt32LE() }
+        }
+      }
+    }
     return new LinuxPeerIdentityProvider(createNativeBinding(koffi))
   } catch (error) {
     if (error instanceof AgentUnsupportedError) {

src/agent-daemon/runtime-composition.ts

@@ -225,7 +225,7 @@ export async function createProductionRuntimeProtocol(
   try {
     if (
       verificationEnvironment === 'production' &&
-      process.platform === 'linux'
+      (process.platform === 'linux' || process.platform === 'darwin')
     ) {
       await (
         options.reconcileOrphanedProcesses ??
@@ -436,7 +436,7 @@ export function derivePrivateModelBridgeDirectory(
     controllerGeneration?: number
   }
 ): string {
-  if (process.platform === 'linux') {
+  if (process.platform === 'linux' || process.platform === 'darwin') {
     const stateDirectory = resolve(stateDirectoryInput)
     ensurePrivateDirectory(stateDirectory, { create: false })
     const userRoot = ensurePrivateTemporaryRoot(

src/agent-daemon/runtime-process-identity.ts

@@ -1,5 +1,6 @@
 import { readFile, readlink } from 'node:fs/promises'
 import { posix } from 'node:path'
+import { darwinBootId, inspectDarwinProcess } from './darwin-process-identity'
 
 export type LinuxRuntimeProcessIdentity = {
   bootId: string
@@ -72,6 +73,19 @@ export async function readLinuxRuntimeProcessIdentity(
   options: { procRoot?: string; bootId?: string } = {}
 ): Promise<LinuxRuntimeProcessIdentity> {
   const pid = positiveInteger(pidInput, 'PID')
+  if (process.platform === 'darwin') {
+    const identity = inspectDarwinProcess(pid)
+    if (identity === undefined) {
+      throw Object.assign(new Error('Runtime process no longer exists'), { code: 'ESRCH' })
+    }
+    return {
+      bootId: options.bootId ?? darwinBootId(),
+      pid,
+      startTimeTicks: BigInt(identity.starttime),
+      processGroupId: identity.processGroupId,
+      executablePath: identity.executablePath
+    }
+  }
   const procRoot = options.procRoot ?? '/proc'
   if (!posix.isAbsolute(procRoot) || procRoot.includes('\0')) {
     throw new Error('Linux proc root must be absolute')