@hellolynk-ai/workbuddy-mcp 0.3.98 → 0.3.100

package/bin/hellolynk-client-setup.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import crypto from "node:crypto";
-import { lstatSync, realpathSync, writeSync } from "node:fs";
+import { constants, lstatSync, realpathSync, writeSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -16,11 +16,14 @@ const PACK_PIN = "hellolynk-client-pack-pin.json";
 
 // A person at a terminal reads sentences in the system language; the updater, tests and other
 // programs read one JSON line.
-const jsonOutput = process.argv.includes("--json") || process.stdout.isTTY !== true;
+const explicitJson = process.argv.includes("--json");
+const jsonOutput = explicitJson || process.stdout.isTTY !== true;
 const CHINESE = /^zh\b/i.test(Intl.DateTimeFormat().resolvedOptions().locale);
 const CLIENT_NAMES = Object.freeze({ codex: "Codex", openclaw: "OpenClaw", "trae-work": "TRAE Work",
   workbuddy: "WorkBuddy", cursor: "Cursor", dsh: "DSH" });
 const { packageJson, metadata } = await readPackage();
+const macPackage = metadata.client === "codex" && packageJson.os?.[0] === "darwin"
+  && packageJson.cpu?.[0] === "arm64";
 const commandArguments = process.argv.slice(2).filter((value) => value !== "--json");
 const command = String(commandArguments.shift() || "help").toLowerCase();
 const waitForPending = command === "--wait-for-pending";
@@ -61,8 +64,14 @@ try {
       "--expected-manifest-sha256", sourceRelease.outerManifestSha256,
     ]);
   } else {
-  const originalLocations = resolveLocations();
   const accountModule = await importStableCore(PACKAGE_ROOT, "hellolynk-client-account.mjs", "hellolynk_npm_account_runtime_invalid");
+  const originalLocations = resolveLocations(accountModule.clientAccountBaseRoot);
+  if (macPackage && command !== "uninstall") {
+    const config = await readJson(path.join(sourceReleaseRoot, ".mcp.json"), "hellolynk_npm_release_invalid", true);
+    const commandPath = config.mcpServers?.["hellolynk-codex"]?.command;
+    if (typeof commandPath !== "string" || !path.isAbsolute(commandPath)) fail("hellolynk_npm_release_invalid");
+    await fs.access(commandPath, constants.X_OK).catch(() => fail("hellolynk_npm_codex_mac_node_required"));
+  }
   const baseRoot = accountModule.clientAccountBaseRoot(originalLocations.hostRoot);
   const packageLocations = { ...originalLocations, hostRoot: baseRoot, finalCurrentRoot: path.dirname(baseRoot) };
   const accounts = accountModule.createClientAccountActions({ client: metadata.client, storeRoot: baseRoot });
@@ -250,6 +259,10 @@ try {
       await verifyExactBinding({ ...installed, locations, activation });
       await verifyClientConfiguration({ ...installed, locations });
     }
+    // A running unsigned updater asks the stable package for implicit JSON. A
+    // staged package may still prove its own first install after lost stdout.
+    const legacyUpdateProof = installed && !existingDoctor && !explicitJson && jsonOutput
+      && process.env.HELLOLYNK_NEUTRAL_STORE_ROOT && samePath(PACKAGE_ROOT, installed.packageRoot);
     print({
       ok: true,
       client: metadata.client,
@@ -260,7 +273,7 @@ try {
       activated: activation.ready,
       activationState: activation.state,
       stableReleaseVerified: installed != null,
-      exactBindingVerified: installed != null,
+      ...(legacyUpdateProof ? {} : { exactBindingVerified: installed != null }),
       clientConfigurationVerified: installed != null,
       installsNode: false,
       installsGit: false,
@@ -429,7 +442,8 @@ async function uninstallClient(locations) {
     if (receiverConfigured) await receiver.configureTraeNativeTaskWorker({ storeRoot: locations.hostRoot, enabled: false });
   }
   // A binding names the release it starts, so it cannot outlive the releases removed below.
-  if (await exists(path.join(locations.hostRoot, "capabilities-v1.dpapi.clixml"))) {
+  const protectedFile = macPackage ? "protected-v1.sqlite" : "capabilities-v1.dpapi.clixml";
+  if (await exists(path.join(locations.hostRoot, protectedFile))) {
     const store = await importStableCore(PACKAGE_ROOT, "hellolynk-host-protected-store.mjs", "hellolynk_npm_binding_invalid");
     await store.createHostProtectedStore({ root: locations.hostRoot, followClientAccount: false }).disconnectLocalClient(metadata.client);
   }
@@ -838,17 +852,20 @@ async function verifyRelease(releaseRoot, packageRoot, expectedMetadata = metada
   return Object.freeze({ manifestSha256, outerManifestSha256 });
 }
 
-function resolveLocations() {
-  if (process.platform !== "win32") fail("hellolynk_npm_windows_only");
-  const home = path.resolve(process.env.USERPROFILE || os.homedir());
-  const localAppData = path.resolve(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"));
-  const appData = path.resolve(process.env.APPDATA || path.join(home, "AppData", "Roaming"));
+function resolveLocations(getDefaultHostRoot) {
+  if (macPackage) {
+    if (process.platform !== "darwin" || process.arch !== "arm64") fail("hellolynk_npm_platform_unsupported");
+  } else if (process.platform !== "win32") fail("hellolynk_npm_windows_only");
+  const home = path.resolve((macPackage ? process.env.HOME : process.env.USERPROFILE) || os.homedir());
+  const localAppData = macPackage ? path.join(home, "Library", "Application Support")
+    : path.resolve(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"));
+  const appData = macPackage ? localAppData : path.resolve(process.env.APPDATA || path.join(home, "AppData", "Roaming"));
   const configuredCodexHome = String(process.env.CODEX_HOME || "");
   if (configuredCodexHome && !path.isAbsolute(configuredCodexHome)) fail("hellolynk_npm_codex_home_invalid");
   const codexHome = path.resolve(configuredCodexHome || path.join(home, ".codex"));
   const configuredHostRoot = String(process.env.HELLOLYNK_NEUTRAL_STORE_ROOT || "").trim();
   if (configuredHostRoot && !path.isAbsolute(configuredHostRoot)) fail("hellolynk_npm_store_root_invalid");
-  const hostRoot = path.resolve(configuredHostRoot || path.join(localAppData, "HelloLynk", "host"));
+  const hostRoot = path.resolve(configuredHostRoot || getDefaultHostRoot());
   if (configuredHostRoot && path.basename(hostRoot).toLowerCase() !== "host") {
     fail("hellolynk_npm_store_root_invalid");
   }
@@ -1004,6 +1021,12 @@ async function startHostWhenAbsent(runtime, binding) {
 }
 
 async function secureStableReleaseTree(locations, releaseId, options = {}) {
+  const releasePath = path.resolve(locations.finalCurrentRoot, "releases", releaseId);
+  // An existing AppData root can be shared while a new release is redirected
+  // into one desktop app's private cache. Other clients cannot use that release.
+  if (process.platform === "win32" && realpathSync.native(releasePath).toLowerCase() !== releasePath.toLowerCase()) {
+    fail("client_root_alias_rejected");
+  }
   const module = await importCore(
     "hellolynk-platform-credential-store.mjs",
     "hellolynk_npm_client_root_security_unavailable",
@@ -2246,6 +2269,13 @@ function runCodexJson(args, code, codexHome) {
 }
 
 function minimalEnv({ codexHome = null } = {}) {
+  if (macPackage) return Object.freeze({
+    PATH: process.env.PATH || "/usr/bin:/bin",
+    HOME: process.env.HOME || os.homedir(),
+    TMPDIR: process.env.TMPDIR || os.tmpdir(),
+    LANG: process.env.LANG || "en_US.UTF-8",
+    ...(codexHome ? { CODEX_HOME: codexHome } : {}),
+  });
   return Object.freeze({
     PATH: process.env.Path || process.env.PATH || "",
     PATHEXT: process.env.PATHEXT || "",
@@ -2261,13 +2291,18 @@ function minimalEnv({ codexHome = null } = {}) {
 
 function resolveCodexRunner(codexHome) {
   if (resolvedCodexRunner) return resolvedCodexRunner;
-  const searchPath = String(process.env.Path || process.env.PATH || "");
+  const searchPath = String((macPackage ? process.env.PATH : process.env.Path || process.env.PATH) || "");
   let sawLoaderCandidate = false;
   let sawNativeCandidate = false;
   for (const rawEntry of searchPath.split(path.delimiter)) {
     try {
       const logical = rawEntry.trim().replace(/^"(.*)"$/, "$1");
       if (!logical || !path.isAbsolute(logical)) continue;
+      if (macPackage) {
+        const runner = probeMacCodex(path.join(logical, "codex"), codexHome);
+        if (runner) return (resolvedCodexRunner = runner);
+        continue;
+      }
       // nvm/fnm and user profile mappings can put a junction on PATH. Resolve
       // that directory once, then retain the ordinary-file checks below it.
       const entry = realpathSync(path.resolve(logical));
@@ -2321,6 +2356,15 @@ function resolveCodexRunner(codexHome) {
 }
 
 function resolveCodexDesktopRunner(codexHome) {
+  if (macPackage) {
+    for (const directory of ["/Applications", path.join(os.homedir(), "Applications")]) {
+      for (const app of ["ChatGPT.app", "Codex.app"]) {
+        const runner = probeMacCodex(path.join(directory, app, "Contents", "Resources", "codex"), codexHome);
+        if (runner) return runner;
+      }
+    }
+    return null;
+  }
   if (process.platform !== "win32") return null;
   const systemRoot = process.env.SystemRoot || process.env.SYSTEMROOT;
   if (!systemRoot || !path.isAbsolute(systemRoot)) return null;
@@ -2348,6 +2392,22 @@ function resolveCodexDesktopRunner(codexHome) {
   return null;
 }
 
+function probeMacCodex(logicalPath, codexHome) {
+  // npm and Homebrew commonly expose a symlink. Execute the canonical file directly.
+  try {
+    const command = realpathSync(logicalPath);
+    const metadata = lstatSync(command);
+    if (!metadata.isFile() || !(metadata.mode & 0o111)) return null;
+    const result = spawnSync(command, ["--version"], {
+      encoding: "utf8", shell: false, timeout: 5000, env: minimalEnv({ codexHome }),
+    });
+    if (result.status === 0 && /^codex-cli\s+\d+\.\d+\.\d+/u.test(String(result.stdout || "").trim())) {
+      return Object.freeze({ command, argsPrefix: Object.freeze([]), kind: "native" });
+    }
+  } catch { /* Missing or unusable CLI. */ }
+  return null;
+}
+
 function resolveRegularDescendantSync(anchor, anchorRealPath, segments) {
   let observed = anchor;
   for (let index = 0; index < segments.length; index += 1) {
@@ -2527,6 +2587,7 @@ function samePath(left, right) {
     const resolved = normalizeWindowsNamespacePath(value);
     let canonical = resolved;
     try { canonical = realpathSync(resolved); } catch { /* comparison can still reject a missing path */ }
+    if (macPackage) return canonical;
     return normalizeWindowsNamespacePath(canonical).replace(/[\\/]+$/u, "").toLowerCase();
   };
   return normalize(left) === normalize(right);
@@ -2646,7 +2707,9 @@ function helpText() {
     : [[say("安装", "Install"), "init"], [say("连接账号", "Connect an account"), connect],
       [say("更新或修复", "Update or repair"), "setup"], [say("检查", "Check"), "doctor"],
       [say("卸载", "Uninstall"), "uninstall"]];
-  return `${[`HelloLynk for ${CLIENT_NAMES[metadata.client]}${say("（Windows，Node.js 22.16.0+）", " (Windows, Node.js 22.16.0+)")}`,
+  const platform = macPackage ? " (macOS arm64, Node.js 22.16.0+)"
+    : say("（Windows，Node.js 22.16.0+）", " (Windows, Node.js 22.16.0+)");
+  return `${[`HelloLynk for ${CLIENT_NAMES[metadata.client]}${platform}`,
     ...rows.map(([label, args]) => `${label}${say("：", ": ")}${run} ${args}`),
     say("加 --json 输出一行 JSON。", "Add --json for one line of JSON.")].join("\n")}\n`;
 }
@@ -2720,6 +2783,9 @@ function failureText(failure) {
 function failureReason(code, name) {
   if (code === "hellolynk_node_22_16_required") return say("需要 Node.js 22.16 或更高版本。", "Node.js 22.16 or later is required.");
   if (code === "hellolynk_npm_windows_only") return say("只支持 Windows。", "Windows only.");
+  if (code === "hellolynk_npm_platform_unsupported") return say("此安装包适用于 Apple 芯片的 Mac。", "This package requires an Apple silicon Mac.");
+  if (code === "hellolynk_npm_codex_mac_node_required") return say("请将 ChatGPT 安装到「应用程序」，打开 Codex 后再试。",
+    "Install ChatGPT in Applications, open Codex, and try again.");
   if (code === "hellolynk_npm_connect_id_invalid") {
     return say("灵信号不对。请从官网复制从 hellolynk: 开始的完整灵信号。",
       "This HelloLynk ID is not valid. Copy the complete ID, starting with hellolynk:, from the website.");

package/clients/core/hellolynk-client-account.mjs

@@ -68,7 +68,7 @@ export function withClientAccountLock(client, root, operation) {
 
 export function createClientAccountActions(options) {
   const client = options?.client;
-  const root = options?.storeRoot || defaultNeutralHostStoreRoot("win32", options?.env || process.env);
+  const root = options?.storeRoot || defaultNeutralHostStoreRoot(process.platform, options?.env || process.env);
   statePath(client, clientAccountBaseRoot(root));
   const readAccountState = () => {
     const state = readClientAccount(client, root);

package/clients/core/hellolynk-client-profile.mjs

@@ -1,4 +1,5 @@
 import { lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -19,12 +20,34 @@ const SAFE_SCOPE = /^[a-z][a-z0-9_.:-]{0,127}$/;
 const MAX_PROFILE_BYTES = 64 * 1024;
 
 export function defaultHelloLynkClientRoot(platform = process.platform, env = process.env) {
-  const home = resolve(String(env.HOME || env.USERPROFILE || homedir()));
-  if (platform === "win32") return resolve(String(env.LOCALAPPDATA || join(home, "AppData", "Local")), "HelloLynk");
+  const home = resolve(String((platform === "win32" ? env.USERPROFILE || env.HOME : env.HOME || env.USERPROFILE) || homedir()));
+  if (platform === "win32") {
+    const current = join(home, ".hellolynk", "hellolynk-v2");
+    // Once selected, another client's older installer must not move us back.
+    if (hasWindowsClientInstallation(current)) return current;
+    const existing = resolve(String(env.LOCALAPPDATA || join(home, "AppData", "Local")), "HelloLynk");
+    // AppData created from a packaged desktop app can be private to that app.
+    // Keep an existing installation; an empty failed setup is not an account.
+    if (hasWindowsClientInstallation(existing)) return existing;
+    return current;
+  }
   if (platform === "darwin") return join(home, "Library", "Application Support", "HelloLynk");
   return resolve(String(env.XDG_DATA_HOME || join(home, ".local", "share")), "hellolynk");
 }
 
+function hasWindowsClientInstallation(root) {
+  for (const directory of ["profiles", "releases", "host", "credentials", "e2ee-private-keys"]) {
+    try {
+      const entries = readdirSync(join(root, directory), { withFileTypes: true });
+      if (entries.some((entry) => directory !== "host" || entry.name !== "runtime")) return true;
+    } catch (error) {
+      // An unreadable existing location must not silently become a fresh account.
+      if (error.code !== "ENOENT") return true;
+    }
+  }
+  return false;
+}
+
 function safeId(value, code) {
   const normalized = String(value || "").trim();
   if (!SAFE_ID.test(normalized)) throw new Error(code);

package/clients/core/hellolynk-client-update-entry.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { clientAccountBaseRoot } from "./hellolynk-client-account.mjs";
 import { startClientUpdateRuntime } from "./hellolynk-client-update-runtime.mjs";
+import { clientUpdateCatalogId, MAC_CLIENT_VERSION } from "./hellolynk-client-update.mjs";
 
 const running = new Map();
 
@@ -9,7 +10,9 @@ const running = new Map();
 // to the Host. A checkout or an uninstalled test fixture never self-updates.
 export function startInstalledClientUpdate(options = {}) {
   const { client, packageRoot, storeRoot } = options;
-  if (process.platform !== "win32" || !path.isAbsolute(String(packageRoot || ""))) return Promise.resolve(null);
+  const catalogId = clientUpdateCatalogId(client, process.platform);
+  const mac = process.platform === "darwin";
+  if (!catalogId || (mac && process.arch !== "arm64") || !path.isAbsolute(String(packageRoot || ""))) return Promise.resolve(null);
   let baseRoot;
   try { baseRoot = clientAccountBaseRoot(storeRoot); } catch { return Promise.resolve(null); }
   const key = `${client}\0${path.resolve(packageRoot)}\0${baseRoot}`;
@@ -21,8 +24,9 @@ export function startInstalledClientUpdate(options = {}) {
     const metadata = await fs.lstat(packageFile);
     if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1 || metadata.size > 64 * 1024) return null;
     const manifest = JSON.parse(await fs.readFile(packageFile, "utf8"));
-    if (manifest.hellolynkClient?.client !== client
-      || !/^\d+\.\d+\.\d+$/.test(manifest.version || "")) return null;
+    const version = mac ? MAC_CLIENT_VERSION : /^\d+\.\d+\.\d+$/u;
+    if (manifest.hellolynkClient?.client !== client || !version.test(manifest.version || "")
+      || (mac && (manifest.os?.[0] !== "darwin" || manifest.cpu?.[0] !== "arm64"))) return null;
     return startClientUpdateRuntime({
       root: baseRoot, client, currentVersion: manifest.version,
       installContext: { ...options.installContext, packageRoot: path.resolve(packageRoot) },

package/clients/core/hellolynk-client-update-runtime.mjs

@@ -4,7 +4,8 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { createClientUpdateManager, extractClientUpdateArchive, compareClientUpdateVersions, CLIENT_UPDATE_CLIENTS } from "./hellolynk-client-update.mjs";
+import { createClientUpdateManager, extractClientUpdateArchive, compareClientUpdateVersions, clientUpdateCatalogId,
+  CLIENT_UPDATE_CLIENTS, CLIENT_UPDATE_RELEASES, MAC_CLIENT_VERSION } from "./hellolynk-client-update.mjs";
 import { withNeutralHostStoreLock } from "./hellolynk-neutral-host-installation-store.mjs";
 import { readClientAccount } from "./hellolynk-client-account.mjs";
 import runtimeSafety from "./hellolynk-runtime-safety.cjs";
@@ -26,7 +27,7 @@ const RETRY_AFTER_MS = 10 * 60_000;
 // waits only for DSH's lease, and a downloaded update is applied by a worker in
 // the background. Checking the network is always detached.
 export async function startClientUpdateRuntime(options = {}) {
-  if ((options.platform || process.platform) !== "win32") return disabled();
+  if (!clientUpdateCatalogId(options.client, options.platform || process.platform)) return disabled();
   let config;
   try { config = normalize(options); await verifyInstalledContext(config); }
   catch { return disabled(); }
@@ -94,8 +95,8 @@ export async function runClientUpdateWorker(options = {}) {
 function createRuntime(config, options) {
   const { root, client, currentVersion, installContext } = config;
   const directory = path.join(root, "client-updates", client);
-  const statePath = path.join(directory, "runtime.json"), leasePath = path.join(directory, "leases.json"), installedPath = path.join(directory, "installed.json");
-  const manager = createClientUpdateManager({ ...options, root, client, currentVersion });
+  const statePath = path.join(directory, "runtime-v2.json"), leasePath = path.join(directory, "leases.json"), installedPath = path.join(directory, "installed.json");
+  const manager = createClientUpdateManager({ ...options, root, client, currentVersion, platform: config.platform });
   const alive = options.isProcessAlive || processAlive;
   async function gate(operation) {
     await safeDirectory(directory);
@@ -200,7 +201,8 @@ function createRuntime(config, options) {
       const attempted = runtime.sha256 === downloaded.sha256 && !(runtime.stage === "applying" || retryable);
       if (downloaded.stage !== "downloaded" || downloaded.error || attempted) return;
       // A damaged worker record means no known worker.
-      const worker = await readJson(path.join(directory, "worker.json"), null).catch((error) => { if (!damaged(error)) throw error; return null; });
+      const workerPath = path.join(directory, "worker-v2.json");
+      const worker = await readJson(workerPath, null).catch((error) => { if (!damaged(error)) throw error; return null; });
       if (worker?.client === client && Number.isSafeInteger(worker.pid) && alive(worker.pid)) return;
       const launch = options.spawnWorker || launchWorker;
       let pid;
@@ -210,13 +212,13 @@ function createRuntime(config, options) {
       } catch (error) {
         // Retain only this rejected launch attempt, not raw errors or proof of
         // worker absence. Keep an earlier PID's conservative liveness check.
-        await atomicJson(path.join(directory, "worker.json"), { client,
+        await atomicJson(workerPath, { client,
           ...(worker?.client === client && Number.isSafeInteger(worker.pid) ? { pid: worker.pid } : {}),
           sha256: downloaded.sha256, error: "client_update_worker_launch_failed", failedAt: Date.now(),
         }).catch(() => {});
         throw error;
       }
-      await atomicJson(path.join(directory, "worker.json"), { client, pid });
+      await atomicJson(workerPath, { client, pid });
     });
   }
   async function applyPending() {
@@ -236,7 +238,7 @@ function createRuntime(config, options) {
           if (sha(await safeFile(path.join(proof.packageRoot, "hellolynk-client-pack-manifest.json")))
             !== sha(await safeFile(path.join(installContext.packageRoot, "hellolynk-client-pack-manifest.json")))) throw failure("adoption_invalid");
           const doctor = await (options.runInstaller || runInstaller)({ executable: installContext.nodePath || process.execPath,
-            args: [path.join(installContext.packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor"], cwd: installContext.packageRoot, root, timeoutMs: 180_000 });
+            args: [path.join(installContext.packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor", "--json"], cwd: installContext.packageRoot, root, timeoutMs: 180_000 });
           if (!doctorProves(doctor, client, currentVersion)) throw failure("adoption_invalid");
           const adoptedRoot = path.join(path.dirname(root), "releases", `${client}-${sha(await safeFile(path.join(proof.packageRoot, "hellolynk-client-pack-manifest.json")))}`);
           if (!options.runInstaller) await verifyPackage(adoptedRoot, client, currentVersion);
@@ -274,7 +276,7 @@ function createRuntime(config, options) {
       try {
         await verifyPackage(packageRoot, client, version);
         const inspected = await run({ executable: installContext.nodePath || process.execPath,
-          args: [path.join(packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor"], cwd: packageRoot, root, timeoutMs: 180_000 });
+          args: [path.join(packageRoot, "bin", "hellolynk-client-setup.mjs"), "doctor", "--json"], cwd: packageRoot, root, timeoutMs: 180_000 });
         return doctorProves(inspected, client, version);
       } catch { return false; }
     };
@@ -397,7 +399,7 @@ async function prepareCandidate(config, record) {
   const directory = path.join(config.root, "client-updates", config.client);
   if (!HASH.test(record.sha256) || typeof record.version !== "string" || !/^[0-9A-Za-z.+-]{1,100}$/.test(record.version)
     || typeof record.filename !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.zip$/.test(record.filename)) throw failure("candidate_invalid");
-  const artifactPath = path.join(directory, "releases", `${record.version}-${record.sha256}`, record.filename);
+  const artifactPath = path.join(directory, CLIENT_UPDATE_RELEASES, `${record.version}-${record.sha256}`, record.filename);
   if (artifactPath !== record.artifactPath) throw failure("candidate_path_invalid");
   const archive = await safeFile(artifactPath, 64 * 1024 * 1024);
   if (archive.length !== record.bytes || sha(archive) !== record.sha256) throw failure("artifact_integrity_invalid");
@@ -406,43 +408,63 @@ async function prepareCandidate(config, record) {
   const extractedRoot = path.join(temporaryRoot, "extracted");
   try {
     // Re-extract the hash-verified archive; never execute a mutable earlier
-    // extractedRoot or an executable path supplied by state.json.
+    // extractedRoot or an executable path supplied by update state.
     const sealed = path.join(temporaryRoot, record.filename);
     await fs.writeFile(sealed, archive, { flag: "wx", mode: 0o600 });
-    await extractClientUpdateArchive({ archivePath: sealed, destination: extractedRoot });
-    let packageRoot;
-    if (config.client === "dsh") {
-      const descriptor = await readJson(path.join(extractedRoot, "trusted-release.json"));
-      const manifestBytes = await safeFile(path.join(extractedRoot, "dist", "package", "hellolynk-dsh-nav-build.json"));
-      if (descriptor?.contract !== "hellolynk-dsh-nav-release-v1" || descriptor.manifestSha256 !== sha(manifestBytes)) throw failure("package_pin_invalid");
-      const manifest = JSON.parse(manifestBytes.toString("utf8"));
-      if (manifest.contract !== "hellolynk-dsh-nav-build-v3") throw failure("package_pin_invalid");
-      await verifyRecords(path.join(extractedRoot, "dist", "package"), manifest.packageFiles, ["hellolynk-dsh-nav-build.json"]);
-      packageRoot = path.join(extractedRoot, "dist", "package", "runtime", "connect");
-      await safeFile(path.join(extractedRoot, "scripts", "install.mjs"));
-    } else {
-      const candidates = [extractedRoot, path.join(extractedRoot, "package"), path.join(extractedRoot, `hellolynk-${config.client}-${record.version}`, "package")];
-      const matches = [];
-      for (const candidate of candidates) if (await exists(path.join(candidate, "package.json"))) matches.push(candidate);
-      if (matches.length !== 1) throw failure("package_identity_invalid");
-      packageRoot = matches[0];
-    }
-    await verifyPackage(packageRoot, config.client, record.version);
+    await extractClientUpdateArchive({ archivePath: sealed, destination: extractedRoot, platform: config.platform });
+    const { packageRoot } = await verifyExtractedClientUpdatePackage(extractedRoot,
+      { client: config.client, platform: config.platform, version: record.version });
     return { temporaryRoot, extractedRoot, artifactPath: sealed, packageRoot, setupPath: path.join(packageRoot, "bin", "hellolynk-client-setup.mjs") };
   } catch (error) { await fs.rm(temporaryRoot, { recursive: true, force: true }); throw error; }
 }
 
+export async function verifyExtractedClientUpdatePackage(extractedRoot, { client, platform, version }) {
+  if (!CLIENT_UPDATE_CLIENTS.includes(client) || typeof version !== "string" || !VERSION.test(version)) throw failure("package_identity_invalid");
+  let packageRoot;
+  if (client === "dsh") {
+    const descriptor = await readJson(path.join(extractedRoot, "trusted-release.json"));
+    const manifestBytes = await safeFile(path.join(extractedRoot, "dist", "package", "hellolynk-dsh-nav-build.json"));
+    if (descriptor?.contract !== "hellolynk-dsh-nav-release-v1" || descriptor.manifestSha256 !== sha(manifestBytes)) throw failure("package_pin_invalid");
+    const manifest = JSON.parse(manifestBytes.toString("utf8"));
+    if (manifest.contract !== "hellolynk-dsh-nav-build-v3") throw failure("package_pin_invalid");
+    await verifyRecords(path.join(extractedRoot, "dist", "package"), manifest.packageFiles, ["hellolynk-dsh-nav-build.json"]);
+    packageRoot = path.join(extractedRoot, "dist", "package", "runtime", "connect");
+    await safeFile(path.join(extractedRoot, "scripts", "install.mjs"));
+  } else {
+    const id = clientUpdateCatalogId(client, platform) || client;
+    const candidates = [extractedRoot, path.join(extractedRoot, "package"), path.join(extractedRoot, `hellolynk-${id}-${version}`, "package")];
+    const matches = [];
+    for (const candidate of candidates) if (await exists(path.join(candidate, "package.json"))) matches.push(candidate);
+    if (matches.length !== 1) throw failure("package_identity_invalid");
+    packageRoot = matches[0];
+  }
+  const checked = await verifyPackage(packageRoot, client, version);
+  return { packageRoot, ...checked };
+}
+
 async function verifyPackage(root, client, version) {
   const pkg = await readJson(path.join(root, "package.json"));
   const manifestBytes = await safeFile(path.join(root, "hellolynk-client-pack-manifest.json"));
   const pin = await readJson(path.join(root, "hellolynk-client-pack-pin.json"));
   const manifest = JSON.parse(manifestBytes.toString("utf8"));
   if (pkg.version !== version || pkg.hellolynkClient?.client !== client || pkg.name !== NAMES[client]
+    || (MAC_CLIENT_VERSION.test(version) && (!clientUpdateCatalogId(client, "darwin") || pkg.os?.[0] !== "darwin" || pkg.cpu?.[0] !== "arm64"))
     || manifest.contract !== "hellolynk-client-npm-pack-manifest-v1" || manifest.client !== client
     || manifest.packageName !== pkg.name || manifest.version !== version
     || pin.contract !== "hellolynk-client-npm-pack-pin-v1" || pin.manifestSha256 !== sha(manifestBytes)) throw failure("package_identity_invalid");
   await verifyRecords(root, manifest.files, ["hellolynk-client-pack-manifest.json", "hellolynk-client-pack-pin.json"]);
   if (!manifest.files.some((file) => file.path === "bin/hellolynk-client-setup.mjs")) throw failure("package_pin_invalid");
+  if (MAC_CLIENT_VERSION.test(version)) {
+    const helpers = client === "codex"
+      ? ["plugins/hellolynk-codex/runtime/platform/darwin", "plugins/hellolynk-codex/runtime/bootstrap/platform/darwin"]
+      : ["runtime/platform/darwin"];
+    for (const relative of helpers) {
+      const file = `${relative}/hellolynk-keychain-helper.bin`;
+      if (!manifest.files.some(record => record.path === file)
+        || (process.platform !== "win32" && !((await fs.lstat(path.join(root, file))).mode & 0o100))) throw failure("package_pin_invalid");
+    }
+  }
+  return { coreRoot: pkg.hellolynkClient.coreRoot, files: manifest.files };
 }
 async function verifyRecords(root, records, allowedExtra) {
   if (!Array.isArray(records) || records.length < 1 || records.length > 5000) throw failure("package_pin_invalid");
@@ -471,7 +493,9 @@ async function verifyInstalledContext(config) {
   await verifyPackage(context.packageRoot, config.client, config.currentVersion);
 }
 function normalize(value) {
+  const platform = value.platform || process.platform;
   if (!CLIENT_UPDATE_CLIENTS.includes(value.client) || typeof value.currentVersion !== "string" || !VERSION.test(value.currentVersion)
+    || (platform === "darwin" && !MAC_CLIENT_VERSION.test(value.currentVersion))
     || !path.isAbsolute(String(value.root || "")) || !path.isAbsolute(String(value.installContext?.packageRoot || ""))) throw failure("configuration_invalid");
   const context = { packageRoot: path.resolve(value.installContext.packageRoot) };
   for (const name of ["nodePath", "dshProfile", "dshRoot"]) {
@@ -484,7 +508,7 @@ function normalize(value) {
     if (!HASH.test(value.installContext.expectedInstalledManifestSha256)) throw failure("configuration_invalid");
     context.expectedInstalledManifestSha256 = value.installContext.expectedInstalledManifestSha256;
   }
-  return { root: path.resolve(value.root), client: value.client, currentVersion: value.currentVersion, installContext: context };
+  return { root: path.resolve(value.root), client: value.client, currentVersion: value.currentVersion, platform, installContext: context };
 }
 async function launchWorker(config) {
   // A host may execute this module from an ephemeral captured import graph.
@@ -510,8 +534,9 @@ async function launchWorker(config) {
 async function runInstaller({ executable, args, cwd, root, timeoutMs }) {
   executable = await runtimeSafety.resolveHelloLynkStandaloneNode({ preferredExecutable: executable });
   const env = { ...runtimeSafety.standaloneHelloLynkNodeEnvironment(process.env), HELLOLYNK_NEUTRAL_STORE_ROOT: root };
+  const mac = process.platform === "darwin";
   return new Promise((resolve, reject) => {
-    const child = spawn(executable, args, { cwd, env, windowsHide: true, stdio: ["ignore", "pipe", "pipe"], shell: false });
+    const child = spawn(executable, args, { cwd, env, detached: mac, windowsHide: true, stdio: ["ignore", "pipe", "pipe"], shell: false });
     let stdout = "", stderr = "", finished = false, terminalError = null;
     const timer = setTimeout(() => terminate(failure("installer_timeout")), timeoutMs);
     function finish(error, value) { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }
@@ -529,6 +554,9 @@ async function runInstaller({ executable, args, cwd, root, timeoutMs }) {
           killer.on("error", () => { clearTimeout(killTimer); if (!finished) killChild(); });
           killer.once("close", () => { clearTimeout(killTimer); if (!finished) killChild(); });
         } catch { killChild(); }
+      } else if (mac && child.pid) {
+        // The installer owns this process group, including a synchronous Codex CLI.
+        try { process.kill(-child.pid, "SIGKILL"); } catch { killChild(); }
       } else killChild();
     }
     child.on("error", () => {
@@ -580,7 +608,8 @@ function damaged(error) { return error instanceof SyntaxError || error?.code ===
 // Windows paths compare case-insensitively and may differ by a link or short name.
 async function samePath(left, right) {
   if (typeof left !== "string" || typeof right !== "string" || !path.isAbsolute(left) || !path.isAbsolute(right)) return false;
-  const same = (a, b) => path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+  const canonical = (value) => process.platform === "win32" ? path.resolve(value).toLowerCase() : path.resolve(value);
+  const same = (a, b) => canonical(a) === canonical(b);
   if (same(left, right)) return true;
   try { return same(await fs.realpath(left), await fs.realpath(right)); } catch { return false; }
 }