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')

src/main/ipc.test.ts

@@ -1537,7 +1537,8 @@ describe('registerIpcHandlers SSH hosts', () => {
       ]
     } as const
     const agentPackageManager = {
-      getSnapshot: vi.fn(async () => agentPackageInventory),
+      getAllSnapshot: vi.fn(async () => agentPackageInventory),
+      forPlatform: vi.fn(() => agentPackageManager),
       download: vi.fn(
         async (
           architecture: 'x64' | 'arm64',
@@ -1675,7 +1676,7 @@ describe('registerIpcHandlers SSH hosts', () => {
       )?.(event, { refresh: true })
     ).resolves.toEqual(agentPackageInventory)
     expect(
-      agentPackageManager.getSnapshot
+      agentPackageManager.getAllSnapshot
     ).toHaveBeenCalledWith({ refresh: true })
     await expect(
       electronMocks.handlers.get(
@@ -1690,6 +1691,7 @@ describe('registerIpcHandlers SSH hosts', () => {
       ipcChannels.sshHostsAgentPackageProgress,
       {
         architecture: 'x64',
+        platform: 'linux',
         phase: 'downloading',
         completedBytes: 1,
         totalBytes: 2
@@ -1902,8 +1904,8 @@ describe('registerIpcHandlers SSH hosts', () => {
       })
     ).rejects.toThrow('拒绝来自未知窗口的 IPC 请求')
     expect(
-      agentPackageManager.getSnapshot
-    ).toHaveBeenCalledOnce()
+      agentPackageManager.getAllSnapshot
+    ).toHaveBeenCalledTimes(3)
 
     await expect(
       electronMocks.handlers.get(

src/main/ipc.ts

@@ -5123,7 +5123,7 @@ export function registerIpcHandlers(
       const request =
         agentPackageInventoryRequestSchema.parse(input ?? {})
       return agentPackageInventorySchema.parse(
-        await agentPackageManager.getSnapshot(request)
+        await agentPackageManager.getAllSnapshot(request)
       )
     }
   )
@@ -5135,10 +5135,9 @@ export function registerIpcHandlers(
       if (!agentPackageManager) {
         throw new Error('Agent 包管理服务不可用')
       }
-      const { architecture } =
+      const { architecture, platform } =
         agentPackageArchitectureRequestSchema.parse(input)
-      return agentPackageInventorySchema.parse(
-        await agentPackageManager.download(
+      await agentPackageManager.forPlatform(platform).download(
           architecture,
           (progress) =>
             sendValidatedProgress(
@@ -5148,7 +5147,7 @@ export function registerIpcHandlers(
               progress
             )
         )
-      )
+      return agentPackageManager.getAllSnapshot()
     }
   )
 
@@ -5171,9 +5170,8 @@ export function registerIpcHandlers(
       if (result.canceled || !archivePath) {
         return undefined
       }
-      return agentPackageInventorySchema.parse(
-        await agentPackageManager.importArchive(archivePath)
-      )
+      await agentPackageManager.importArchive(archivePath)
+      return agentPackageManager.getAllSnapshot()
     }
   )
 
@@ -5184,10 +5182,10 @@ export function registerIpcHandlers(
       if (!agentPackageManager) {
         throw new Error('Agent 包管理服务不可用')
       }
-      const { architecture } =
+      const { architecture, platform } =
         agentPackageArchitectureRequestSchema.parse(input)
       const defaultPath =
-        await agentPackageManager.getExportArchiveName(
+        await agentPackageManager.forPlatform(platform).getExportArchiveName(
           architecture
         )
       const result = await dialog.showSaveDialog(window, {
@@ -5204,7 +5202,7 @@ export function registerIpcHandlers(
       const destination = result.filePath.endsWith('.gbagent')
         ? result.filePath
         : `${result.filePath}.gbagent`
-      await agentPackageManager.exportArchive(
+      await agentPackageManager.forPlatform(platform).exportArchive(
         architecture,
         destination
       )

src/main/remote-agent/agent-bundle-verifier.ts

@@ -1,3 +1,5 @@
+import { binaryTargetArchitecture } from '../../shared/node/binary-target'
+import type { AgentPlatform } from '../../shared/agent-target'
 import {
   createHash,
   createPublicKey,
@@ -206,9 +208,10 @@ export async function verifyAgentBundleDirectory(
   await assertElfArchitecture(
     join(bundleDirectory, manifest.entrypoint.runtimePath),
     manifest.arch,
-    'Agent Node runtime'
+    'Agent Node runtime',
+    manifest.platform
   )
-  const koffiPaths = requiredKoffiPayloadPaths(manifest.arch)
+  const koffiPaths = requiredKoffiPayloadPaths(manifest.arch, manifest.platform)
   assertKoffiManifest(
     manifest,
     runtimeLock.koffi.version,
@@ -218,7 +221,8 @@ export async function verifyAgentBundleDirectory(
     await assertElfArchitecture(
       join(bundleDirectory, ...nativePath.split('/')),
       manifest.arch,
-      'Agent Koffi native binding'
+      'Agent Koffi native binding',
+      manifest.platform
     )
   }
   return {
@@ -349,15 +353,19 @@ export function assertAgentManifestMatchesRuntimeLock(
 }
 
 function requiredKoffiPayloadPaths(
-  architecture: AgentArchitecture
+  architecture: AgentArchitecture,
+  platform: AgentPlatform
 ): {
   required: string[]
   native: string[]
 } {
   const packageRoot = 'lib/node_modules/koffi'
   const nativePackage =
-    `@koromix/koffi-linux-${architecture}`
+    `@koromix/koffi-${platform}-${architecture}`
   const nativeRoot = `lib/node_modules/${nativePackage}`
+  const native = platform === 'darwin'
+    ? [`${nativeRoot}/darwin_${architecture}/koffi.node`]
+    : [`${nativeRoot}/linux_${architecture}/koffi.node`, `${nativeRoot}/musl_${architecture}/koffi.node`]
   return {
     required: [
       `${packageRoot}/package.json`,
@@ -366,13 +374,9 @@ function requiredKoffiPayloadPaths(
       `${packageRoot}/src/koffi/src/static.js`,
       `${nativeRoot}/package.json`,
       `${nativeRoot}/index.js`,
-      `${nativeRoot}/linux_${architecture}/koffi.node`,
-      `${nativeRoot}/musl_${architecture}/koffi.node`
+      ...native
     ],
-    native: [
-      `${nativeRoot}/linux_${architecture}/koffi.node`,
-      `${nativeRoot}/musl_${architecture}/koffi.node`
-    ]
+    native
   }
 }
 
@@ -390,7 +394,7 @@ function assertKoffiManifest(
     }
   }
   const nativePackage =
-    `@koromix/koffi-linux-${manifest.arch}`
+    `@koromix/koffi-${manifest.platform}-${manifest.arch}`
   const koffiLicense = manifest.licenses.find(
     (license) => license.package === 'koffi'
   )
@@ -614,14 +618,15 @@ function modeString(mode: number): string {
 async function assertElfArchitecture(
   filePath: string,
   expectedArchitecture: AgentArchitecture,
-  description: string
+  description: string,
+  platform: AgentPlatform
 ): Promise<void> {
   const handle = await open(filePath, 'r')
   try {
     const header = Buffer.alloc(64)
     const { bytesRead } = await handle.read(header, 0, header.length, 0)
-    const actualArchitecture = detectElfArchitecture(
-      header.subarray(0, bytesRead)
+    const actualArchitecture = binaryTargetArchitecture(
+      header.subarray(0, bytesRead), platform
     )
     if (actualArchitecture !== expectedArchitecture) {
       throw new Error(
@@ -633,29 +638,6 @@ async function assertElfArchitecture(
   }
 }
 
-function detectElfArchitecture(
-  buffer: Buffer
-): AgentArchitecture | undefined {
-  if (
-    buffer.length < 20 ||
-    buffer[0] !== 0x7f ||
-    buffer.toString('ascii', 1, 4) !== 'ELF' ||
-    (buffer[5] !== 1 && buffer[5] !== 2)
-  ) {
-    return undefined
-  }
-  const machine =
-    buffer[5] === 2
-      ? buffer.readUInt16BE(18)
-      : buffer.readUInt16LE(18)
-  if (machine === 62) {
-    return 'x64'
-  }
-  if (machine === 183) {
-    return 'arm64'
-  }
-  return undefined
-}
 
 function parseContract<T>(
   schema: { safeParse(value: unknown): {

src/main/remote-agent/agent-installation-manager.ts

@@ -43,7 +43,7 @@ export type AgentInstallationIdentity = {
     major: number
     minor: number
   }
-  platform: 'linux'
+  platform: 'linux' | 'darwin'
   architecture: AgentArchitecture
   supervisor: 'detached-on-demand'
 }
@@ -239,7 +239,7 @@ export class AgentInstallationManager {
         protocol: {
           ...(registeredProtocol ?? runtimeLock.protocol)
         },
-        platform: 'linux',
+        platform: probe.platform,
         architecture: registered.arch,
         supervisor: 'detached-on-demand'
       }

src/main/remote-agent/agent-package-manager.test.ts

@@ -20,6 +20,7 @@ import {
 } from '../../shared/agent-package-contracts'
 import {
   AgentPackageManager,
+  selectLatestCompatibleEntry,
   type VerifiedRemoteAgentInstallCandidate
 } from './agent-package-manager'
 
@@ -256,6 +257,22 @@ function response(
 }
 
 describe('AgentPackageManager remote install candidates', () => {
+  it('selects Linux and Darwin arm64 independently from one catalog', async () => {
+    await createFixture('mirror', (catalog) => {
+      for (const platform of ['linux', 'darwin'] as const) {
+        catalog.entries.push({
+          ...catalog.entries[0]!,
+          platform,
+          architecture: 'arm64',
+          archive: `goodbuddy-agent-2.0.0-${platform}-arm64.gbagent`
+        })
+      }
+      const parsed = agentPackageCatalogSchema.parse(catalog)
+      expect(selectLatestCompatibleEntry(parsed, 'arm64', '2.0.0').platform).toBe('linux')
+      expect(selectLatestCompatibleEntry(parsed, 'arm64', '2.0.0', 'darwin').platform).toBe('darwin')
+      expect(() => selectLatestCompatibleEntry(parsed, 'x64', '2.0.0', 'darwin')).toThrow()
+    })
+  })
   it('removes interrupted manager-owned staging on startup', async () => {
     const fixture = await createFixture('mirror')
     const packageRoot = join(

src/main/remote-agent/agent-package-manager.ts

@@ -16,6 +16,7 @@ import {
   writeFile
 } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
+import { agentPlatformSchema, type AgentPlatform } from '../../shared/agent-target'
 import {
   agentPackageArchiveName,
   agentPackageCatalogSchema,
@@ -94,6 +95,7 @@ type CatalogState =
     }
 
 export type AgentPackageManagerOptions = {
+  platform?: AgentPlatform
   userDataPath: string
   desktopVersion: string
   keyRegistryPath: string
@@ -104,7 +106,7 @@ export type AgentPackageManagerOptions = {
 
 export type VerifiedRemoteAgentInstallCandidate = {
   source: UpdateSource
-  platform: 'linux'
+  platform: AgentPlatform
   architecture: AgentArchitecture
   version: string
   minimumDesktopVersion: string
@@ -161,6 +163,7 @@ export type AgentPackageArchiveLease = {
 }
 
 export type AcquireInstallArchiveOptions = {
+  platform?: AgentPlatform
   signal?: AbortSignal
   onProgress?: (progress: AgentPackageDownloadProgress) => void
 }
@@ -185,7 +188,7 @@ function candidateFromCatalogEntry(
 ): VerifiedRemoteAgentInstallCandidate {
   return {
     source,
-    platform: 'linux',
+    platform: entry.platform,
     architecture: entry.architecture,
     version: entry.version,
     minimumDesktopVersion: entry.minimumDesktopVersion,
@@ -209,7 +212,7 @@ function candidateFromVerifiedRecord(
   const descriptor = record.verified.descriptor
   return {
     source,
-    platform: 'linux',
+    platform: descriptor.platform,
     architecture: descriptor.architecture,
     version: descriptor.version,
     minimumDesktopVersion: descriptor.minimumDesktopVersion,
@@ -220,7 +223,8 @@ function candidateFromVerifiedRecord(
     },
     archive: agentPackageArchiveName(
       descriptor.version,
-      descriptor.architecture
+      descriptor.architecture,
+      descriptor.platform
     ),
     size,
     sha256: record.archiveSha256,
@@ -229,6 +233,9 @@ function candidateFromVerifiedRecord(
 }
 
 export class AgentPackageManager {
+  readonly #options: AgentPackageManagerOptions
+  readonly #platform: AgentPlatform
+  readonly #platformManagers = new Map<AgentPlatform, AgentPackageManager>()
   readonly #rootDirectory: string
   readonly #desktopVersion: string
   readonly #keyRegistryPath: string
@@ -250,6 +257,8 @@ export class AgentPackageManager {
   #catalogState?: CatalogState
 
   constructor(options: AgentPackageManagerOptions) {
+    this.#options = options
+    this.#platform = agentPlatformSchema.parse(options.platform ?? 'linux')
     this.#rootDirectory = resolve(
       options.userDataPath,
       'remote-components',
@@ -263,6 +272,31 @@ export class AgentPackageManager {
     this.#startupCleanup = this.#cleanupInterruptedArtifacts()
   }
 
+  forPlatform(platform: AgentPlatform): AgentPackageManager {
+    if (platform === this.#platform) return this
+    let manager = this.#platformManagers.get(platform)
+    if (!manager) {
+      manager = new AgentPackageManager({ ...this.#options, platform })
+      this.#platformManagers.set(platform, manager)
+    }
+    return manager
+  }
+
+  async getAllSnapshot(options: { refresh?: boolean } = {}): Promise<AgentPackageInventory> {
+    const linux = await this.forPlatform('linux').getSnapshot(options)
+    const darwin = this.forPlatform('darwin')
+    darwin.#catalogState = this.forPlatform('linux').#catalogState
+    const mac = await darwin.getInventory(options)
+    return agentPackageInventorySchema.parse({
+      ...linux,
+      entries: [...linux.entries, ...mac.entries]
+    })
+  }
+
+  #select(catalog: AgentPackageCatalog, architecture: AgentArchitecture, desktopVersion: string) {
+    return selectLatestCompatibleEntry(catalog, architecture, desktopVersion, this.#platform)
+  }
+
   async getInventory(
     options: { refresh?: boolean } = {}
   ): Promise<AgentPackageInventory> {
@@ -270,7 +304,9 @@ export class AgentPackageManager {
       this.#installed.clear()
     }
     const entries = await Promise.all(
-      agentArchitectureSchema.options.map(async (architecture) => {
+      agentArchitectureSchema.options.filter(architecture =>
+        this.#platform === 'linux' || architecture === 'arm64'
+      ).map(async (architecture) => {
         let record: InstalledRecord | undefined
         let state: 'not-downloaded' | 'verified' | 'invalid'
         try {
@@ -283,7 +319,7 @@ export class AgentPackageManager {
         }
         const latestVersion = this.#latestVersion(architecture)
         return {
-          platform: 'linux' as const,
+          platform: this.#platform,
           architecture,
           state,
           version: record?.verified.descriptor.version ?? null,
@@ -334,8 +370,11 @@ export class AgentPackageManager {
 
   async getRemoteEnvironmentCatalog(
     architecture: AgentArchitecture,
-    options: { signal?: AbortSignal } = {}
+    options: { signal?: AbortSignal; platform?: AgentPlatform } = {}
   ): Promise<VerifiedRemoteAgentEnvironmentCatalog> {
+    if (options.platform && options.platform !== this.#platform) {
+      return this.forPlatform(options.platform).getRemoteEnvironmentCatalog(architecture, options)
+    }
     options.signal?.throwIfAborted()
     let entry: AgentPackageCatalogEntry
     let source: UpdateSource | undefined
@@ -346,7 +385,7 @@ export class AgentPackageManager {
         source,
         options.signal
       )
-      entry = selectLatestCompatibleEntry(
+      entry = this.#select(
         catalog,
         architecture,
         this.#desktopVersion
@@ -406,8 +445,11 @@ export class AgentPackageManager {
    */
   async getRemoteInstallCandidate(
     architecture: AgentArchitecture,
-    options: { signal?: AbortSignal } = {}
+    options: { signal?: AbortSignal; platform?: AgentPlatform } = {}
   ): Promise<VerifiedRemoteAgentInstallCandidate> {
+    if (options.platform && options.platform !== this.#platform) {
+      return this.forPlatform(options.platform).getRemoteInstallCandidate(architecture, options)
+    }
     options.signal?.throwIfAborted()
     const source = await this.#getUpdateSource()
     options.signal?.throwIfAborted()
@@ -415,7 +457,7 @@ export class AgentPackageManager {
       source,
       options.signal
     )
-    const entry = selectLatestCompatibleEntry(
+    const entry = this.#select(
       catalog,
       architecture,
       this.#desktopVersion
@@ -463,7 +505,7 @@ export class AgentPackageManager {
         source,
         signal
       )
-      const entry = selectLatestCompatibleEntry(
+      const entry = this.#select(
         catalog,
         architecture,
         this.#desktopVersion
@@ -484,6 +526,11 @@ export class AgentPackageManager {
     expectedCandidate: VerifiedRemoteAgentInstallCandidate,
     options: AcquireInstallArchiveOptions = {}
   ): Promise<AgentPackageArchiveLease> {
+    if (expectedCandidate.platform !== this.#platform) {
+      return this.forPlatform(expectedCandidate.platform).acquireInstallArchive(
+        architecture, expectedCandidate, options
+      )
+    }
     return this.#runExclusive(
       architecture,
       async () => {
@@ -507,7 +554,7 @@ export class AgentPackageManager {
           source,
           options.signal
         )
-        const entry = selectLatestCompatibleEntry(
+        const entry = this.#select(
           catalog,
           architecture,
           this.#desktopVersion
@@ -534,6 +581,9 @@ export class AgentPackageManager {
     architecture: AgentArchitecture,
     options: AcquireInstallArchiveOptions = {}
   ): Promise<AgentPackageArchiveLease> {
+    if (options.platform && options.platform !== this.#platform) {
+      return this.forPlatform(options.platform).acquireGoodBuddyInstallArchive(architecture, options)
+    }
     return this.#runExclusive(
       architecture,
       async () => {
@@ -562,7 +612,7 @@ export class AgentPackageManager {
         }
         let entry: AgentPackageCatalogEntry
         if (this.#catalogState?.state === 'available') {
-          entry = selectLatestCompatibleEntry(
+          entry = this.#select(
             this.#catalogState.catalog,
             architecture,
             this.#desktopVersion
@@ -584,7 +634,7 @@ export class AgentPackageManager {
             source,
             options.signal
           )
-          entry = selectLatestCompatibleEntry(
+          entry = this.#select(
             catalog,
             architecture,
             this.#desktopVersion
@@ -651,6 +701,7 @@ export class AgentPackageManager {
   ): Promise<boolean> {
     const descriptor = record.verified.descriptor
     if (
+      descriptor.platform === candidate.platform &&
       descriptor.architecture === candidate.architecture &&
       descriptor.version === candidate.version &&
       descriptor.minimumDesktopVersion ===
@@ -831,11 +882,12 @@ export class AgentPackageManager {
       )
       const architecture =
         installed.verified.descriptor.architecture
-      return await this.#runExclusive(
+      const manager = this.forPlatform(installed.verified.descriptor.platform)
+      return await manager.#runExclusive(
         architecture,
         async () => {
-          await this.#publishInstalled(installed, architecture)
-          return this.getInventory()
+          await manager.#publishInstalled(installed, architecture)
+          return manager.getInventory()
         }
       )
     } finally {
@@ -918,7 +970,8 @@ export class AgentPackageManager {
         .verified.descriptor
     return agentPackageArchiveName(
       descriptor.version,
-      descriptor.architecture
+      descriptor.architecture,
+      descriptor.platform
     )
   }
 
@@ -978,7 +1031,10 @@ export class AgentPackageManager {
           desktopVersion: this.#desktopVersion,
           trustedRegistry: await this.#loadTrustedRegistry()
         })
-        if (packageContent.descriptor.version !== entry.name) {
+        if (
+          packageContent.descriptor.version !== entry.name ||
+          packageContent.descriptor.platform !== this.#platform
+        ) {
           continue
         }
         const archivePath = join(directory, 'package.gbagent')
@@ -1051,6 +1107,10 @@ export class AgentPackageManager {
     architecture: AgentArchitecture,
     catalogEntry?: AgentPackageCatalogEntry
   ): Promise<InstalledRecord> {
+    if (
+      installed.verified.descriptor.platform !== this.#platform ||
+      installed.verified.descriptor.architecture !== architecture
+    ) throw new Error('Agent package does not match the selected platform and architecture')
     const destination = join(
       this.#architectureRoot(architecture),
       installed.verified.descriptor.version
@@ -1318,7 +1378,7 @@ export class AgentPackageManager {
       return null
     }
     try {
-      return selectLatestCompatibleEntry(
+      return this.#select(
         this.#catalogState.catalog,
         architecture,
         this.#desktopVersion
@@ -1701,7 +1761,7 @@ export class AgentPackageManager {
     await mkdir(this.#rootDirectory, { recursive: true })
     const path = join(
       this.#rootDirectory,
-      `.stage-linux-${architecture}-${randomUUID()}`
+      `.stage-${this.#platform}-${architecture}-${randomUUID()}`
     )
     await mkdir(path)
     return path
@@ -1710,7 +1770,7 @@ export class AgentPackageManager {
   async #cleanupInterruptedArtifacts(): Promise<void> {
     await this.#removeOwnedTemporaryDirectories(
       this.#rootDirectory,
-      /^\.stage-linux-(?:x64|arm64|import)-[0-9a-f-]{36}$/u
+      new RegExp(`^\\.stage-${this.#platform}-(?:x64|arm64|import)-[0-9a-f-]{36}$`, 'u')
     )
     await Promise.all(
       agentArchitectureSchema.options.map((architecture) =>
@@ -1756,7 +1816,7 @@ export class AgentPackageManager {
   #architectureRoot(
     architecture: AgentArchitecture
   ): string {
-    return join(this.#rootDirectory, `linux-${architecture}`)
+    return join(this.#rootDirectory, `${this.#platform}-${architecture}`)
   }
 
   #loadTrustedRegistry(): Promise<AgentReleaseKeyRegistry> {
@@ -1825,10 +1885,10 @@ export class AgentPackageManager {
     observer:
       | ((progress: AgentPackageDownloadProgress) => void)
       | undefined,
-    progress: AgentPackageDownloadProgress
+    progress: Omit<AgentPackageDownloadProgress, 'platform'>
   ): void {
     try {
-      observer?.(agentPackageDownloadProgressSchema.parse(progress))
+      observer?.(agentPackageDownloadProgressSchema.parse({ ...progress, platform: this.#platform }))
     } catch {
       // Progress observers cannot alter the package operation.
     }
@@ -1838,11 +1898,13 @@ export class AgentPackageManager {
 export function selectLatestCompatibleEntry(
   catalog: AgentPackageCatalog,
   architecture: AgentArchitecture,
-  desktopVersion: string
+  desktopVersion: string,
+  platform: AgentPlatform = 'linux'
 ): AgentPackageCatalogEntry {
   const entry = catalog.entries
     .filter(
       (candidate) =>
+        candidate.platform === platform &&
         candidate.architecture === architecture &&
         compareSemanticVersions(
           desktopVersion,

src/main/remote-agent/agent-package-verifier.ts

@@ -188,6 +188,7 @@ export async function verifyExtractedAgentPackage(options: {
     }
   )
   if (
+    agentBundle.manifest.platform !== descriptor.platform ||
     agentBundle.manifest.agentVersion !== descriptor.version ||
     agentBundle.manifest.protocol.major !==
       descriptor.agentProtocol.major ||
@@ -231,6 +232,7 @@ export async function verifyExtractedAgentPackage(options: {
       }
     )
   if (
+    runtimeBundle.manifest.platform !== descriptor.platform ||
     runtimeBundle.manifest.runtimeVersion !==
       descriptor.remoteRuntime.version ||
     runtimeBundle.manifest.bundleDigest !==

src/main/remote-agent/control-plane-package-installer.ts

@@ -63,6 +63,7 @@ const windowsReservedNamePattern =
 
 type JsonRecord = Record<string, unknown>
 type Architecture = 'x64' | 'arm64'
+type Platform = 'linux' | 'darwin'
 type Protocol = { major: number; minor: number }
 type FileRecord = {
   path: string
@@ -94,7 +95,7 @@ export type PackageInstallerAgentIdentity = {
   agentVersion: string
   manifestSha256: string
   binaryDigest: string
-  platform: 'linux'
+  platform: Platform
   architecture: Architecture
   protocol: Protocol
   supervisor: 'detached-on-demand'
@@ -107,7 +108,7 @@ export type PackageInstallerRuntimeIdentity = {
   manifestDigest: string
   runtimeAdapterDigest: string
   acpCapabilitiesDigest: string
-  platform: 'linux'
+  platform: Platform
   architecture: Architecture
   protocol: Protocol
 }
@@ -818,7 +819,7 @@ function assertOuterDescriptor(
     descriptor.component !== 'agent' ||
     !versionPattern.test(String(descriptor.version)) ||
     !versionPattern.test(String(descriptor.minimumDesktopVersion)) ||
-    descriptor.platform !== 'linux' ||
+    !isSupportedTarget(descriptor.platform, architecture) ||
     !['x64', 'arm64'].includes(String(architecture)) ||
     typeof descriptor.signingKeyId !== 'string' ||
     !digestPattern.test(String(descriptor.contentDigest)) ||
@@ -920,7 +921,7 @@ function assertAgentManifest(
     manifest.formatVersion !== 1 ||
     manifest.product !== 'GoodBuddy' ||
     !versionPattern.test(String(manifest.agentVersion)) ||
-    manifest.platform !== 'linux' ||
+    !isSupportedTarget(manifest.platform, manifest.arch) ||
     !['x64', 'arm64'].includes(String(manifest.arch)) ||
     !isRecord(manifest.entrypoint) ||
     !Array.isArray(manifest.licenses)
@@ -944,6 +945,7 @@ function assertAgentManifest(
     lock.formatVersion !== 1 ||
     manifest.agentVersion !== lock.agentVersion ||
     manifest.arch !== descriptor.architecture ||
+    manifest.platform !== descriptor.platform ||
     manifest.agentVersion !== descriptor.version ||
     canonicalJson(agentProtocol) !== canonicalJson(descriptor.agentProtocol) ||
     canonicalJson(agentProtocol) !== canonicalJson(lock.protocol)
@@ -1002,7 +1004,7 @@ function assertAgentManifest(
   }
   const architecture = manifest.arch as Architecture
   const koffiPackageRoot = 'lib/node_modules/koffi'
-  const koffiNativePackage = `@koromix/koffi-linux-${architecture}`
+  const koffiNativePackage = `@koromix/koffi-${manifest.platform}-${architecture}`
   const koffiNativeRoot =
     `lib/node_modules/${koffiNativePackage}`
   for (const required of [
@@ -1017,10 +1019,7 @@ function assertAgentManifest(
       throw new Error(`Agent Koffi payload is missing: ${required}`)
     }
   }
-  for (const native of [
-    `lib/node_modules/@koromix/koffi-linux-${manifest.arch}/linux_${manifest.arch}/koffi.node`,
-    `lib/node_modules/@koromix/koffi-linux-${manifest.arch}/musl_${manifest.arch}/koffi.node`
-  ]) {
+  for (const native of nativeKoffiPaths(manifest.platform as Platform, architecture)) {
     if (!declared.has(native)) {
       throw new Error(`Agent Koffi payload is missing: ${native}`)
     }
@@ -1091,11 +1090,12 @@ function assertRuntimeManifest(
   const runtime = isRecord(lock.runtimes) && isRecord(lock.runtimes.opencode)
     ? lock.runtimes.opencode
     : undefined
+  const targetKey = descriptor.platform === 'darwin' ? 'darwin-arm64' : String(descriptor.architecture)
   const target =
     runtime !== undefined &&
     isRecord(runtime.targets) &&
-    isRecord(runtime.targets[String(descriptor.architecture)])
-      ? runtime.targets[String(descriptor.architecture)]
+    isRecord(runtime.targets[targetKey])
+      ? runtime.targets[targetKey]
       : undefined
   const remote = descriptor.remoteRuntime as JsonRecord
   if (
@@ -1103,7 +1103,7 @@ function assertRuntimeManifest(
     manifest.product !== 'GoodBuddy' ||
     manifest.runtimeId !== 'opencode' ||
     manifest.provider !== 'opencode' ||
-    manifest.platform !== 'linux' ||
+    manifest.platform !== descriptor.platform ||
     manifest.architecture !== descriptor.architecture ||
     !versionPattern.test(String(manifest.runtimeVersion)) ||
     !digestPattern.test(String(manifest.bundleDigest)) ||
@@ -1255,7 +1255,26 @@ function assertRuntimeManifest(
   }
 }
 
-function elfArchitecture(bytes: Buffer): Architecture | undefined {
+function isSupportedTarget(platform: unknown, architecture: unknown): boolean {
+  return (platform === 'linux' && (architecture === 'x64' || architecture === 'arm64')) ||
+    (platform === 'darwin' && architecture === 'arm64')
+}
+
+function nativeKoffiPaths(platform: Platform, architecture: Architecture): string[] {
+  const root = `lib/node_modules/@koromix/koffi-${platform}-${architecture}`
+  return platform === 'darwin'
+    ? [`${root}/darwin_${architecture}/koffi.node`]
+    : [`${root}/linux_${architecture}/koffi.node`, `${root}/musl_${architecture}/koffi.node`]
+}
+
+function elfArchitecture(bytes: Buffer, platform: Platform): Architecture | undefined {
+  if (platform === 'darwin') {
+    if (bytes.length < 8) return undefined
+    const cpu = bytes.readUInt32LE(0) === 0xfeedfacf
+      ? bytes.readUInt32LE(4)
+      : bytes.readUInt32BE(0) === 0xfeedfacf ? bytes.readUInt32BE(4) : 0
+    return cpu === 0x0100000c ? 'arm64' : undefined
+  }
   if (
     bytes.length < 20 ||
     !bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46]))
@@ -1273,32 +1292,16 @@ function elfArchitecture(bytes: Buffer): Architecture | undefined {
 
 function assertExtractedArchitectures(
   preparedRoot: string,
-  architecture: Architecture
+  architecture: Architecture,
+  platform: Platform
 ): void {
   for (const path of [
     join(preparedRoot, 'agent', 'node'),
-    join(
-      preparedRoot,
-      'agent',
-      'lib',
-      'node_modules',
-      `@koromix/koffi-linux-${architecture}`,
-      `linux_${architecture}`,
-      'koffi.node'
-    ),
-    join(
-      preparedRoot,
-      'agent',
-      'lib',
-      'node_modules',
-      `@koromix/koffi-linux-${architecture}`,
-      `musl_${architecture}`,
-      'koffi.node'
-    ),
+    ...nativeKoffiPaths(platform, architecture).map(path => join(preparedRoot, 'agent', path)),
     join(preparedRoot, 'runtime', 'bin', 'opencode')
   ]) {
     if (
-      elfArchitecture(readFileHeader(path, 64)) !== architecture
+      elfArchitecture(readFileHeader(path, 64), platform) !== architecture
     ) {
       throw new Error(`Installed executable architecture mismatch: ${basename(path)}`)
     }
@@ -1518,7 +1521,7 @@ function verifyArchive(
         agentVersion: String(agentManifest.agentVersion),
         manifestSha256: agentManifestSha256,
         binaryDigest: `sha256:${agentManifestSha256}`,
-        platform: 'linux',
+        platform: descriptor.platform as Platform,
         architecture,
         protocol: protocol(agentManifest.protocol, 'Agent protocol'),
         supervisor: 'detached-on-demand'
@@ -1530,7 +1533,7 @@ function verifyArchive(
         manifestDigest: runtime.manifestDigest,
         runtimeAdapterDigest: String(runtime.manifest.adapterDigest),
         acpCapabilitiesDigest: String(runtime.manifest.acpCapabilitiesDigest),
-        platform: 'linux',
+        platform: descriptor.platform as Platform,
         architecture,
         protocol: protocol(runtime.manifest.protocol, 'Runtime protocol')
       }
@@ -1766,7 +1769,7 @@ function extractPayload(
     } finally {
       closeSync(handle)
     }
-    assertExtractedArchitectures(temporary, verified.agent.architecture)
+    assertExtractedArchitectures(temporary, verified.agent.architecture, verified.agent.platform)
     chmodSync(temporary, 0o700)
     renameSync(temporary, destinationRoot)
   } catch (error) {
@@ -2127,7 +2130,7 @@ function readPreparedState(path: string): PreparedState {
     !sha256Pattern.test(String(agent.manifestSha256)) ||
     agent.installationId !== `agent-${String(agent.manifestSha256)}` ||
     agent.binaryDigest !== `sha256:${String(agent.manifestSha256)}` ||
-    agent.platform !== 'linux' ||
+    !isSupportedTarget(agent.platform, agent.architecture) ||
     !['x64', 'arm64'].includes(String(agent.architecture)) ||
     agent.supervisor !== 'detached-on-demand' ||
     runtime.runtimeId !== 'opencode' ||
@@ -2136,7 +2139,7 @@ function readPreparedState(path: string): PreparedState {
     !digestPattern.test(String(runtime.manifestDigest)) ||
     !digestPattern.test(String(runtime.runtimeAdapterDigest)) ||
     !digestPattern.test(String(runtime.acpCapabilitiesDigest)) ||
-    runtime.platform !== 'linux' ||
+    runtime.platform !== agent.platform ||
     runtime.architecture !== agent.architecture
   ) {
     throw new Error('Prepared package state identity is invalid')
@@ -2159,7 +2162,7 @@ function readPreparedState(path: string): PreparedState {
       agentVersion: String(agent.agentVersion),
       manifestSha256: String(agent.manifestSha256),
       binaryDigest: String(agent.binaryDigest),
-      platform: 'linux',
+      platform: agent.platform as Platform,
       architecture: agent.architecture as Architecture,
       protocol: agentProtocol,
       supervisor: 'detached-on-demand'
@@ -2171,7 +2174,7 @@ function readPreparedState(path: string): PreparedState {
       manifestDigest: String(runtime.manifestDigest),
       runtimeAdapterDigest: String(runtime.runtimeAdapterDigest),
       acpCapabilitiesDigest: String(runtime.acpCapabilitiesDigest),
-      platform: 'linux',
+      platform: agent.platform as Platform,
       architecture: runtime.architecture as Architecture,
       protocol: runtimeProtocol
     }
@@ -2322,7 +2325,7 @@ function assertPreparedIdentity(
     agentVersion: String(agentManifest.agentVersion),
     manifestSha256: agentManifestSha256,
     binaryDigest: `sha256:${agentManifestSha256}`,
-    platform: 'linux',
+    platform: agentManifest.platform as Platform,
     architecture,
     protocol: protocol(agentManifest.protocol, 'Agent protocol'),
     supervisor: 'detached-on-demand'
@@ -2336,7 +2339,7 @@ function assertPreparedIdentity(
     acpCapabilitiesDigest: String(
       runtime.manifest.acpCapabilitiesDigest
     ),
-    platform: 'linux',
+    platform: agentManifest.platform as Platform,
     architecture,
     protocol: protocol(
       runtime.manifest.protocol,

src/main/remote-agent/managed-remote-acp-runtime.ts

@@ -48,7 +48,7 @@ type ManagedRemoteRuntimeIdentity = {
   bundleDigest: string
   runtimeAdapterDigest: string
   acpCapabilitiesDigest: string
-  platform: 'linux'
+  platform: 'linux' | 'darwin'
   architecture: 'x64' | 'arm64'
 }
 
@@ -648,7 +648,7 @@ function runtimeIdentityFromCapabilities(
 ): ManagedRemoteRuntimeIdentity {
   if (
     installation.runtimeId !== 'opencode' ||
-    installation.platform !== 'linux'
+    (installation.platform !== 'linux' && !(installation.platform === 'darwin' && installation.architecture === 'arm64'))
   ) {
     throw new Error(
       'Remote Agent does not advertise the current Runtime'
@@ -660,7 +660,7 @@ function runtimeIdentityFromCapabilities(
     bundleDigest: installation.bundleDigest,
     runtimeAdapterDigest: installation.runtimeAdapterDigest,
     acpCapabilitiesDigest: installation.acpCapabilitiesDigest,
-    platform: 'linux',
+    platform: installation.platform,
     architecture: installation.architecture
   }
   assertRuntimeAdvertised(runtime, capabilities)

src/main/remote-agent/managed-remote-project-runtime-validator.test.ts

@@ -155,6 +155,7 @@ function harness(options: {
       installationId: agentInstallationId,
       binaryDigest: status.binaryDigest,
       version: status.agentVersion,
+      platform: 'linux',
       architecture,
       protocolMajor: 1
     },

src/main/remote-agent/managed-remote-project-runtime-validator.ts

@@ -165,7 +165,7 @@ function assertInstallationIdentity(
 ): void {
   if (
     installation.runtimeId !== 'opencode' ||
-    installation.platform !== 'linux' ||
+    installation.platform !== input.agent.platform ||
     installation.architecture !== input.agent.architecture
   ) {
     throw new Error(

src/main/remote-agent/remote-agent-connection-manager.ts

@@ -64,7 +64,7 @@ export type RemoteAgentInstallationIdentity = {
     major: number
     minor: number
   }
-  platform: 'linux'
+  platform: 'linux' | 'darwin'
   architecture: 'x64' | 'arm64'
   supervisor: 'detached-on-demand'
   requiredCapabilities?: ReadonlyArray<{
@@ -1145,7 +1145,7 @@ function validateInstallation(
     input.protocol ?? AGENT_PROTOCOL_VERSION
   )
   if (
-    input.platform !== 'linux' ||
+    (input.platform !== 'linux' && !(input.platform === 'darwin' && input.architecture === 'arm64')) ||
     !['x64', 'arm64'].includes(input.architecture) ||
     input.supervisor !== 'detached-on-demand'
   ) {

src/main/remote-agent/remote-environment-preparer.ts

@@ -164,7 +164,8 @@ export class RemoteEnvironmentPreparer implements Preparer {
           await this.#acquireGoodBuddyArchive(
             probe.architecture,
             emit,
-            signal
+            signal,
+            probe.platform
           )
         candidate = archiveLease.candidate
         method = 'goodbuddy-transfer'
@@ -173,7 +174,7 @@ export class RemoteEnvironmentPreparer implements Preparer {
           candidate =
             await this.#agentPackageManager.getRemoteInstallCandidate(
               probe.architecture,
-              { signal }
+              { signal, platform: probe.platform }
             )
         } catch (error) {
           if (requestedMethod === 'remote-download') {
@@ -183,14 +184,15 @@ export class RemoteEnvironmentPreparer implements Preparer {
             await this.#acquireGoodBuddyArchive(
               probe.architecture,
               emit,
-              signal
+              signal,
+              probe.platform
             )
           candidate = archiveLease.candidate
           method = 'goodbuddy-transfer'
         }
       }
       signal.throwIfAborted()
-      assertCandidate(candidate, probe.architecture)
+      assertCandidate(candidate, probe.architecture, probe.platform)
       await assertTargetCurrent(this.#resolver, target, signal)
 
       operationId = randomUUID()
@@ -503,12 +505,14 @@ export class RemoteEnvironmentPreparer implements Preparer {
       method: RemoteEnvironmentPreparationMethod,
       phase: RemoteEnvironmentUpdateProgress['phase']
     ) => void,
-    signal: AbortSignal
+    signal: AbortSignal,
+    platform: 'linux' | 'darwin'
   ): Promise<AgentPackageArchiveLease> {
     return this.#agentPackageManager.acquireGoodBuddyInstallArchive(
       architecture,
       {
         signal,
+        platform,
         onProgress: (progress) => {
           emit(
             'goodbuddy-transfer',
@@ -674,10 +678,11 @@ function assertSameLeaseIdentity(
 
 function assertCandidate(
   candidate: VerifiedRemoteAgentInstallCandidate,
-  architecture: 'x64' | 'arm64'
+  architecture: 'x64' | 'arm64',
+  platform: 'linux' | 'darwin'
 ): void {
   if (
-    candidate.platform !== 'linux' ||
+    candidate.platform !== platform ||
     candidate.architecture !== architecture
   ) {
     throw new Error('签名 Agent 安装候选与 Host 架构不匹配')

src/main/remote-agent/remote-project-save-service.ts

@@ -59,6 +59,7 @@ export type RemoteProjectRuntimeValidationInput = Readonly<{
     installationId: AgentInstallationIdentity['installationId']
     binaryDigest: string
     version: string
+    platform: 'linux' | 'darwin'
     architecture: 'x64' | 'arm64'
     protocolMajor: number
   }>
@@ -308,6 +309,7 @@ export class RemoteProjectSaveService {
         installationId: installation.installationId,
         binaryDigest: installation.binaryDigest,
         version: installation.agentVersion,
+        platform: installation.platform,
         architecture: installation.architecture,
         protocolMajor: installation.protocol.major
       },
@@ -484,7 +486,7 @@ function assertInstallation(
       installation.installationId
     ) ||
     !sha256DigestSchema.safeParse(installation.binaryDigest).success ||
-    installation.platform !== 'linux' ||
+    (installation.platform !== 'linux' && !(installation.platform === 'darwin' && installation.architecture === 'arm64')) ||
     !['x64', 'arm64'].includes(installation.architecture) ||
     installation.supervisor !== 'detached-on-demand'
   ) {

src/main/remote-agent/remote-runtime-installation-manager.ts

@@ -36,7 +36,7 @@ export type RemoteRuntimeInstallationIdentity = {
   manifestDigest: string
   runtimeAdapterDigest: string
   acpCapabilitiesDigest: string
-  platform: 'linux'
+  platform: 'linux' | 'darwin'
   architecture: AgentArchitecture
 }
 
@@ -188,7 +188,7 @@ export class RemoteRuntimeInstallationManager {
         )
       }
       if (
-        probe.platform !== 'linux' ||
+        (probe.platform !== 'linux' && !(probe.platform === 'darwin' && probe.architecture === 'arm64')) ||
         (
           probe.architecture !== 'x64' &&
           probe.architecture !== 'arm64'
@@ -279,7 +279,7 @@ export class RemoteRuntimeInstallationManager {
         runtimeAdapterDigest,
         acpCapabilitiesDigest:
           current.acpCapabilitiesDigest,
-        platform: 'linux',
+        platform: probe.platform,
         architecture: current.architecture
       }
     } catch (error) {

src/main/remote-agent/remote-runtime-resource-loader.ts

@@ -275,7 +275,7 @@ async function validateVerifiedBundle(
     verified.bundleDirectory !== bundleDirectory ||
     manifest.runtimeId !== 'opencode' ||
     manifest.provider !== 'opencode' ||
-    manifest.platform !== 'linux' ||
+    (manifest.platform !== 'linux' && !(manifest.platform === 'darwin' && manifest.architecture === 'arm64')) ||
     manifest.architecture !== architecture
   ) {
     throw new Error(

src/main/ssh/ssh-agent-command.test.ts

@@ -214,7 +214,8 @@ describe('fixed Agent SSH commands', () => {
     const cases: Array<
       [Partial<Record<string, string>>, string]
     > = [
-      [{ os: 'Darwin' }, 'non-linux'],
+      [{ os: 'Darwin' }, 'unsupported-architecture'],
+      [{ os: 'FreeBSD' }, 'unsupported-platform'],
       [{ arch: 'riscv64' }, 'unsupported-architecture'],
       [{ home: 'unknown' }, 'home-directory-unavailable'],
       [{ uid: 'unknown' }, 'uid-unavailable'],

src/main/ssh/ssh-agent-command.ts

@@ -129,17 +129,17 @@ export function parseAgentBootstrapProbeOutput(
   }
 
   const os = values.get('os')
-  if (os !== 'Linux') {
-    return incompatible('non-linux')
+  if (os !== 'Linux' && os !== 'Darwin') {
+    return incompatible('unsupported-platform')
   }
   const rawArchitecture = values.get('arch')
   const architecture =
     rawArchitecture === 'x86_64'
       ? 'x64'
-      : rawArchitecture === 'aarch64'
+      : rawArchitecture === 'aarch64' || rawArchitecture === 'arm64'
         ? 'arm64'
         : undefined
-  if (!architecture) {
+  if (!architecture || (os === 'Darwin' && architecture !== 'arm64')) {
     return incompatible('unsupported-architecture')
   }
 
@@ -169,17 +169,17 @@ export function parseAgentBootstrapProbeOutput(
   if (procfs !== 'ready' && procfs !== 'unavailable') {
     throw new Error('Agent 启动探针返回了无效结果')
   }
-  if (procfs === 'unavailable') {
+  if (procfs === 'unavailable' && os === 'Linux') {
     return incompatible('procfs-unavailable')
   }
   return agentBootstrapProbeResultSchema.parse({
     ready: true,
-    platform: 'linux',
+    platform: os === 'Darwin' ? 'darwin' : 'linux',
     architecture,
     canonicalHomeDirectory: home,
     uid,
     shell,
-    procfs: 'ready'
+    procfs: os === 'Darwin' ? 'not-applicable' : 'ready'
   })
 }
 

src/main/ssh/ssh-host-remote-environment.ts

@@ -83,7 +83,7 @@ export type SshHostRemoteEnvironmentInspectorOptions = {
   remoteRuntimeLockPath: string
   loadRemoteEnvironmentCatalog?: (
     architecture: 'x64' | 'arm64',
-    options: { signal?: AbortSignal }
+    options: { signal?: AbortSignal; platform?: 'linux' | 'darwin' }
   ) => Promise<RemoteEnvironmentCatalog>
   now?: () => Date
 }
@@ -155,7 +155,7 @@ export class SshHostRemoteEnvironmentInspector {
         await Promise.all([
           this.#loadRemoteEnvironmentCatalog(
             probe.architecture,
-            { signal }
+            { signal, platform: probe.platform }
           ),
           readOptionalRegistry(
             sftp,

src/main/ssh/ssh-remote-package-bootstrap.test.ts

@@ -503,7 +503,7 @@ describe("fixed SSH remote package bootstrap", () => {
       '--archive-sha256-verified true',
     );
     expect(SSH_REMOTE_PACKAGE_BOOTSTRAP_SCRIPT).toContain(
-      'actual_sha256=$(sha256sum "$archive"',
+      'actual_sha256=$(hash_sha256 "$archive"',
     );
   });
 

src/main/ssh/ssh-remote-package-bootstrap.ts

@@ -127,7 +127,7 @@ export type SshRemotePackageAgentIdentity = {
   agentVersion: string;
   manifestSha256: string;
   binaryDigest: string;
-  platform: "linux";
+  platform: "linux" | "darwin";
   architecture: "x64" | "arm64";
   protocol: SshRemotePackageProtocol;
   supervisor: "detached-on-demand";
@@ -140,7 +140,7 @@ export type SshRemotePackageRuntimeIdentity = {
   manifestDigest: string;
   runtimeAdapterDigest: string;
   acpCapabilitiesDigest: string;
-  platform: "linux";
+  platform: "linux" | "darwin";
   architecture: "x64" | "arm64";
   protocol: SshRemotePackageProtocol;
 };
@@ -614,9 +614,17 @@ if [ "$action" = prepare-uploaded ]; then
   run_prepare
 fi
 command -v curl >/dev/null 2>&1 || stop unavailable missing-curl
-command -v sha256sum >/dev/null 2>&1 || stop unavailable missing-sha256sum
+hash_sha256() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$@"
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$@"
+  else
+    return 1
+  fi
+}
 command -v unzip >/dev/null 2>&1 || stop unavailable missing-unzip
-printf test | sha256sum >/dev/null 2>&1 || stop unavailable missing-sha256sum
+printf test | hash_sha256 >/dev/null 2>&1 || stop unavailable missing-sha256sum
 unzip -v >/dev/null 2>&1 || stop unavailable missing-unzip
 if ! mkdir -p -- "$staging_root"; then stop unavailable managed-path-unavailable; fi
 if [ -L "$goodbuddy_root" ] || [ -L "$managed_root" ] ||
@@ -708,7 +716,7 @@ set -- $actual_size
 actual_size=${SHELL_FIRST_POSITIONAL_OR_EMPTY}
 [ "$actual_size" = "$expected_size" ] || stop failed size-mismatch
 emit_progress verifying
-actual_sha256=$(sha256sum "$archive" 2>/dev/null) || stop failed sha256-mismatch
+actual_sha256=$(hash_sha256 "$archive" 2>/dev/null) || stop failed sha256-mismatch
 set -- $actual_sha256
 actual_sha256=${SHELL_FIRST_POSITIONAL_OR_EMPTY}
 [ "$actual_sha256" = "$expected_sha256" ] || stop failed sha256-mismatch
@@ -973,7 +981,7 @@ function parsePackageIdentity(
     agent.installationId !== `agent-${agent.manifestSha256}` ||
     agent.binaryDigest !== `sha256:${agent.manifestSha256}` ||
     !isVersion(agent.agentVersion) ||
-    agent.platform !== "linux" ||
+    (agent.platform !== "linux" && !(agent.platform === "darwin" && architecture === "arm64")) ||
     (architecture !== "x64" && architecture !== "arm64") ||
     !agentProtocol ||
     agent.supervisor !== "detached-on-demand" ||
@@ -987,7 +995,7 @@ function parsePackageIdentity(
     !DIGEST_PATTERN.test(runtime.runtimeAdapterDigest) ||
     typeof runtime.acpCapabilitiesDigest !== "string" ||
     !DIGEST_PATTERN.test(runtime.acpCapabilitiesDigest) ||
-    runtime.platform !== "linux" ||
+    runtime.platform !== agent.platform ||
     runtime.architecture !== architecture ||
     !runtimeProtocol
   ) {
@@ -1003,7 +1011,7 @@ function parsePackageIdentity(
       agentVersion: agent.agentVersion,
       manifestSha256: agent.manifestSha256,
       binaryDigest: agent.binaryDigest,
-      platform: "linux",
+      platform: agent.platform as "linux" | "darwin",
       architecture,
       protocol: agentProtocol,
       supervisor: "detached-on-demand",
@@ -1015,7 +1023,7 @@ function parsePackageIdentity(
       manifestDigest: runtime.manifestDigest,
       runtimeAdapterDigest: runtime.runtimeAdapterDigest,
       acpCapabilitiesDigest: runtime.acpCapabilitiesDigest,
-      platform: "linux",
+      platform: agent.platform as "linux" | "darwin",
       architecture,
       protocol: runtimeProtocol,
     },

src/preload/index.ts

@@ -450,19 +450,19 @@ const desktopApi: DesktopApi = {
         ipcChannels.sshHostsAgentPackageInventory,
         { refresh }
       ) as Promise<AgentPackageInventory>,
-    downloadAgentPackage: (architecture: AgentArchitecture) =>
+    downloadAgentPackage: (architecture: AgentArchitecture, platform: 'linux' | 'darwin' = 'linux') =>
       ipcRenderer.invoke(
         ipcChannels.sshHostsAgentPackageDownload,
-        { architecture }
+        { architecture, platform }
       ) as Promise<AgentPackageInventory>,
     importAgentPackage: () =>
       ipcRenderer.invoke(
         ipcChannels.sshHostsAgentPackageImport
       ) as Promise<AgentPackageInventory | undefined>,
-    exportAgentPackage: async (architecture: AgentArchitecture) => {
+    exportAgentPackage: async (architecture: AgentArchitecture, platform: 'linux' | 'darwin' = 'linux') => {
       await ipcRenderer.invoke(
         ipcChannels.sshHostsAgentPackageExport,
-        { architecture }
+        { architecture, platform }
       )
     },
     onAgentPackageProgress: (listener) => {

src/renderer/src/PlatformFeaturesSettingsSection.tsx

@@ -109,7 +109,7 @@ export function PlatformFeaturesSettingsSection({
   const [agentInventoryError, setAgentInventoryError] =
     useState<string>()
   const [agentPackageBusy, setAgentPackageBusy] =
-    useState<AgentArchitecture | 'import'>()
+    useState<string>()
   const [agentPackageProgress, setAgentPackageProgress] =
     useState<AgentPackageDownloadProgress>()
   const agentInventoryRequested = useRef(false)
@@ -195,23 +195,24 @@ export function PlatformFeaturesSettingsSection({
   }, [])
 
   const downloadAgentPackage = async (
-    architecture: AgentArchitecture
+    architecture: AgentArchitecture,
+    platform: 'linux' | 'darwin'
   ): Promise<void> => {
     const download =
       window.goodbuddy.sshHosts?.downloadAgentPackage
     if (!download) {
       return
     }
-    setAgentPackageBusy(architecture)
+    setAgentPackageBusy(`${platform}-${architecture}`)
     setAgentPackageProgress(undefined)
     setAgentInventoryError(undefined)
     try {
-      setAgentInventory(await download(architecture))
+      setAgentInventory(await download(architecture, platform))
       onNotify?.({
-        dedupeKey: `agent-package-downloaded:${architecture}`,
+        dedupeKey: `agent-package-downloaded:${platform}-${architecture}`,
         message: t(
           'platformFeatures.remoteProjects.agentInventory.notifications.downloaded',
-          { architecture }
+          { architecture, platform: platform === 'darwin' ? 'macOS' : 'Linux' }
         ),
         tone: 'success'
       })
@@ -265,22 +266,23 @@ export function PlatformFeaturesSettingsSection({
   }
 
   const exportAgentPackage = async (
-    architecture: AgentArchitecture
+    architecture: AgentArchitecture,
+    platform: 'linux' | 'darwin'
   ): Promise<void> => {
     const exportPackage =
       window.goodbuddy.sshHosts?.exportAgentPackage
     if (!exportPackage) {
       return
     }
-    setAgentPackageBusy(architecture)
+    setAgentPackageBusy(`${platform}-${architecture}`)
     setAgentInventoryError(undefined)
     try {
-      await exportPackage(architecture)
+      await exportPackage(architecture, platform)
       onNotify?.({
-        dedupeKey: `agent-package-exported:${architecture}`,
+        dedupeKey: `agent-package-exported:${platform}-${architecture}`,
         message: t(
           'platformFeatures.remoteProjects.agentInventory.notifications.exported',
-          { architecture }
+          { architecture, platform: platform === 'darwin' ? 'macOS' : 'Linux' }
         ),
         tone: 'success'
       })
@@ -983,13 +985,13 @@ export function PlatformFeaturesSettingsSection({
               {agentInventory.entries.map((entry) => (
                 <article
                   className="bundled-agent-inventory__item"
-                  key={entry.architecture}
+                  key={`${entry.platform}-${entry.architecture}`}
                   role="listitem"
                 >
                   <div className="bundled-agent-inventory__item-header">
                     <Cpu aria-hidden="true" size={16} />
                     <strong>
-                      Linux {entry.architecture}
+                      {entry.platform === 'darwin' ? 'macOS' : 'Linux'} {entry.architecture}
                     </strong>
                     <span
                       className={`bundled-agent-inventory__badge bundled-agent-inventory__badge--${
@@ -1063,7 +1065,8 @@ export function PlatformFeaturesSettingsSection({
                   </dl>
                   {agentPackageProgress?.architecture ===
                     entry.architecture &&
-                    agentPackageBusy === entry.architecture && (
+                    agentPackageProgress.platform === entry.platform &&
+                    agentPackageBusy === `${entry.platform}-${entry.architecture}` && (
                       <p className="settings-notice" role="status">
                         {t(
                           `platformFeatures.remoteProjects.agentInventory.progress.${agentPackageProgress.phase}`
@@ -1084,7 +1087,8 @@ export function PlatformFeaturesSettingsSection({
                         disabled={agentPackageBusy !== undefined}
                         onClick={() =>
                           void downloadAgentPackage(
-                            entry.architecture
+                            entry.architecture,
+                            entry.platform
                           )
                         }
                         type="button"
@@ -1107,7 +1111,8 @@ export function PlatformFeaturesSettingsSection({
                         disabled={agentPackageBusy !== undefined}
                         onClick={() =>
                           void exportAgentPackage(
-                            entry.architecture
+                            entry.architecture,
+                            entry.platform
                           )
                         }
                         type="button"

src/renderer/src/SettingsPanel.test.tsx

@@ -2149,7 +2149,7 @@ describe('SettingsPanel runtime files', () => {
       await screen.findByText('GoodBuddy Agent 包')
     ).toBeInTheDocument()
     expect(
-      screen.getByText('当前 1 / 2 个 Linux 架构可用。')
+      screen.getByText('当前 1 / 2 个平台与架构目标可用。')
     ).toBeInTheDocument()
     expect(screen.getByText('Linux x64')).toBeInTheDocument()
     expect(screen.getByText('Linux arm64')).toBeInTheDocument()
@@ -2192,7 +2192,7 @@ describe('SettingsPanel runtime files', () => {
       })
     )
     await waitFor(() =>
-      expect(downloadAgentPackage).toHaveBeenCalledWith('x64')
+      expect(downloadAgentPackage).toHaveBeenCalledWith('x64', 'linux')
     )
     expect(
       await within(x64Card as HTMLElement).findByText('已是最新')
@@ -2208,7 +2208,7 @@ describe('SettingsPanel runtime files', () => {
       })
     )
     await waitFor(() =>
-      expect(exportAgentPackage).toHaveBeenCalledWith('x64')
+      expect(exportAgentPackage).toHaveBeenCalledWith('x64', 'linux')
     )
     fireEvent.click(
       within(arm64Card as HTMLElement).getByRole('button', {
@@ -2216,7 +2216,7 @@ describe('SettingsPanel runtime files', () => {
       })
     )
     await waitFor(() =>
-      expect(downloadAgentPackage).toHaveBeenCalledWith('arm64')
+      expect(downloadAgentPackage).toHaveBeenCalledWith('arm64', 'linux')
     )
     fireEvent.click(
       screen.getByRole('button', { name: '导入离线包' })
@@ -2272,7 +2272,7 @@ describe('SettingsPanel runtime files', () => {
       await Promise.resolve()
     })
     expect(
-      await screen.findByText('当前 1 / 2 个 Linux 架构可用。')
+      await screen.findByText('当前 1 / 2 个平台与架构目标可用。')
     ).toBeInTheDocument()
 
     getAgentPackageInventory.mockRejectedValueOnce(

src/renderer/src/i18n/locales/en-US/settingsSections.ts

@@ -585,7 +585,7 @@ export const settingsSections = {
         downloadVersion: 'Download {{version}}',
         listLabel: 'Local Agent package inventory',
         summary:
-          '{{available}} of {{total}} Linux architectures are available.',
+          '{{available}} of {{total}} platform and architecture targets are available.',
         states: {
           verified: 'Downloaded and verified',
           'not-downloaded': 'Not downloaded',
@@ -613,9 +613,9 @@ export const settingsSections = {
           installing: 'Writing the local cache…'
         },
         notifications: {
-          downloaded: 'Linux {{architecture}} Agent package updated',
+          downloaded: '{{platform}} {{architecture}} Agent package updated',
           imported: 'Agent offline package imported and verified',
-          exported: 'Linux {{architecture}} Agent package exported'
+          exported: '{{platform}} {{architecture}} Agent package exported'
         },
         errors: {
           unavailable:

src/renderer/src/i18n/locales/zh-CN/settingsSections.ts

@@ -554,7 +554,7 @@ export const settingsSections = {
         updateTo: '更新到 {{version}}',
         downloadVersion: '下载 {{version}}',
         listLabel: '本地 Agent 包清单',
-        summary: '当前 {{available}} / {{total}} 个 Linux 架构可用。',
+        summary: '当前 {{available}} / {{total}} 个平台与架构目标可用。',
         states: {
           verified: '已下载并验证',
           'not-downloaded': '未下载',
@@ -582,9 +582,9 @@ export const settingsSections = {
           installing: '正在写入本地缓存…'
         },
         notifications: {
-          downloaded: 'Linux {{architecture}} Agent 包已更新',
+          downloaded: '{{platform}} {{architecture}} Agent 包已更新',
           imported: 'Agent 离线包已导入并验证',
-          exported: 'Linux {{architecture}} Agent 包已导出'
+          exported: '{{platform}} {{architecture}} Agent 包已导出'
         },
         errors: {
           unavailable: '当前版本未提供 Agent 包管理服务',

src/shared/agent-installation-contracts.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { agentPlatformSchema } from './agent-target'
 
 const versionPattern =
   /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+((?:[0-9a-zA-Z-]+)(?:\.[0-9a-zA-Z-]+)*))?$/u
@@ -81,7 +82,7 @@ export const agentBundleManifestSchema = z
     formatVersion: z.literal(1),
     product: z.literal('GoodBuddy'),
     agentVersion: componentVersionSchema,
-    platform: z.literal('linux'),
+    platform: agentPlatformSchema,
     arch: agentArchitectureSchema,
     protocol: agentProtocolVersionSchema,
     signingKeyId: z.string().regex(keyIdPattern),
@@ -248,7 +249,8 @@ export const agentRuntimeLockSchema = z
         targets: z
           .object({
             'linux-x64': lockedNodeTargetSchema,
-            'linux-arm64': lockedNodeTargetSchema
+            'linux-arm64': lockedNodeTargetSchema,
+            'darwin-arm64': lockedNodeTargetSchema.optional()
           })
           .strict()
       })

src/shared/agent-package-contracts.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import {
   agentPackageArchiveName,
   agentPackageCatalogEntrySchema,
+  agentPackageCatalogSchema,
   agentPackageInventoryRequestSchema,
   agentPackageInventorySchema,
   isSafeAgentPackagePath
@@ -48,6 +49,27 @@ function catalogEntry() {
 }
 
 describe('Agent package contracts', () => {
+  it('accepts Linux and macOS arm64 independently in one signed catalog', () => {
+    const linux = {
+      ...catalogEntry(),
+      architecture: 'arm64',
+      archive: agentPackageArchiveName('0.11.2', 'arm64', 'linux')
+    }
+    const mac = {
+      ...linux,
+      platform: 'darwin',
+      archive: agentPackageArchiveName('0.11.2', 'arm64', 'darwin')
+    }
+    const catalog = agentPackageCatalogSchema.parse({
+      formatVersion: 1, product: 'GoodBuddy', component: 'agent',
+      signingKeyId: 'test', generatedAt: '2026-09-06T00:00:00.000Z',
+      entries: [catalogEntry(), linux, mac]
+    })
+    expect(catalog.entries).toHaveLength(3)
+    expect(() => agentPackageCatalogSchema.parse({
+      ...catalog, entries: [...catalog.entries, mac]
+    })).toThrow('duplicate')
+  })
   it('binds each catalog archive name to its signed identity', () => {
     expect(agentPackageCatalogEntrySchema.parse(catalogEntry()))
       .toMatchObject({

src/shared/agent-package-contracts.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { agentPlatformSchema, agentTargetKey, type AgentPlatform } from './agent-target'
 import {
   agentArchitectureSchema,
   agentProtocolVersionSchema
@@ -9,9 +10,10 @@ export const AGENT_PACKAGE_FORMAT_VERSION = 1
 
 export function agentPackageArchiveName(
   version: string,
-  architecture: 'x64' | 'arm64'
+  architecture: 'x64' | 'arm64',
+  platform: AgentPlatform = 'linux'
 ): string {
-  return `goodbuddy-agent-${version}-linux-${architecture}.gbagent`
+  return `goodbuddy-agent-${version}-${agentTargetKey({ platform, architecture })}.gbagent`
 }
 
 const semanticVersionSchema = z
@@ -31,7 +33,7 @@ const safeArchiveNameSchema = z
   .min(1)
   .max(255)
   .regex(
-    /^goodbuddy-agent-(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?-linux-(?:x64|arm64)\.gbagent$/u
+    /^goodbuddy-agent-(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?-(?:linux-(?:x64|arm64)|darwin-arm64)\.gbagent$/u
   )
 
 const windowsReservedNamePattern =
@@ -86,7 +88,7 @@ const agentPackageDescriptorObjectSchema = z
     component: z.literal('agent'),
     version: semanticVersionSchema,
     minimumDesktopVersion: semanticVersionSchema,
-    platform: z.literal('linux'),
+    platform: agentPlatformSchema,
     architecture: agentArchitectureSchema,
     signingKeyId: signingKeyIdSchema,
     agentProtocol: agentProtocolVersionSchema,
@@ -152,7 +154,7 @@ export const agentPackageCatalogEntrySchema =
     .superRefine((entry, context) => {
       if (
         entry.archive !==
-        agentPackageArchiveName(entry.version, entry.architecture)
+        agentPackageArchiveName(entry.version, entry.architecture, entry.platform)
       ) {
         context.addIssue({
           code: 'custom',
@@ -182,7 +184,7 @@ export const agentPackageCatalogSchema = z
   .strict()
   .superRefine((catalog, context) => {
     const identities = catalog.entries.map(
-      (entry) => `${entry.version}:${entry.architecture}`
+      (entry) => `${entry.version}:${entry.platform}:${entry.architecture}`
     )
     if (new Set(identities).size !== identities.length) {
       context.addIssue({
@@ -205,7 +207,7 @@ export const agentPackageStateSchema = z.enum([
 
 export const agentPackageInventoryEntrySchema = z
   .object({
-    platform: z.literal('linux'),
+    platform: agentPlatformSchema,
     architecture: agentArchitectureSchema,
     state: agentPackageStateSchema,
     version: semanticVersionSchema.nullable(),
@@ -247,12 +249,12 @@ export const agentPackageInventorySchema = z
     catalog: agentPackageCatalogStatusSchema,
     entries: z
       .array(agentPackageInventoryEntrySchema)
-      .length(agentArchitectureSchema.options.length)
+      .min(1).max(3)
   })
   .strict()
   .superRefine((inventory, context) => {
     const architectures = inventory.entries.map(
-      (entry) => entry.architecture
+      (entry) => `${entry.platform}-${entry.architecture}`
     )
     if (new Set(architectures).size !== architectures.length) {
       context.addIssue({
@@ -276,7 +278,8 @@ export const agentPackageInventoryRequestSchema = z
 
 export const agentPackageArchitectureRequestSchema = z
   .object({
-    architecture: agentArchitectureSchema
+    architecture: agentArchitectureSchema,
+    platform: agentPlatformSchema.default('linux')
   })
   .strict()
 
@@ -287,6 +290,7 @@ export type AgentPackageArchitectureRequest = z.infer<
 export const agentPackageDownloadProgressSchema = z
   .object({
     architecture: agentArchitectureSchema,
+    platform: agentPlatformSchema.default('linux'),
     phase: z.enum([
       'catalog',
       'downloading',

src/shared/agent-protocol/control-contracts.ts

@@ -190,7 +190,7 @@ export const daemonStatusSchema = z
       label: 'Agent version'
     }),
     protocol: protocolVersionSchema,
-    platform: z.literal('linux'),
+    platform: z.enum(['linux', 'darwin']),
     architecture: z.enum(['x64', 'arm64']),
     supervisor: z.literal('detached-on-demand'),
     remoteUserIdentity: agentIdentifierSchema,

src/shared/agent-target.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod'
+
+export const agentPlatformSchema = z.enum(['linux', 'darwin'])
+export type AgentPlatform = z.infer<typeof agentPlatformSchema>
+
+export const AGENT_TARGETS = [
+  { platform: 'linux', architecture: 'x64' },
+  { platform: 'linux', architecture: 'arm64' },
+  { platform: 'darwin', architecture: 'arm64' }
+] as const
+
+export type AgentTarget = (typeof AGENT_TARGETS)[number]
+export type AgentTargetKey = 'linux-x64' | 'linux-arm64' | 'darwin-arm64'
+
+export function agentTargetKey(target: {
+  platform: string
+  architecture: string
+}): AgentTargetKey {
+  if (!AGENT_TARGETS.some(entry =>
+    entry.platform === target.platform && entry.architecture === target.architecture
+  )) throw new Error(`Unsupported Agent target: ${target.platform}-${target.architecture}`)
+  return `${target.platform}-${target.architecture}` as AgentTargetKey
+}
+
+export function currentAgentPlatform(): AgentPlatform {
+  const platform = agentPlatformSchema.parse(process.platform)
+  agentTargetKey({ platform, architecture: process.arch })
+  return platform
+}

src/shared/contracts.ts

@@ -1660,11 +1660,13 @@ export type DesktopApi = {
       refresh?: boolean
     ) => Promise<AgentPackageInventory>
     downloadAgentPackage: (
-      architecture: AgentArchitecture
+      architecture: AgentArchitecture,
+      platform?: 'linux' | 'darwin'
     ) => Promise<AgentPackageInventory>
     importAgentPackage: () => Promise<AgentPackageInventory | undefined>
     exportAgentPackage: (
-      architecture: AgentArchitecture
+      architecture: AgentArchitecture,
+      platform?: 'linux' | 'darwin'
     ) => Promise<void>
     onAgentPackageProgress: (
       listener: (progress: AgentPackageDownloadProgress) => void

src/shared/node/binary-target.ts

@@ -0,0 +1,22 @@
+import type { AgentArchitecture } from '../agent-installation-contracts'
+import type { AgentPlatform } from '../agent-target'
+
+export function binaryTargetArchitecture(
+  bytes: Buffer,
+  platform: AgentPlatform
+): AgentArchitecture | undefined {
+  if (platform === 'darwin') {
+    if (bytes.length < 8) return undefined
+    const cpu = bytes.readUInt32LE(0) === 0xfeedfacf
+      ? bytes.readUInt32LE(4)
+      : bytes.readUInt32BE(0) === 0xfeedfacf ? bytes.readUInt32BE(4) : undefined
+    return cpu === 0x0100000c ? 'arm64' : undefined
+  }
+  if (
+    bytes.length < 20 || bytes[0] !== 0x7f ||
+    bytes.toString('ascii', 1, 4) !== 'ELF' ||
+    ![1, 2].includes(bytes[5]!)
+  ) return undefined
+  const machine = bytes[5] === 2 ? bytes.readUInt16BE(18) : bytes.readUInt16LE(18)
+  return machine === 62 ? 'x64' : machine === 183 ? 'arm64' : undefined
+}

src/shared/node/runtime-bundle-verifier.ts

@@ -1,3 +1,5 @@
+import { binaryTargetArchitecture } from './binary-target'
+import type { AgentPlatform } from '../agent-target'
 import {
   createHash,
   createPublicKey,
@@ -219,7 +221,8 @@ export async function verifyPublishedRuntimeBundle(
   await assertElfArchitecture(
     executablePath,
     options.architecture,
-    'Runtime executable'
+    'Runtime executable',
+    manifest.platform
   )
   return {
     bundleDirectory,
@@ -412,8 +415,11 @@ export function assertRuntimeManifestMatchesLock(
   architecture: AgentArchitecture
 ): void {
   const expected = lock.runtimes.opencode
-  const target = expected.targets[architecture]
+  const target = manifest.platform === 'darwin'
+    ? expected.targets['darwin-arm64']
+    : expected.targets[architecture]
   if (
+    target === undefined ||
     manifest.runtimeId !== 'opencode' ||
     manifest.provider !== expected.provider ||
     manifest.runtimeVersion !== expected.version ||
@@ -696,7 +702,8 @@ async function sha256File(filePath: string): Promise<string> {
 async function assertElfArchitecture(
   filePath: string,
   expected: AgentArchitecture,
-  label: string
+  label: string,
+  platform: AgentPlatform
 ): Promise<void> {
   const handle = await open(filePath, 'r')
   try {
@@ -707,8 +714,8 @@ 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(
@@ -718,26 +725,4 @@ async function assertElfArchitecture(
   } finally {
     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/shared/remote-runtime-launch-contracts.ts

@@ -118,7 +118,7 @@ const remoteRuntimeManifestFields = {
     runtimeId: agentIdentifierSchema,
     runtimeVersion: agentBundleManifestSchema.shape.agentVersion,
     provider: remoteRuntimeProviderKindSchema,
-    platform: z.literal('linux'),
+    platform: z.enum(['linux', 'darwin']),
     architecture: agentArchitectureSchema,
     signingKeyId: agentReleaseKeySchema.shape.keyId,
     bundleDigest: sha256DigestSchema,
@@ -252,7 +252,10 @@ export const remoteRuntimeLockSchema = z
                 }),
                 arm64: remoteRuntimeLockedTargetSchema.extend({
                   package: z.literal('opencode-linux-arm64')
-                })
+                }),
+                'darwin-arm64': remoteRuntimeLockedTargetSchema.extend({
+                  package: z.literal('opencode-darwin-arm64')
+                }).optional()
               })
               .strict()
           })

src/shared/ssh-host-contracts.ts

@@ -404,6 +404,7 @@ export type RemoteEnvironmentUpdateProgress = z.infer<
 
 export const agentBootstrapIncompatibleReasonSchema = z.enum([
   'non-linux',
+  'unsupported-platform',
   'unsupported-architecture',
   'home-directory-unavailable',
   'uid-unavailable',
@@ -562,12 +563,12 @@ export const agentBootstrapProbeResultSchema = z.discriminatedUnion(
     z
       .object({
         ready: z.literal(true),
-        platform: z.literal('linux'),
+        platform: z.enum(['linux', 'darwin']),
         architecture: z.enum(['x64', 'arm64']),
         canonicalHomeDirectory: canonicalRemotePathSchema,
         uid: z.number().int().min(0).max(4_294_967_294),
         shell: canonicalRemotePathSchema,
-        procfs: z.literal('ready')
+        procfs: z.enum(['ready', 'not-applicable'])
       })
       .strict(),
     z