opensocrates 1.0.0 → 1.1.2

package/installer/opensocrates.mjs

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
-import { createReadStream, createWriteStream, realpathSync } from "node:fs";
+import { createHash, randomInt, randomUUID } from "node:crypto";
+import { constants as fsConstants, createReadStream, createWriteStream, realpathSync } from "node:fs";
 import {
   access,
+  chmod,
   cp,
   lstat,
   mkdir,
   mkdtemp,
+  open,
   readFile,
   readdir,
   rename,
@@ -22,24 +24,58 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 
-export const PRODUCT_VERSION = "1.0.0";
+export const PRODUCT_VERSION = "1.1.2";
 export const REPOSITORY = "ParkerHwang/OpenSocrates";
 export const MARKETPLACE_NAME = "opensocrates";
 export const PLUGIN_NAME = "opensocrates";
 export const PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
-export const ASSET_NAME = `opensocrates-${PRODUCT_VERSION}-codex-plugin.zip`;
+export const DEFAULT_HOST = "codex";
+export const SUPPORTED_HOSTS = Object.freeze(["claude", "codex"]);
+export const ALL_HOST = "all";
+export const HOST_CHOICES = Object.freeze([ALL_HOST, ...SUPPORTED_HOSTS]);
+export function assetNameFor(host = DEFAULT_HOST) {
+  if (!SUPPORTED_HOSTS.includes(host)) {
+    fail(`unsupported host ${JSON.stringify(host)}`);
+  }
+  return `opensocrates-${PRODUCT_VERSION}-${host}-plugin.zip`;
+}
+export const ASSET_NAME = assetNameFor(DEFAULT_HOST);
 export const CHECKSUM_NAME = `${ASSET_NAME}.sha256`;
 
 const MARKER_NAME = ".opensocrates-managed.json";
-const MARKER = Object.freeze({
+const CODEX_MARKER = Object.freeze({
+  schemaVersion: 1,
+  marketplaceName: MARKETPLACE_NAME,
+  pluginName: PLUGIN_NAME,
+});
+const CLAUDE_MARKER = Object.freeze({
   schemaVersion: 1,
   marketplaceName: MARKETPLACE_NAME,
   pluginName: PLUGIN_NAME,
+  host: "claude",
+});
+const HOST_LAYOUTS = Object.freeze({
+  claude: {
+    marketplaceRelative: join(".claude-plugin", "marketplace.json"),
+    pluginRelative: join("plugins", PLUGIN_NAME),
+    manifestRelative: join(".claude-plugin", "plugin.json"),
+  },
+  codex: {
+    marketplaceRelative: join(".agents", "plugins", "marketplace.json"),
+    pluginRelative: join("build", "generated", "plugins", "codex"),
+    manifestRelative: join(".codex-plugin", "plugin.json"),
+  },
 });
-const MARKETPLACE_RELATIVE = join(".agents", "plugins", "marketplace.json");
-const PLUGIN_RELATIVE = join("build", "generated", "plugins", "codex");
 const MAX_DOWNLOAD_BYTES = 2 * 1024 * 1024 * 1024;
 const MAX_ARCHIVE_ENTRIES = 10_000;
+const DESIRED_STATE_SCHEMA = "opensocrates.desired-state/1.0.0";
+const RECEIPT_SCHEMA = "opensocrates.auto-update-receipt/1.0.0";
+const AUTO_UPDATE_LABEL = "com.opensocrates.auto-update";
+const AUTO_UPDATE_MIN_INTERVAL_HOURS = 1;
+const AUTO_UPDATE_MAX_INTERVAL_HOURS = 24 * 7;
+const AUTO_UPDATE_DEFAULT_INTERVAL_HOURS = 24;
+const AUTO_UPDATE_POLL_SECONDS = 60 * 60;
+const LOCK_STALE_MILLISECONDS = 2 * 60 * 60 * 1000;
 
 export class InstallerError extends Error {}
 
@@ -56,6 +92,273 @@ async function exists(target) {
   }
 }
 
+export function statePaths() {
+  const stateDirectory = resolve(
+    process.env.OPENSOCRATES_STATE_DIR || join(homedir(), ".opensocrates"),
+  );
+  const launchAgentsDirectory = resolve(
+    process.env.OPENSOCRATES_LAUNCH_AGENTS_DIR || join(homedir(), "Library", "LaunchAgents"),
+  );
+  return {
+    directory: stateDirectory,
+    desiredState: join(stateDirectory, "desired-state.json"),
+    receipt: join(stateDirectory, "auto-update-receipt.json"),
+    lock: join(stateDirectory, "lifecycle.lock"),
+    launchAgentsDirectory,
+    launchAgent: join(launchAgentsDirectory, `${AUTO_UPDATE_LABEL}.plist`),
+  };
+}
+
+function defaultDesiredState() {
+  return {
+    schema: DESIRED_STATE_SCHEMA,
+    channel: "stable",
+    installedHosts: [],
+    activeVersion: null,
+    updatePolicy: {
+      intervalHours: AUTO_UPDATE_DEFAULT_INTERVAL_HOURS,
+      allowMajor: false,
+    },
+    autoUpdate: {
+      enabled: false,
+      hosts: [],
+      nextCheckAt: null,
+    },
+    availableVersion: null,
+    lastCheckAt: null,
+    lastSuccessfulUpdateAt: null,
+  };
+}
+
+function normalizeDesiredState(value) {
+  if (
+    value === null ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    value.schema !== DESIRED_STATE_SCHEMA
+  ) {
+    fail("the OpenSocrates desired-state manifest has an unsupported schema");
+  }
+  const installedHosts = value.installedHosts;
+  if (
+    !Array.isArray(installedHosts) ||
+    installedHosts.some((host) => !SUPPORTED_HOSTS.includes(host)) ||
+    new Set(installedHosts).size !== installedHosts.length
+  ) {
+    fail("the OpenSocrates desired-state manifest has an invalid host set");
+  }
+  const channel = value.channel;
+  if (!new Set(["stable", "next"]).has(channel)) {
+    fail("the OpenSocrates desired-state manifest has an invalid update channel");
+  }
+  const intervalHours = value.updatePolicy?.intervalHours;
+  if (
+    !Number.isInteger(intervalHours) ||
+    intervalHours < AUTO_UPDATE_MIN_INTERVAL_HOURS ||
+    intervalHours > AUTO_UPDATE_MAX_INTERVAL_HOURS ||
+    typeof value.updatePolicy?.allowMajor !== "boolean" ||
+    typeof value.autoUpdate?.enabled !== "boolean"
+  ) {
+    fail("the OpenSocrates desired-state manifest has an invalid update policy");
+  }
+  const autoUpdateHosts =
+    value.autoUpdate.hosts === undefined
+      ? value.autoUpdate.enabled
+        ? installedHosts
+        : []
+      : value.autoUpdate.hosts;
+  if (
+    !Array.isArray(autoUpdateHosts) ||
+    autoUpdateHosts.some(
+      (host) => !SUPPORTED_HOSTS.includes(host) || !installedHosts.includes(host),
+    ) ||
+    new Set(autoUpdateHosts).size !== autoUpdateHosts.length ||
+    (value.autoUpdate.enabled && autoUpdateHosts.length === 0) ||
+    (!value.autoUpdate.enabled && autoUpdateHosts.length > 0)
+  ) {
+    fail("the OpenSocrates desired-state manifest has an invalid automatic-update host set");
+  }
+  return {
+    ...defaultDesiredState(),
+    ...value,
+    installedHosts: [...installedHosts].sort(),
+    updatePolicy: {
+      intervalHours,
+      allowMajor: value.updatePolicy.allowMajor,
+    },
+    autoUpdate: {
+      enabled: value.autoUpdate.enabled,
+      hosts: [...autoUpdateHosts].sort(),
+      nextCheckAt: value.autoUpdate.nextCheckAt ?? null,
+    },
+  };
+}
+
+export async function readDesiredState() {
+  const { desiredState } = statePaths();
+  if (!(await exists(desiredState))) {
+    return defaultDesiredState();
+  }
+  let value;
+  try {
+    value = JSON.parse(await readFile(desiredState, "utf8"));
+  } catch (error) {
+    fail(`cannot read the OpenSocrates desired-state manifest: ${error.message}`);
+  }
+  return normalizeDesiredState(value);
+}
+
+async function ensurePrivateDirectory(directory) {
+  if (await exists(directory)) {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      fail(`refusing to use a non-directory or symbolic-link state path: ${directory}`);
+    }
+    await chmod(directory, 0o700);
+    return;
+  }
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    fail(`refusing to use an unsafe state path: ${directory}`);
+  }
+  await chmod(directory, 0o700);
+}
+
+async function atomicWritePrivateFile(target, contents) {
+  const parent = dirname(target);
+  await ensurePrivateDirectory(parent);
+  const temporary = join(parent, `.${basename(target)}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, contents, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await chmod(temporary, 0o600);
+    await rename(temporary, target);
+  } finally {
+    if (await exists(temporary)) {
+      await rm(temporary, { force: true });
+    }
+  }
+}
+
+export async function writeDesiredState(value) {
+  const normalized = normalizeDesiredState(value);
+  await atomicWritePrivateFile(
+    statePaths().desiredState,
+    `${JSON.stringify(normalized, null, 2)}\n`,
+  );
+  return normalized;
+}
+
+async function writeAutoUpdateReceipt({ version, checkedAt, hosts, result, errorCategory }) {
+  const receipt = {
+    schema: RECEIPT_SCHEMA,
+    version,
+    checkedAt,
+    hosts: [...hosts]
+      .sort((left, right) => left.host.localeCompare(right.host))
+      .map(({ host, result: hostResult }) => ({ host, result: hostResult })),
+    result,
+    errorCategory: errorCategory ?? null,
+  };
+  await atomicWritePrivateFile(
+    statePaths().receipt,
+    `${JSON.stringify(receipt, null, 2)}\n`,
+  );
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function nextCheckAt(intervalHours) {
+  const intervalMilliseconds = intervalHours * 60 * 60 * 1000;
+  const jitterBasisPoints = randomInt(-1500, 1501);
+  return new Date(Date.now() + intervalMilliseconds * (1 + jitterBasisPoints / 10_000)).toISOString();
+}
+
+function majorVersion(value) {
+  const match = String(value ?? "").match(/^(\d+)\./u);
+  return match ? Number(match[1]) : null;
+}
+
+function errorCategory(error) {
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  if (/checksum|manifest|archive|symbolic link/u.test(message)) return "verification";
+  if (/download|fetch|network|offline|timed? ?out/u.test(message)) return "network";
+  if (/preflight|not logged|auth|version is required|could not run/u.test(message)) return "preflight";
+  if (/rollback|restore/u.test(message)) return "rollback";
+  if (/lock|already running/u.test(message)) return "locked";
+  if (/register|plugin|marketplace/u.test(message)) return "activation";
+  return "internal";
+}
+
+async function acquireOperationLock() {
+  const paths = statePaths();
+  await ensurePrivateDirectory(paths.directory);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await open(paths.lock, "wx", 0o600);
+      try {
+        await handle.writeFile(
+          `${JSON.stringify({ pid: process.pid, startedAt: nowIso() })}\n`,
+          "utf8",
+        );
+      } catch (writeError) {
+        await handle.close().catch(() => undefined);
+        await rm(paths.lock, { force: true }).catch(() => undefined);
+        throw writeError;
+      }
+      return async () => {
+        try {
+          await handle.close();
+        } finally {
+          await rm(paths.lock, { force: true });
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        throw error;
+      }
+      let stale = false;
+      try {
+        const lock = JSON.parse(await readFile(paths.lock, "utf8"));
+        const started = Date.parse(lock.startedAt);
+        let ownerAlive = null;
+        if (Number.isInteger(lock.pid) && lock.pid > 0) {
+          try {
+            process.kill(lock.pid, 0);
+            ownerAlive = true;
+          } catch (processError) {
+            ownerAlive = processError?.code === "ESRCH" ? false : true;
+          }
+        }
+        stale =
+          ownerAlive === false ||
+          (ownerAlive === null &&
+            Number.isFinite(started) &&
+            Date.now() - started > LOCK_STALE_MILLISECONDS);
+      } catch {
+        const info = await lstat(paths.lock);
+        stale = Date.now() - info.mtimeMs > LOCK_STALE_MILLISECONDS;
+      }
+      if (!stale || attempt > 0) {
+        fail("another OpenSocrates lifecycle operation is already running");
+      }
+      await rm(paths.lock, { force: true });
+    }
+  }
+  fail("could not acquire the OpenSocrates lifecycle lock");
+}
+
+export async function withOperationLock(action) {
+  const release = await acquireOperationLock();
+  try {
+    return await action();
+  } finally {
+    await release();
+  }
+}
+
 function jsonEqual(left, right) {
   const leftKeys = Object.keys(left).sort();
   const rightKeys = Object.keys(right).sort();
@@ -65,12 +368,16 @@ function jsonEqual(left, right) {
   );
 }
 
-export function markerMatches(value) {
+function markerFor(host) {
+  return host === "claude" ? CLAUDE_MARKER : CODEX_MARKER;
+}
+
+export function markerMatches(value, host = DEFAULT_HOST) {
   return (
     value !== null &&
     typeof value === "object" &&
     !Array.isArray(value) &&
-    jsonEqual(value, MARKER)
+    jsonEqual(value, markerFor(host))
   );
 }
 
@@ -111,7 +418,15 @@ export function parseChecksumText(text, expectedName = ASSET_NAME) {
 }
 
 export function parseCli(argv) {
-  const actions = new Set(["install", "status", "update", "remove", "verify", "help"]);
+  const actions = new Set([
+    "install",
+    "status",
+    "update",
+    "remove",
+    "verify",
+    "auto-update",
+    "help",
+  ]);
   const args = [...argv];
   let action = "install";
   if (args[0] && !args[0].startsWith("-")) {
@@ -120,13 +435,95 @@ export function parseCli(argv) {
   if (!actions.has(action)) {
     fail(`unknown action ${JSON.stringify(action)}`);
   }
-  const options = { action, asset: null, checksum: null };
+  let autoUpdateAction = null;
+  if (action === "auto-update") {
+    if (["--help", "-h"].includes(args[0])) {
+      args.shift();
+      action = "help";
+    } else {
+      autoUpdateAction = args.shift() ?? "status";
+      if (!new Set(["enable", "status", "disable", "run"]).has(autoUpdateAction)) {
+        fail(`unknown auto-update action ${JSON.stringify(autoUpdateAction)}`);
+      }
+    }
+  }
+  const options = {
+    action,
+    autoUpdateAction,
+    host: action === "auto-update" ? ALL_HOST : DEFAULT_HOST,
+    asset: null,
+    checksum: null,
+    hostAssets: {
+      claude: { asset: null, checksum: null },
+      codex: { asset: null, checksum: null },
+    },
+    channel: "stable",
+    intervalHours: AUTO_UPDATE_DEFAULT_INTERVAL_HOURS,
+    allowMajor: false,
+    force: false,
+  };
+  const seenOptions = new Set();
   while (args.length > 0) {
     const flag = args.shift();
     if (flag === "--help" || flag === "-h") {
       options.action = "help";
       continue;
     }
+    if (flag === "--host") {
+      seenOptions.add("host");
+      const host = args.shift();
+      if (!HOST_CHOICES.includes(host)) {
+        fail(`--host must be one of: ${HOST_CHOICES.join(", ")}`);
+      }
+      options.host = host;
+      continue;
+    }
+    if (flag === "--allow-major") {
+      seenOptions.add("allow-major");
+      options.allowMajor = true;
+      continue;
+    }
+    if (flag === "--force") {
+      seenOptions.add("force");
+      options.force = true;
+      continue;
+    }
+    if (flag === "--channel") {
+      seenOptions.add("channel");
+      const channel = args.shift();
+      if (!new Set(["stable", "next"]).has(channel)) {
+        fail("--channel must be one of: stable, next");
+      }
+      options.channel = channel;
+      continue;
+    }
+    if (flag === "--interval-hours") {
+      seenOptions.add("interval-hours");
+      const raw = args.shift();
+      const value = Number(raw);
+      if (
+        !Number.isInteger(value) ||
+        value < AUTO_UPDATE_MIN_INTERVAL_HOURS ||
+        value > AUTO_UPDATE_MAX_INTERVAL_HOURS
+      ) {
+        fail(
+          `--interval-hours must be an integer from ${AUTO_UPDATE_MIN_INTERVAL_HOURS} ` +
+            `through ${AUTO_UPDATE_MAX_INTERVAL_HOURS}`,
+        );
+      }
+      options.intervalHours = value;
+      continue;
+    }
+    const qualified = flag?.match(/^--(asset|checksum)-(claude|codex)$/u);
+    if (qualified) {
+      seenOptions.add(qualified[1]);
+      const value = args.shift();
+      if (!value || value.startsWith("-")) {
+        fail(`${flag} requires a file path`);
+      }
+      options.hostAssets[qualified[2]][qualified[1]] = resolve(value);
+      continue;
+    }
     if (flag !== "--asset" && flag !== "--checksum") {
       fail(`unknown option ${JSON.stringify(flag)}`);
     }
@@ -135,13 +532,71 @@ export function parseCli(argv) {
       fail(`${flag} requires a file path`);
     }
     options[flag === "--asset" ? "asset" : "checksum"] = resolve(value);
+    seenOptions.add(flag.slice(2));
   }
   if ((options.asset === null) !== (options.checksum === null)) {
     fail("--asset and --checksum must be supplied together");
   }
+  for (const host of SUPPORTED_HOSTS) {
+    const inputs = options.hostAssets[host];
+    if ((inputs.asset === null) !== (inputs.checksum === null)) {
+      fail(`--asset-${host} and --checksum-${host} must be supplied together`);
+    }
+  }
+  if (options.host === ALL_HOST && options.asset !== null) {
+    fail("--host all requires host-qualified --asset-<host> and --checksum-<host> options");
+  }
+  if (
+    options.host === ALL_HOST &&
+    SUPPORTED_HOSTS.some((host) => options.hostAssets[host].asset !== null) &&
+    SUPPORTED_HOSTS.some((host) => options.hostAssets[host].asset === null)
+  ) {
+    fail("local --host all verification requires asset and checksum pairs for both hosts");
+  }
+  if (
+    options.host !== ALL_HOST &&
+    SUPPORTED_HOSTS.some((host) => options.hostAssets[host].asset !== null)
+  ) {
+    fail("host-qualified asset options are only valid with --host all");
+  }
   if (["status", "remove", "help"].includes(options.action) && options.asset !== null) {
     fail(`${options.action} does not accept --asset or --checksum`);
   }
+  if (
+    ["status", "remove", "help"].includes(options.action) &&
+    SUPPORTED_HOSTS.some((host) => options.hostAssets[host].asset !== null)
+  ) {
+    fail(`${options.action} does not accept host-qualified asset options`);
+  }
+  if (
+    options.action === "auto-update" &&
+    options.autoUpdateAction !== "run" &&
+    (options.asset !== null ||
+      SUPPORTED_HOSTS.some((host) => options.hostAssets[host].asset !== null))
+  ) {
+    fail(`auto-update ${options.autoUpdateAction} does not accept local asset options`);
+  }
+  const autoUpdateEnable =
+    options.action === "auto-update" && options.autoUpdateAction === "enable";
+  const autoUpdateRun = options.action === "auto-update" && options.autoUpdateAction === "run";
+  for (const policyOption of ["allow-major", "channel", "interval-hours"]) {
+    if (seenOptions.has(policyOption) && !autoUpdateEnable) {
+      fail(`--${policyOption} is only valid with auto-update enable`);
+    }
+  }
+  if (seenOptions.has("force") && !autoUpdateRun) {
+    fail("--force is only valid with auto-update run");
+  }
+  if (
+    seenOptions.has("host") &&
+    options.action === "auto-update" &&
+    new Set(["status", "disable"]).has(options.autoUpdateAction)
+  ) {
+    fail(`auto-update ${options.autoUpdateAction} does not accept --host`);
+  }
+  if (autoUpdateRun && seenOptions.has("host") && options.host !== ALL_HOST) {
+    fail("auto-update run always reconciles desired state and only accepts --host all");
+  }
   return options;
 }
 
@@ -149,28 +604,47 @@ function showHelp() {
   console.log(`OpenSocrates ${PRODUCT_VERSION}
 
 Usage:
-  opensocrates install [--asset ZIP --checksum SHA256]
-  opensocrates status
-  opensocrates update [--asset ZIP --checksum SHA256]
-  opensocrates remove
-  opensocrates verify [--asset ZIP --checksum SHA256]
+  opensocrates install [--host all|codex|claude] [--asset ZIP --checksum SHA256]
+  opensocrates status [--host all|codex|claude]
+  opensocrates update [--host all|codex|claude] [--asset ZIP --checksum SHA256]
+  opensocrates remove [--host all|codex|claude]
+  opensocrates verify [--host all|codex|claude] [--asset ZIP --checksum SHA256]
+  opensocrates auto-update enable [--host all|codex|claude]
+      [--channel stable|next] [--interval-hours ${AUTO_UPDATE_DEFAULT_INTERVAL_HOURS}]
+      [--allow-major]
+  opensocrates auto-update status
+  opensocrates auto-update disable
 
 Without --asset, install, update, and verify download the v${PRODUCT_VERSION}
-package and checksum from GitHub Releases.
+package and checksum from GitHub Releases. The default lifecycle host is codex.
+For offline --host all verification, use --asset-claude/--checksum-claude
+and --asset-codex/--checksum-codex together. Automatic updates are opt-in.
 `);
 }
 
-function managedPaths() {
-  const configured = process.env.CODEX_HOME;
-  const codexHome = resolve(configured ? configured : join(homedir(), ".codex"));
-  const root = join(codexHome, "managed-marketplaces", MARKETPLACE_NAME);
+function managedPaths(host) {
+  const configured =
+    host === "claude" ? process.env.CLAUDE_CONFIG_DIR : process.env.CODEX_HOME;
+  const configuredHome = resolve(
+    configured ? configured : join(homedir(), host === "claude" ? ".claude" : ".codex"),
+  );
+  let hostHome = configuredHome;
+  try {
+    hostHome = realpathSync(configuredHome);
+  } catch {
+    // The installer creates a missing host home below after validating its
+    // explicit, non-recursive target. Lexical resolution is the only
+    // available normalization until then.
+  }
+  const root = join(hostHome, "managed-marketplaces", MARKETPLACE_NAME);
+  const layout = HOST_LAYOUTS[host];
   return {
-    codexHome,
+    hostHome,
     root,
     parent: dirname(root),
     marker: join(root, MARKER_NAME),
-    marketplace: join(root, MARKETPLACE_RELATIVE),
-    plugin: join(root, PLUGIN_RELATIVE),
+    marketplace: join(root, layout.marketplaceRelative),
+    plugin: join(root, layout.pluginRelative),
   };
 }
 
@@ -178,6 +652,10 @@ function codexBinary() {
   return process.env.CODEX_BIN || "codex";
 }
 
+function claudeBinary() {
+  return process.env.CLAUDE_BIN || "claude";
+}
+
 function run(command, args, { allowFailure = false } = {}) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
@@ -197,47 +675,103 @@ function run(command, args, { allowFailure = false } = {}) {
   return result;
 }
 
-function runCodexJson(args) {
-  const result = run(codexBinary(), args);
+function runJson(command, args, label) {
+  const result = run(command, args);
   try {
     const payload = JSON.parse(result.stdout);
-    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
-      fail("Codex returned a non-object JSON value");
+    if (payload === null || typeof payload !== "object") {
+      fail(`${label} returned a non-container JSON value`);
     }
     return payload;
   } catch (error) {
     if (error instanceof InstallerError) {
       throw error;
     }
-    fail(`Codex returned invalid JSON for ${args.join(" ")}: ${error.message}`);
+    fail(`${label} returned invalid JSON for ${args.join(" ")}: ${error.message}`);
+  }
+}
+
+function runCodexJson(args) {
+  const payload = runJson(codexBinary(), args, "Codex");
+  if (Array.isArray(payload)) {
+    fail("Codex returned an unexpected JSON array");
+  }
+  return payload;
+}
+
+function runClaudeJson(args) {
+  return runJson(claudeBinary(), args, "Claude Code");
+}
+
+function versionAtLeast(value, minimum) {
+  const match = String(value).match(/(\d+)\.(\d+)\.(\d+)/u);
+  if (!match) {
+    return false;
+  }
+  const current = match.slice(1).map(Number);
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (current[index] > minimum[index]) return true;
+    if (current[index] < minimum[index]) return false;
   }
+  return true;
 }
 
-function requireCodex() {
+function requireHostCli(host, { authenticated = false } = {}) {
+  if (host === "claude") {
+    const result = run(claudeBinary(), ["--version"]);
+    if (!versionAtLeast(result.stdout, [2, 1, 205])) {
+      fail(
+        `Claude Code 2.1.205 or later is required for structured selector output; got ${result.stdout.trim()}`,
+      );
+    }
+    if (authenticated) {
+      run(claudeBinary(), ["auth", "status"]);
+    }
+    return;
+  }
   run(codexBinary(), ["--version"]);
+  if (authenticated) {
+    run(codexBinary(), ["login", "status"]);
+  }
 }
 
-function marketplaceEntry() {
-  const payload = runCodexJson(["plugin", "marketplace", "list", "--json"]);
-  const entries = payload.marketplaces;
+function marketplaceEntries(host) {
+  const payload =
+    host === "claude"
+      ? runClaudeJson(["plugin", "marketplace", "list", "--json"])
+      : runCodexJson(["plugin", "marketplace", "list", "--json"]).marketplaces;
+  const entries = payload;
   if (!Array.isArray(entries)) {
-    fail("Codex marketplace list returned an unexpected schema");
+    fail(`${host} marketplace list returned an unexpected schema`);
   }
+  return entries;
+}
+
+function marketplaceEntry(host) {
+  const entries = marketplaceEntries(host);
   const matches = entries.filter((entry) => entry?.name === MARKETPLACE_NAME);
   if (matches.length > 1) {
-    fail(`Codex reported duplicate marketplaces named ${MARKETPLACE_NAME}`);
+    fail(`${host} reported duplicate marketplaces named ${MARKETPLACE_NAME}`);
   }
   return matches[0] ?? null;
 }
 
-function pluginState() {
+function pluginState(host) {
+  if (host === "claude") {
+    const installed = runClaudeJson(["plugin", "list", "--json"]);
+    if (!Array.isArray(installed)) {
+      fail("Claude Code plugin list returned an unexpected schema");
+    }
+    const matches = installed.filter((entry) => entry?.id === PLUGIN_ID);
+    if (matches.length > 1) {
+      fail(`Claude Code reported duplicate entries for ${PLUGIN_ID}`);
+    }
+    return matches.length === 1
+      ? { kind: "installed", version: matches[0].version ?? null }
+      : { kind: "missing", version: null };
+  }
   const payload = runCodexJson([
-    "plugin",
-    "list",
-    "--marketplace",
-    MARKETPLACE_NAME,
-    "--available",
-    "--json",
+    "plugin", "list", "--marketplace", MARKETPLACE_NAME, "--available", "--json",
   ]);
   const installed = Array.isArray(payload.installed) ? payload.installed : null;
   const available = Array.isArray(payload.available) ? payload.available : null;
@@ -258,6 +792,56 @@ function pluginState() {
   return { kind: "missing", version: null };
 }
 
+function detectLegacyClaudeInstallation() {
+  const marketplaces = marketplaceEntries("claude").filter(
+    (entry) =>
+      typeof entry?.name === "string" &&
+      entry.name !== MARKETPLACE_NAME &&
+      entry.name.toLowerCase() === MARKETPLACE_NAME,
+  );
+  const plugins = runClaudeJson(["plugin", "list", "--json"]);
+  const legacyPlugins = Array.isArray(plugins)
+    ? plugins.filter(
+        (entry) =>
+          typeof entry?.id === "string" &&
+          entry.id !== PLUGIN_ID &&
+          entry.id.toLowerCase() === PLUGIN_ID,
+      )
+    : [];
+  const names = marketplaces.map((entry) => entry.name).join(", ") || "OpenSocrates";
+  return { found: marketplaces.length > 0 || legacyPlugins.length > 0, names };
+}
+
+// Install and update write into the managed root, so a case-variant pre-1.0
+// registration must be resolved by the user first. Status and remove are
+// diagnostic and scoped to the root this installer owns, so they only warn:
+// blocking them would strand a user who needs to inspect or back out.
+function requireNoLegacyClaudeInstallation() {
+  const legacy = detectLegacyClaudeInstallation();
+  if (legacy.found) {
+    fail(
+      `a legacy Claude marketplace (${legacy.names}) is installed; OpenSocrates will not remove it automatically. ` +
+        "Uninstall its plugin and marketplace explicitly, then rerun this command. See the README migration section.",
+    );
+  }
+}
+
+function warnLegacyClaudeInstallation() {
+  let legacy;
+  try {
+    legacy = detectLegacyClaudeInstallation();
+  } catch {
+    return;
+  }
+  if (legacy.found) {
+    console.warn(
+      `warning: a legacy Claude marketplace (${legacy.names}) is also registered. ` +
+        "OpenSocrates never removes it automatically; this command only affects the root it owns. " +
+        "See the README migration section.",
+    );
+  }
+}
+
 async function readJsonObject(target) {
   let payload;
   try {
@@ -271,13 +855,13 @@ async function readJsonObject(target) {
   return payload;
 }
 
-async function requireOwnedRoot(root) {
+async function requireOwnedRoot(root, host) {
   const info = await lstat(root);
   if (!info.isDirectory() || info.isSymbolicLink()) {
     fail(`managed marketplace path is not an owned directory: ${root}`);
   }
   const marker = await readJsonObject(join(root, MARKER_NAME));
-  if (!markerMatches(marker)) {
+  if (!markerMatches(marker, host)) {
     fail(`managed marketplace path has no valid ownership marker: ${root}`);
   }
 }
@@ -313,24 +897,34 @@ async function downloadFile(url, destination) {
   }
 }
 
-async function resolveAssetInputs(options, scratch) {
-  if (options.asset !== null) {
-    if (!(await exists(options.asset)) || !(await exists(options.checksum))) {
+function localAssetInputs(options, host) {
+  if (options.host === ALL_HOST) {
+    return options.hostAssets[host];
+  }
+  return { asset: options.asset, checksum: options.checksum };
+}
+
+async function resolveAssetInputs(options, scratch, host) {
+  const local = localAssetInputs(options, host);
+  if (local.asset !== null) {
+    if (!(await exists(local.asset)) || !(await exists(local.checksum))) {
       fail("the supplied asset or checksum file does not exist");
     }
-    return { asset: options.asset, checksum: options.checksum };
+    return local;
   }
   const base = `https://github.com/${REPOSITORY}/releases/download/v${PRODUCT_VERSION}`;
-  const asset = join(scratch, ASSET_NAME);
-  const checksum = join(scratch, CHECKSUM_NAME);
+  const assetName = assetNameFor(host);
+  const checksumName = `${assetName}.sha256`;
+  const asset = join(scratch, assetName);
+  const checksum = join(scratch, checksumName);
   console.log(`Downloading OpenSocrates ${PRODUCT_VERSION} from GitHub Releases...`);
-  await downloadFile(`${base}/${ASSET_NAME}`, asset);
-  await downloadFile(`${base}/${CHECKSUM_NAME}`, checksum);
+  await downloadFile(`${base}/${assetName}`, asset);
+  await downloadFile(`${base}/${checksumName}`, checksum);
   return { asset, checksum };
 }
 
-async function verifyOuterChecksum(asset, checksum) {
-  const expected = parseChecksumText(await readFile(checksum, "utf8"));
+async function verifyOuterChecksum(asset, checksum, host) {
+  const expected = parseChecksumText(await readFile(checksum, "utf8"), assetNameFor(host));
   const actual = await sha256File(asset);
   if (actual !== expected) {
     fail(`release checksum mismatch: expected ${expected}, got ${actual}`);
@@ -420,8 +1014,8 @@ async function verifyPackageChecksums(pluginRoot) {
   return declared.size;
 }
 
-async function verifyExtractedPackage(pluginRoot) {
-  const manifest = await readJsonObject(join(pluginRoot, ".codex-plugin", "plugin.json"));
+async function verifyExtractedPackage(pluginRoot, host) {
+  const manifest = await readJsonObject(join(pluginRoot, HOST_LAYOUTS[host].manifestRelative));
   if (manifest.name !== PLUGIN_NAME || manifest.version !== PRODUCT_VERSION) {
     fail(
       `plugin manifest mismatch: expected ${PLUGIN_NAME} ${PRODUCT_VERSION}, ` +
@@ -431,7 +1025,7 @@ async function verifyExtractedPackage(pluginRoot) {
   const release = await readJsonObject(join(pluginRoot, "release-manifest.json"));
   if (
     release.product_version !== PRODUCT_VERSION ||
-    release.host !== "codex" ||
+    release.host !== host ||
     release.schema !== "opensocrates.plugin-release-manifest/1.0.0"
   ) {
     fail("package release manifest does not match this installer");
@@ -450,22 +1044,61 @@ async function verifyExtractedPackage(pluginRoot) {
   return verifyPackageChecksums(pluginRoot);
 }
 
-async function prepareVerifiedPackage(options) {
+async function prepareVerifiedPackage(options, host = options.host) {
+  if (!SUPPORTED_HOSTS.includes(host)) {
+    fail(`cannot prepare a package for unsupported host ${JSON.stringify(host)}`);
+  }
   const scratch = await mkdtemp(join(tmpdir(), "opensocrates-install-"));
   try {
-    const { asset, checksum } = await resolveAssetInputs(options, scratch);
-    await verifyOuterChecksum(asset, checksum);
+    const { asset, checksum } = await resolveAssetInputs(options, scratch, host);
+    await verifyOuterChecksum(asset, checksum, host);
     const pluginRoot = join(scratch, "plugin");
     await extractArchive(asset, pluginRoot);
-    const checkedFiles = await verifyExtractedPackage(pluginRoot);
-    return { scratch, pluginRoot, checkedFiles };
+    const checkedFiles = await verifyExtractedPackage(pluginRoot, host);
+    return { scratch, pluginRoot, checkedFiles, host };
   } catch (error) {
     await rm(scratch, { recursive: true, force: true });
     throw error;
   }
 }
 
-function expectedMarketplace() {
+async function prepareVerifiedPackages(options, hosts) {
+  const settled = await Promise.allSettled(
+    hosts.map((host) => prepareVerifiedPackage(options, host)),
+  );
+  const prepared = settled
+    .filter((result) => result.status === "fulfilled")
+    .map((result) => result.value);
+  const failure = settled.find((result) => result.status === "rejected");
+  if (failure) {
+    await Promise.all(
+      prepared.map((item) => rm(item.scratch, { recursive: true, force: true })),
+    );
+    throw failure.reason;
+  }
+  return prepared;
+}
+
+function expectedMarketplace(host) {
+  if (host === "claude") {
+    return {
+      name: MARKETPLACE_NAME,
+      owner: { name: "Parker Hwang" },
+      metadata: {
+        description: "OpenSocrates reasoning support for Claude Code and Cowork",
+        version: PRODUCT_VERSION,
+      },
+      plugins: [
+        {
+          name: PLUGIN_NAME,
+          source: `./plugins/${PLUGIN_NAME}`,
+          description:
+            "Local reasoning-system selection for Claude Code and Cowork, plus one /opensocrates entry.",
+          category: "workflow",
+        },
+      ],
+    };
+  }
   return {
     name: MARKETPLACE_NAME,
     interface: { displayName: "OpenSocrates" },
@@ -486,23 +1119,24 @@ function expectedMarketplace() {
   };
 }
 
-async function buildStagingTree(parent, pluginSource) {
+async function buildStagingTree(parent, pluginSource, host) {
+  const layout = HOST_LAYOUTS[host];
   const staging = await mkdtemp(join(parent, ".opensocrates.staging-"));
   try {
-    const marketplace = join(staging, MARKETPLACE_RELATIVE);
-    const plugin = join(staging, PLUGIN_RELATIVE);
+    const marketplace = join(staging, layout.marketplaceRelative);
+    const plugin = join(staging, layout.pluginRelative);
     await mkdir(dirname(marketplace), { recursive: true, mode: 0o700 });
     await mkdir(dirname(plugin), { recursive: true, mode: 0o700 });
     await cp(pluginSource, plugin, { recursive: true, preserveTimestamps: true });
-    await writeFile(marketplace, `${JSON.stringify(expectedMarketplace(), null, 2)}\n`, {
+    await writeFile(marketplace, `${JSON.stringify(expectedMarketplace(host), null, 2)}\n`, {
       encoding: "utf8",
       mode: 0o600,
     });
-    await writeFile(join(staging, MARKER_NAME), `${JSON.stringify(MARKER, null, 2)}\n`, {
+    await writeFile(join(staging, MARKER_NAME), `${JSON.stringify(markerFor(host), null, 2)}\n`, {
       encoding: "utf8",
       mode: 0o600,
     });
-    await verifyExtractedPackage(plugin);
+    await verifyExtractedPackage(plugin, host);
     return staging;
   } catch (error) {
     await rm(staging, { recursive: true, force: true });
@@ -510,17 +1144,38 @@ async function buildStagingTree(parent, pluginSource) {
   }
 }
 
-function entryRoot(entry) {
+function entryRoot(entry, host) {
   if (entry === null) {
     return null;
   }
-  if (typeof entry.root !== "string" || entry.root.trim().length === 0) {
-    fail(`Codex marketplace ${MARKETPLACE_NAME} has no usable root`);
+  const value = host === "claude" ? entry.path ?? entry.installLocation : entry.root;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    fail(`${host} marketplace ${MARKETPLACE_NAME} has no usable root`);
+  }
+  const resolved = resolve(value);
+  try {
+    // Host CLIs may report an equivalent canonical path even when the user
+    // configured a symlinked home (for example /var versus /private/var on
+    // macOS). Compare canonical existing paths without weakening ownership
+    // checks for missing or unmanaged roots.
+    return realpathSync(resolved);
+  } catch {
+    return resolved;
   }
-  return resolve(entry.root);
 }
 
-function removeRegistration(entry, state) {
+function removeRegistration(host, entry, state) {
+  if (host === "claude") {
+    if (state.kind === "installed") {
+      run(claudeBinary(), ["plugin", "uninstall", PLUGIN_ID, "--scope", "user"]);
+    }
+    if (entry !== null) {
+      run(claudeBinary(), [
+        "plugin", "marketplace", "remove", MARKETPLACE_NAME, "--scope", "user",
+      ]);
+    }
+    return;
+  }
   if (state.kind === "installed") {
     runCodexJson(["plugin", "remove", PLUGIN_ID, "--json"]);
   }
@@ -529,7 +1184,14 @@ function removeRegistration(entry, state) {
   }
 }
 
-function addRegistration(root, installPlugin) {
+function addRegistration(host, root, installPlugin) {
+  if (host === "claude") {
+    run(claudeBinary(), ["plugin", "marketplace", "add", root, "--scope", "user"]);
+    if (installPlugin) {
+      run(claudeBinary(), ["plugin", "install", PLUGIN_ID, "--scope", "user"]);
+    }
+    return null;
+  }
   runCodexJson(["plugin", "marketplace", "add", root, "--json"]);
   if (installPlugin) {
     return runCodexJson(["plugin", "add", PLUGIN_ID, "--json"]);
@@ -537,10 +1199,10 @@ function addRegistration(root, installPlugin) {
   return null;
 }
 
-function removeRegistrationBestEffort() {
+function removeRegistrationBestEffort(host) {
   const entry = (() => {
     try {
-      return marketplaceEntry();
+      return marketplaceEntry(host);
     } catch {
       return null;
     }
@@ -549,174 +1211,963 @@ function removeRegistrationBestEffort() {
     return;
   }
   try {
-    const state = pluginState();
+    const state = pluginState(host);
     if (state.kind === "installed") {
-      run(codexBinary(), ["plugin", "remove", PLUGIN_ID, "--json"], { allowFailure: true });
+      const binary = host === "claude" ? claudeBinary() : codexBinary();
+      const args =
+        host === "claude"
+          ? ["plugin", "uninstall", PLUGIN_ID, "--scope", "user"]
+          : ["plugin", "remove", PLUGIN_ID, "--json"];
+      run(binary, args, { allowFailure: true });
     }
   } catch {
     // Rollback continues with marketplace cleanup.
   }
-  run(codexBinary(), ["plugin", "marketplace", "remove", MARKETPLACE_NAME, "--json"], {
-    allowFailure: true,
-  });
+  const binary = host === "claude" ? claudeBinary() : codexBinary();
+  const args =
+    host === "claude"
+      ? ["plugin", "marketplace", "remove", MARKETPLACE_NAME, "--scope", "user"]
+      : ["plugin", "marketplace", "remove", MARKETPLACE_NAME, "--json"];
+  run(binary, args, { allowFailure: true });
 }
 
-async function installVerifiedPackage(pluginSource, action) {
-  requireCodex();
-  const paths = managedPaths();
-  await mkdir(paths.parent, { recursive: true, mode: 0o700 });
+async function recoveryStep(label, action) {
+  try {
+    await action();
+    return true;
+  } catch (recoveryError) {
+    const detail =
+      recoveryError instanceof Error ? recoveryError.message : String(recoveryError);
+    console.error(`warning: rollback step failed (${label}): ${detail}`);
+    return false;
+  }
+}
 
-  const previousEntry = marketplaceEntry();
-  if (previousEntry !== null && entryRoot(previousEntry) !== paths.root) {
+async function preflightHost(host, action) {
+  requireHostCli(host, { authenticated: ["install", "update"].includes(action) });
+  if (host === "claude") {
+    if (["install", "update"].includes(action)) {
+      requireNoLegacyClaudeInstallation();
+    } else {
+      warnLegacyClaudeInstallation();
+    }
+  }
+  const paths = managedPaths(host);
+  const previousEntry = marketplaceEntry(host);
+  if (previousEntry !== null && entryRoot(previousEntry, host) !== paths.root) {
     fail(
-      `marketplace ${MARKETPLACE_NAME} is already registered at ${entryRoot(previousEntry)}; ` +
+      `marketplace ${MARKETPLACE_NAME} is already registered at ${entryRoot(previousEntry, host)}; ` +
         "refusing to overwrite an unmanaged location",
     );
   }
-  const previousState = previousEntry === null ? { kind: "missing", version: null } : pluginState();
+  const rootExists = await exists(paths.root);
+  if (rootExists) {
+    await requireOwnedRoot(paths.root, host);
+  }
+  if (previousEntry !== null && !rootExists) {
+    fail(`${host} has a managed registration whose root is missing: ${paths.root}`);
+  }
+  const previousState =
+    previousEntry === null ? { kind: "missing", version: null } : pluginState(host);
+  return { host, paths, previousEntry, previousState, rootExists };
+}
+
+async function preflightSelectedHosts(options, action, desiredState) {
+  if (options.host !== ALL_HOST) {
+    return [await preflightHost(options.host, action)];
+  }
+  const desiredHosts = new Set(desiredState.installedHosts);
+  const rootPresence = Object.fromEntries(
+    await Promise.all(
+      SUPPORTED_HOSTS.map(async (host) => [host, await exists(managedPaths(host).root)]),
+    ),
+  );
+  const settled = await Promise.allSettled(
+    SUPPORTED_HOSTS.map((host) => preflightHost(host, action)),
+  );
+  const successes = new Map();
+  const failures = new Map();
+  settled.forEach((result, index) => {
+    const host = SUPPORTED_HOSTS[index];
+    if (result.status === "fulfilled") successes.set(host, result.value);
+    else failures.set(host, result.reason);
+  });
+
+  const required = new Set();
+  if (action === "install") {
+    for (const host of SUPPORTED_HOSTS) {
+      if (desiredHosts.has(host) || rootPresence[host]) required.add(host);
+    }
+  } else if (desiredHosts.size > 0) {
+    for (const host of desiredHosts) required.add(host);
+  } else if (action === "remove") {
+    for (const host of SUPPORTED_HOSTS) {
+      if (rootPresence[host]) required.add(host);
+    }
+  }
+  for (const host of required) {
+    if (failures.has(host)) {
+      const reason = failures.get(host);
+      fail(`preflight failed for ${host}: ${reason instanceof Error ? reason.message : reason}`);
+    }
+  }
+
+  let selected;
+  if (action === "update" && desiredHosts.size > 0) {
+    selected = [...desiredHosts].map((host) => successes.get(host)).filter(Boolean);
+  } else if (action === "remove") {
+    selected = [...successes.values()].filter(
+      (item) => desiredHosts.has(item.host) || item.rootExists || item.previousEntry !== null,
+    );
+  } else {
+    selected = [...successes.values()];
+  }
+  for (const [host, reason] of failures) {
+    if (!required.has(host)) {
+      console.log(
+        `${host}: skipped (host is unavailable or not authenticated: ` +
+          `${reason instanceof Error ? reason.message : reason})`,
+      );
+    }
+  }
+  if (selected.length === 0 && action !== "remove") {
+    fail(`preflight found no ready hosts for ${action} --host all`);
+  }
+  return selected.sort((left, right) => left.host.localeCompare(right.host));
+}
+
+async function stageInstallation(preflight, pluginSource) {
+  const { host, paths } = preflight;
+  await mkdir(paths.parent, { recursive: true, mode: 0o700 });
+  const staging = await buildStagingTree(paths.parent, pluginSource, host);
+  return {
+    ...preflight,
+    staging,
+    backup: join(paths.parent, `.opensocrates.backup-${randomUUID()}`),
+    registrationRemoved: false,
+    backupCreated: false,
+    newRootActive: false,
+    activationStarted: false,
+  };
+}
+
+async function activateInstallation(transaction) {
+  const { host, paths, previousEntry, previousState } = transaction;
+  transaction.activationStarted = true;
+  if (previousEntry !== null) {
+    transaction.registrationRemoved = true;
+    removeRegistration(host, previousEntry, previousState);
+  }
   if (await exists(paths.root)) {
-    await requireOwnedRoot(paths.root);
+    await rename(paths.root, transaction.backup);
+    transaction.backupCreated = true;
+  }
+  await rename(transaction.staging, paths.root);
+  transaction.newRootActive = true;
+  const result = addRegistration(host, paths.root, true);
+  const state = pluginState(host);
+  if (
+    (host === "codex" &&
+      (result?.pluginId !== PLUGIN_ID || result?.version !== PRODUCT_VERSION)) ||
+    state.kind !== "installed" ||
+    state.version !== PRODUCT_VERSION
+  ) {
+    fail(`${host} did not confirm the expected installed plugin and version`);
+  }
+}
+
+async function rollbackInstallation(transaction) {
+  if (!transaction.activationStarted) return;
+  const { host, paths, previousEntry, previousState } = transaction;
+  let restored = false;
+  await recoveryStep(`unregister the failed ${host} installation`, async () => {
+    removeRegistrationBestEffort(host);
+  });
+  if (transaction.newRootActive && (await exists(paths.root))) {
+    await recoveryStep(`remove the failed ${host} installation root`, async () => {
+      // This root was created by this transaction, so deleting it cannot
+      // cross the ownership boundary even if a failed host command damaged
+      // its marker.
+      await rm(paths.root, { recursive: true, force: true });
+    });
+  }
+  if (transaction.backupCreated && (await exists(transaction.backup))) {
+    restored = await recoveryStep(`restore the previous ${host} installation`, async () => {
+      await requireOwnedRoot(transaction.backup, host);
+      await rename(transaction.backup, paths.root);
+    });
+  }
+  if (
+    transaction.registrationRemoved &&
+    previousEntry !== null &&
+    (restored || !transaction.backupCreated)
+  ) {
+    await recoveryStep(`re-register the previous ${host} installation`, async () => {
+      addRegistration(host, paths.root, previousState.kind === "installed");
+    });
+  }
+  if (transaction.backupCreated && !restored) {
+    console.error(
+      `error: the previous ${host} OpenSocrates installation could not be restored automatically.`,
+    );
+    console.error(`error: your previous files are preserved at: ${transaction.backup}`);
+    console.error(
+      `error: remove ${paths.root} if it still exists, move the preserved directory ` +
+        `to ${paths.root}, then rerun \`opensocrates install --host ${host}\`.`,
+    );
+  }
+}
+
+async function cleanupInstallationTransaction(transaction) {
+  if (await exists(transaction.staging)) {
+    await rm(transaction.staging, { recursive: true, force: true });
+  }
+}
+
+async function commitInstallation(transaction) {
+  if (transaction.backupCreated && (await exists(transaction.backup))) {
+    await requireOwnedRoot(transaction.backup, transaction.host);
+    await rm(transaction.backup, { recursive: true });
+    transaction.backupCreated = false;
   }
+}
 
-  const staging = await buildStagingTree(paths.parent, pluginSource);
-  const backup = join(paths.parent, `.opensocrates.backup-${randomUUID()}`);
-  let registrationRemoved = false;
-  let backupCreated = false;
-  let newRootActive = false;
+function installedDesiredState(previous, hosts) {
+  return {
+    ...previous,
+    installedHosts: [...new Set([...previous.installedHosts, ...hosts])].sort(),
+    activeVersion: PRODUCT_VERSION,
+    availableVersion: PRODUCT_VERSION,
+  };
+}
+
+async function runInstallOrUpdate(options, action) {
+  const desired = await readDesiredState();
+  const preflights = await preflightSelectedHosts(options, action, desired);
+  const hosts = preflights.map((item) => item.host);
+  const prepared = await prepareVerifiedPackages(options, hosts);
+  const packages = new Map(prepared.map((item) => [item.host, item]));
+  const transactions = [];
   try {
-    if (previousEntry !== null) {
-      registrationRemoved = true;
-      removeRegistration(previousEntry, previousState);
-    }
-    if (await exists(paths.root)) {
-      await rename(paths.root, backup);
-      backupCreated = true;
-    }
-    await rename(staging, paths.root);
-    newRootActive = true;
-    const result = addRegistration(paths.root, true);
-    const state = pluginState();
-    if (
-      result?.pluginId !== PLUGIN_ID ||
-      result?.version !== PRODUCT_VERSION ||
-      state.kind !== "installed" ||
-      state.version !== PRODUCT_VERSION
-    ) {
-      fail("Codex did not confirm the expected installed plugin and version");
-    }
-    if (backupCreated) {
-      await requireOwnedRoot(backup);
-      await rm(backup, { recursive: true });
-    }
-    const verb = action === "update" ? "updated" : "installed";
-    console.log(`OpenSocrates ${PRODUCT_VERSION} ${verb} successfully.`);
-    console.log(`Managed marketplace: ${paths.root}`);
-    console.log("Start a new Codex task to load the updated skills and hooks.");
-  } catch (error) {
-    removeRegistrationBestEffort();
-    if (newRootActive && (await exists(paths.root))) {
-      await requireOwnedRoot(paths.root);
-      await rm(paths.root, { recursive: true });
+    for (const preflight of preflights) {
+      const item = packages.get(preflight.host);
+      console.log(
+        `${preflight.host}: verified OpenSocrates ${PRODUCT_VERSION} and ` +
+          `${item.checkedFiles} package files`,
+      );
+      transactions.push(await stageInstallation(preflight, item.pluginRoot));
     }
-    if (backupCreated && (await exists(backup))) {
-      await requireOwnedRoot(backup);
-      await rename(backup, paths.root);
+    for (const transaction of transactions) {
+      await activateInstallation(transaction);
+      console.log(`${transaction.host}: activated OpenSocrates ${PRODUCT_VERSION}`);
     }
-    if (registrationRemoved && previousEntry !== null) {
-      try {
-        addRegistration(paths.root, previousState.kind === "installed");
-      } catch (rollbackError) {
-        fail(`${error.message}; rollback also failed: ${rollbackError.message}`);
-      }
+    await writeDesiredState(installedDesiredState(desired, hosts));
+  } catch (error) {
+    for (const transaction of [...transactions].reverse()) {
+      await rollbackInstallation(transaction);
     }
     throw error;
   } finally {
-    if (await exists(staging)) {
-      await rm(staging, { recursive: true, force: true });
+    await Promise.all(transactions.map(cleanupInstallationTransaction));
+    await Promise.all(
+      prepared.map((item) => rm(item.scratch, { recursive: true, force: true })),
+    );
+  }
+  for (const transaction of transactions) {
+    const cleaned = await recoveryStep(`remove the committed ${transaction.host} backup`, async () => {
+      await commitInstallation(transaction);
+    });
+    if (!cleaned) {
+      console.warn(`warning: ${transaction.host} is active, but its previous backup needs cleanup`);
     }
   }
+  const verb = action === "update" ? "updated" : "installed";
+  console.log(
+    `OpenSocrates ${PRODUCT_VERSION} ${verb} successfully for ${hosts.join(", ")}.`,
+  );
+  console.log("Start new host tasks to load the updated skills and hooks.");
+  return hosts;
 }
 
-async function showStatus() {
-  requireCodex();
-  const paths = managedPaths();
-  const entry = marketplaceEntry();
+async function inspectHostStatus(host) {
+  requireHostCli(host);
+  if (host === "claude") warnLegacyClaudeInstallation();
+  const paths = managedPaths(host);
+  const entry = marketplaceEntry(host);
   if (entry === null) {
     if (await exists(paths.root)) {
-      await requireOwnedRoot(paths.root);
-      console.log(`OpenSocrates files are present but not registered: ${paths.root}`);
-    } else {
-      console.log("OpenSocrates is not installed.");
+      await requireOwnedRoot(paths.root, host);
+      return { host, kind: "files-only", version: null, paths };
     }
-    return;
+    return { host, kind: "missing", version: null, paths };
   }
-  if (entryRoot(entry) !== paths.root) {
-    fail(`OpenSocrates is registered at an unmanaged location: ${entryRoot(entry)}`);
+  if (entryRoot(entry, host) !== paths.root) {
+    fail(`OpenSocrates is registered at an unmanaged location: ${entryRoot(entry, host)}`);
   }
-  await requireOwnedRoot(paths.root);
-  const state = pluginState();
-  if (state.kind === "installed") {
-    console.log(`OpenSocrates ${state.version ?? "unknown"} is installed.`);
-  } else if (state.kind === "available") {
-    console.log(`OpenSocrates ${state.version ?? "unknown"} is available but not installed.`);
+  await requireOwnedRoot(paths.root, host);
+  const state = pluginState(host);
+  return { host, kind: state.kind, version: state.version, paths };
+}
+
+async function showStatus(host) {
+  if (host === ALL_HOST) {
+    const desired = await readDesiredState();
+    console.log(`Desired version: ${desired.activeVersion ?? "none"}`);
+    console.log(`Available version: ${desired.availableVersion ?? "unknown"}`);
+    console.log(`Last check: ${desired.lastCheckAt ?? "never"}`);
+    console.log(`Last successful update: ${desired.lastSuccessfulUpdateAt ?? "never"}`);
+    console.log(`Auto-update: ${desired.autoUpdate.enabled ? "enabled" : "disabled"}`);
+    let drift = false;
+    for (const candidate of SUPPORTED_HOSTS) {
+      try {
+        const status = await inspectHostStatus(candidate);
+        const expected = desired.installedHosts.includes(candidate);
+        const hostDrift = expected
+          ? status.kind !== "installed" ||
+            desired.activeVersion === null ||
+            status.version !== desired.activeVersion
+          : status.kind !== "missing";
+        drift ||= hostDrift;
+        if (status.kind === "installed") {
+          console.log(
+            `${candidate}: installed ${status.version ?? "unknown"}` +
+              (expected
+                ? hostDrift
+                  ? ` (drift from ${desired.activeVersion ?? "desired state"})`
+                  : " (in sync)"
+                : " (not in desired state)"),
+          );
+        } else if (status.kind === "available") {
+          console.log(
+            `${candidate}: available but not installed (${status.version ?? "unknown"})` +
+              (expected ? " (drift: desired host is not active)" : ""),
+          );
+        } else if (status.kind === "files-only") {
+          console.log(`${candidate}: managed files present but not registered`);
+        } else {
+          console.log(
+            `${candidate}: not installed` + (expected ? " (drift: desired host is missing)" : ""),
+          );
+        }
+      } catch (error) {
+        if (desired.installedHosts.includes(candidate)) drift = true;
+        console.log(
+          `${candidate}: unavailable (${errorCategory(error)})` +
+            (desired.installedHosts.includes(candidate) ? " (drift unknown)" : ""),
+        );
+      }
+    }
+    console.log(`Overall: ${drift ? "drift detected" : "no detected drift"}`);
+    return;
+  }
+  const status = await inspectHostStatus(host);
+  if (status.kind === "installed") {
+    console.log(`OpenSocrates ${status.version ?? "unknown"} is installed.`);
+  } else if (status.kind === "available") {
+    console.log(`OpenSocrates ${status.version ?? "unknown"} is available but not installed.`);
+  } else if (status.kind === "files-only") {
+    console.log(`OpenSocrates files are present but not registered: ${status.paths.root}`);
   } else {
-    console.log("The OpenSocrates marketplace is registered, but the plugin is missing.");
+    console.log("OpenSocrates is not installed.");
   }
 }
 
-async function removeInstalled() {
-  requireCodex();
-  const paths = managedPaths();
-  const entry = marketplaceEntry();
-  if (entry !== null && entryRoot(entry) !== paths.root) {
-    fail(`OpenSocrates is registered at an unmanaged location: ${entryRoot(entry)}`);
+function removalTransaction(preflight) {
+  return {
+    ...preflight,
+    backup: join(preflight.paths.parent, `.opensocrates.removed-${randomUUID()}`),
+    registrationRemoved: false,
+    backupCreated: false,
+  };
+}
+
+async function activateRemoval(transaction) {
+  const { host, previousEntry, previousState, paths } = transaction;
+  if (previousEntry !== null) {
+    transaction.registrationRemoved = true;
+    removeRegistration(host, previousEntry, previousState);
   }
-  const state = entry === null ? { kind: "missing", version: null } : pluginState();
-  removeRegistration(entry, state);
   if (await exists(paths.root)) {
-    await requireOwnedRoot(paths.root);
-    await rm(paths.root, { recursive: true });
+    await rename(paths.root, transaction.backup);
+    transaction.backupCreated = true;
   }
-  console.log("OpenSocrates was removed from Codex.");
 }
 
-export async function main(argv = process.argv.slice(2)) {
-  const options = parseCli(argv);
-  if (options.action === "help") {
-    showHelp();
-    return 0;
+async function rollbackRemoval(transaction) {
+  let restored = !transaction.backupCreated;
+  if (transaction.backupCreated && (await exists(transaction.backup))) {
+    restored = await recoveryStep(`restore the removed ${transaction.host} files`, async () => {
+      await requireOwnedRoot(transaction.backup, transaction.host);
+      await rename(transaction.backup, transaction.paths.root);
+    });
   }
-  if (options.action === "status") {
-    await showStatus();
-    return 0;
+  if (transaction.registrationRemoved && transaction.previousEntry !== null && restored) {
+    await recoveryStep(`restore the removed ${transaction.host} registration`, async () => {
+      addRegistration(
+        transaction.host,
+        transaction.paths.root,
+        transaction.previousState.kind === "installed",
+      );
+    });
   }
-  if (options.action === "remove") {
-    await removeInstalled();
-    return 0;
+}
+
+async function commitRemoval(transaction) {
+  if (transaction.backupCreated && (await exists(transaction.backup))) {
+    await requireOwnedRoot(transaction.backup, transaction.host);
+    await rm(transaction.backup, { recursive: true });
+  }
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+async function executablePath(name, environmentOverride) {
+  const override = process.env[environmentOverride];
+  if (override) {
+    const candidate = resolve(override);
+    await access(candidate, fsConstants.X_OK);
+    return candidate;
+  }
+  const which = run("/usr/bin/which", [name], { allowFailure: true });
+  const candidate = which.status === 0 ? which.stdout.trim() : "";
+  if (!candidate || !candidate.startsWith("/")) {
+    fail(`could not find an executable ${name} for the automatic updater`);
+  }
+  await access(candidate, fsConstants.X_OK);
+  return candidate;
+}
+
+function launchctlBinary() {
+  return process.env.OPENSOCRATES_LAUNCHCTL_BIN || "/bin/launchctl";
+}
+
+function launchctlDomain() {
+  if (typeof process.getuid !== "function") {
+    fail("automatic updates require a user launchd domain");
+  }
+  return `gui/${process.getuid()}`;
+}
+
+function launchAgentDocument(npx, channel, environment) {
+  const packageTag = channel === "next" ? "next" : "latest";
+  const arguments_ = [
+    npx,
+    "--yes",
+    `opensocrates@${packageTag}`,
+    "auto-update",
+    "run",
+  ];
+  const argumentsXml = arguments_
+    .map((argument) => `      <string>${xmlEscape(argument)}</string>`)
+    .join("\n");
+  const environmentEntries = Object.entries(environment).sort(([left], [right]) =>
+    left.localeCompare(right),
+  );
+  const environmentXml =
+    environmentEntries.length === 0
+      ? ""
+      : `\n    <key>EnvironmentVariables</key>\n    <dict>\n` +
+        environmentEntries
+          .map(
+            ([key, value]) =>
+              `      <key>${xmlEscape(key)}</key>\n` +
+              `      <string>${xmlEscape(value)}</string>`,
+          )
+          .join("\n") +
+        "\n    </dict>";
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${AUTO_UPDATE_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+${argumentsXml}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StartInterval</key>
+    <integer>${AUTO_UPDATE_POLL_SECONDS}</integer>
+    <key>ProcessType</key>
+    <string>Background</string>
+    <key>StandardOutPath</key>
+    <string>/dev/null</string>
+    <key>StandardErrorPath</key>
+    <string>/dev/null</string>${environmentXml}
+  </dict>
+</plist>
+`;
+}
+
+function launchAgentTarget() {
+  return `${launchctlDomain()}/${AUTO_UPDATE_LABEL}`;
+}
+
+function launchAgentLoaded() {
+  return run(launchctlBinary(), ["print", launchAgentTarget()], { allowFailure: true }).status === 0;
+}
+
+function stopLoadedLaunchAgent() {
+  if (!launchAgentLoaded()) return;
+  const stopped = run(launchctlBinary(), ["bootout", launchAgentTarget()], {
+    allowFailure: true,
+  });
+  if (stopped.status !== 0 && launchAgentLoaded()) {
+    const detail = stopped.stderr?.trim() || stopped.stdout?.trim() || `exit ${stopped.status}`;
+    fail(`could not stop the OpenSocrates LaunchAgent: ${detail}`);
+  }
+}
+
+async function updaterEnvironment(hosts, npx) {
+  const node = await executablePath("node", "OPENSOCRATES_NODE_BIN");
+  const environment = {
+    PATH: [...new Set([dirname(npx), dirname(node), "/usr/bin", "/bin", "/usr/sbin", "/sbin"])].join(
+      ":",
+    ),
+  };
+  for (const host of hosts) {
+    const key = host === "claude" ? "CLAUDE_BIN" : "CODEX_BIN";
+    const executable = await executablePath(host, key);
+    environment[key] = executable;
+    environment.PATH = [...new Set([dirname(executable), ...environment.PATH.split(":")])].join(":");
+  }
+  for (const key of ["CLAUDE_CONFIG_DIR", "CODEX_HOME", "OPENSOCRATES_STATE_DIR"]) {
+    if (process.env[key]) environment[key] = resolve(process.env[key]);
+  }
+  return environment;
+}
+
+async function installLaunchAgent(channel, hosts) {
+  if (process.platform !== "darwin" || process.arch !== "arm64") {
+    fail(
+      `automatic updates currently support darwin-arm64 only; detected ` +
+        `${process.platform}-${process.arch}`,
+    );
+  }
+  const paths = statePaths();
+  const npx = await executablePath("npx", "OPENSOCRATES_NPX_BIN");
+  const environment = await updaterEnvironment(hosts, npx);
+  let previousDocument = null;
+  if (await exists(paths.launchAgent)) {
+    const info = await lstat(paths.launchAgent);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      fail(`refusing to replace an unsafe LaunchAgent path: ${paths.launchAgent}`);
+    }
+    previousDocument = await readFile(paths.launchAgent, "utf8");
+  }
+  const document = launchAgentDocument(npx, channel, environment);
+  if (process.env.OPENSOCRATES_SKIP_LAUNCHCTL === "1") {
+    await atomicWritePrivateFile(paths.launchAgent, document);
+    return;
+  }
+  const wasLoaded = launchAgentLoaded();
+  if (wasLoaded) stopLoadedLaunchAgent();
+  await atomicWritePrivateFile(paths.launchAgent, document);
+  const launched = run(
+    launchctlBinary(),
+    ["bootstrap", launchctlDomain(), paths.launchAgent],
+    { allowFailure: true },
+  );
+  if (launched.status !== 0) {
+    if (previousDocument === null) {
+      await rm(paths.launchAgent, { force: true });
+    } else {
+      await atomicWritePrivateFile(paths.launchAgent, previousDocument);
+      if (wasLoaded) {
+        const restored = run(
+          launchctlBinary(),
+          ["bootstrap", launchctlDomain(), paths.launchAgent],
+          { allowFailure: true },
+        );
+        if (restored.status !== 0) {
+          console.error("warning: the previous OpenSocrates LaunchAgent could not be reloaded");
+        }
+      }
+    }
+    const detail = launched.stderr?.trim() || launched.stdout?.trim() || `exit ${launched.status}`;
+    fail(`could not enable the OpenSocrates LaunchAgent: ${detail}`);
+  }
+}
+
+async function disableLaunchAgent() {
+  const paths = statePaths();
+  const agentPresent = await exists(paths.launchAgent);
+  if (agentPresent) {
+    const info = await lstat(paths.launchAgent);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      fail(`refusing to remove an unsafe LaunchAgent path: ${paths.launchAgent}`);
+    }
+  }
+  if (process.env.OPENSOCRATES_SKIP_LAUNCHCTL !== "1") {
+    stopLoadedLaunchAgent();
+  }
+  if (agentPresent) await rm(paths.launchAgent);
+}
+
+async function disableAutoUpdateState(desired) {
+  await disableLaunchAgent();
+  return {
+    ...desired,
+    autoUpdate: { enabled: false, hosts: [], nextCheckAt: null },
+  };
+}
+
+async function runRemove(options) {
+  const desired = await readDesiredState();
+  const preflights = await preflightSelectedHosts(options, "remove", desired);
+  const removedHosts = preflights.map((item) => item.host);
+  const remainingHosts = desired.installedHosts.filter((host) => !removedHosts.includes(host));
+  const remainingAutoUpdateHosts = desired.autoUpdate.hosts.filter(
+    (host) => !removedHosts.includes(host),
+  );
+  const keepAutoUpdate = desired.autoUpdate.enabled && remainingAutoUpdateHosts.length > 0;
+  const nextDesired = {
+    ...desired,
+    installedHosts: remainingHosts,
+    activeVersion: remainingHosts.length === 0 ? null : desired.activeVersion,
+    autoUpdate: keepAutoUpdate
+      ? { ...desired.autoUpdate, hosts: remainingAutoUpdateHosts }
+      : { enabled: false, hosts: [], nextCheckAt: null },
+  };
+  const launchAgentPresent = await exists(statePaths().launchAgent);
+  const schedulerNeedsChange =
+    options.host === ALL_HOST ||
+    remainingHosts.length === 0 ||
+    launchAgentPresent !== keepAutoUpdate ||
+    desired.autoUpdate.hosts.some((host) => removedHosts.includes(host));
+  const transactions = preflights.map(removalTransaction);
+  let schedulerTouched = false;
+  try {
+    for (const transaction of transactions) await activateRemoval(transaction);
+    if (schedulerNeedsChange) {
+      schedulerTouched = true;
+      if (keepAutoUpdate) {
+        await installLaunchAgent(desired.channel, remainingAutoUpdateHosts);
+      } else {
+        await disableLaunchAgent();
+      }
+    }
+    await writeDesiredState(nextDesired);
+  } catch (error) {
+    for (const transaction of [...transactions].reverse()) await rollbackRemoval(transaction);
+    if (schedulerTouched) {
+      const schedulerRestored = await recoveryStep(
+        "restore the automatic updater after removal failure",
+        async () => {
+          if (desired.autoUpdate.enabled) {
+            await installLaunchAgent(desired.channel, desired.autoUpdate.hosts);
+          } else {
+            await disableLaunchAgent();
+          }
+        },
+      );
+      if (!schedulerRestored && desired.autoUpdate.enabled) {
+        await recoveryStep("record the disabled updater after removal failure", async () => {
+          await writeDesiredState({
+            ...desired,
+            autoUpdate: { enabled: false, hosts: [], nextCheckAt: null },
+          });
+        });
+      }
+    } else if (!nextDesired.autoUpdate.enabled && desired.autoUpdate.enabled) {
+      await recoveryStep("record the disabled updater after removal failure", async () => {
+        await writeDesiredState({
+          ...desired,
+          autoUpdate: { enabled: false, hosts: [], nextCheckAt: null },
+        });
+      });
+    }
+    throw error;
+  }
+  for (const transaction of transactions) await commitRemoval(transaction);
+  for (const host of removedHosts) {
+    console.log(`OpenSocrates was removed from ${host === "claude" ? "Claude" : "Codex"}.`);
+  }
+  if (removedHosts.length === 0) console.log("OpenSocrates is not installed on any managed host.");
+}
+
+async function enableAutoUpdate(options) {
+  const previous = await readDesiredState();
+  const preflights = new Map();
+  let installedHosts = [...previous.installedHosts];
+  if (installedHosts.length === 0) {
+    const discoveryOptions = { ...options, host: ALL_HOST };
+    const discovered = await preflightSelectedHosts(discoveryOptions, "update", previous);
+    for (const item of discovered) {
+      if (item.previousState.kind === "installed") {
+        preflights.set(item.host, item);
+        installedHosts.push(item.host);
+      }
+    }
+  }
+  let updateHosts = options.host === ALL_HOST ? [...installedHosts] : [options.host];
+  if (updateHosts.length === 0) {
+    fail("install OpenSocrates on at least one host before enabling automatic updates");
+  }
+  for (const host of updateHosts) {
+    const preflight = preflights.get(host) ?? (await preflightHost(host, "update"));
+    if (preflight.previousState.kind !== "installed") {
+      fail(`OpenSocrates is not installed on ${host}`);
+    }
+    if (typeof preflight.previousState.version !== "string") {
+      fail(`cannot determine the installed OpenSocrates version on ${host}`);
+    }
+    preflights.set(host, preflight);
+    installedHosts.push(host);
+  }
+  installedHosts = [...new Set(installedHosts)].sort();
+  updateHosts = [...new Set(updateHosts)].sort();
+  let activeVersion = previous.activeVersion;
+  if (activeVersion === null) {
+    const observedVersions = new Set();
+    for (const host of installedHosts) {
+      const preflight = preflights.get(host) ?? (await preflightHost(host, "update"));
+      if (
+        preflight.previousState.kind !== "installed" ||
+        typeof preflight.previousState.version !== "string"
+      ) {
+        fail(`cannot determine the installed OpenSocrates version on ${host}`);
+      }
+      preflights.set(host, preflight);
+      observedVersions.add(preflight.previousState.version);
+    }
+    if (observedVersions.size !== 1) {
+      fail(
+        "installed hosts do not share one known version; run update --host all before enabling automatic updates",
+      );
+    }
+    [activeVersion] = observedVersions;
+  }
+  const desired = {
+    ...previous,
+    channel: options.channel,
+    installedHosts,
+    activeVersion,
+    updatePolicy: {
+      intervalHours: options.intervalHours,
+      allowMajor: options.allowMajor,
+    },
+    autoUpdate: {
+      enabled: true,
+      hosts: updateHosts,
+      nextCheckAt: nowIso(),
+    },
+  };
+  await writeDesiredState(desired);
+  try {
+    await installLaunchAgent(options.channel, desired.autoUpdate.hosts);
+  } catch (error) {
+    await writeDesiredState(previous);
+    throw error;
   }
+  console.log(
+    `Automatic updates enabled for ${desired.autoUpdate.hosts.join(", ")} on the ` +
+      `${desired.channel} channel every ${desired.updatePolicy.intervalHours} hours with jitter.`,
+  );
+  console.log(
+    desired.updatePolicy.allowMajor
+      ? "Automatic major-version upgrades are enabled."
+      : "Automatic major-version upgrades remain disabled.",
+  );
+}
+
+async function showAutoUpdateStatus() {
+  const desired = await readDesiredState();
+  const agentPresent = await exists(statePaths().launchAgent);
+  console.log(`Automatic updates: ${desired.autoUpdate.enabled ? "enabled" : "disabled"}`);
+  console.log(`LaunchAgent: ${agentPresent ? "installed" : "not installed"}`);
+  console.log(`Channel: ${desired.channel}`);
+  console.log(`Installed hosts: ${desired.installedHosts.join(", ") || "none"}`);
+  console.log(`Automatic-update hosts: ${desired.autoUpdate.hosts.join(", ") || "none"}`);
+  console.log(`Interval: ${desired.updatePolicy.intervalHours} hours with jitter`);
+  console.log(`Major upgrades: ${desired.updatePolicy.allowMajor ? "allowed" : "blocked"}`);
+  console.log(`Next check: ${desired.autoUpdate.nextCheckAt ?? "not scheduled"}`);
+  console.log(`Last check: ${desired.lastCheckAt ?? "never"}`);
+  console.log(`Last successful update: ${desired.lastSuccessfulUpdateAt ?? "never"}`);
+}
+
+async function disableAutoUpdate() {
+  const desired = await readDesiredState();
+  await writeDesiredState(await disableAutoUpdateState(desired));
+  console.log("Automatic updates are disabled and the LaunchAgent was removed.");
+}
+
+async function runScheduledUpdate(options) {
+  let desired = await readDesiredState();
+  if (!desired.autoUpdate.enabled) {
+    console.log("Automatic updates are disabled.");
+    return;
+  }
+  const scheduledAt = Date.parse(desired.autoUpdate.nextCheckAt ?? "");
+  if (!options.force && Number.isFinite(scheduledAt) && scheduledAt > Date.now()) {
+    console.log(`The next automatic update check is scheduled for ${desired.autoUpdate.nextCheckAt}.`);
+    return;
+  }
+  const checkedAt = nowIso();
+  const hosts = desired.autoUpdate.hosts;
+  if (hosts.length === 0) {
+    fail("the automatic updater has no selected hosts in desired state");
+  }
+  const next = nextCheckAt(desired.updatePolicy.intervalHours);
+  const currentMajor = majorVersion(desired.activeVersion);
+  const availableMajor = majorVersion(PRODUCT_VERSION);
   if (
-    ["install", "update"].includes(options.action) &&
-    (process.platform !== "darwin" || process.arch !== "arm64")
+    !desired.updatePolicy.allowMajor &&
+    currentMajor !== null &&
+    availableMajor !== null &&
+    availableMajor > currentMajor
   ) {
+    desired = await writeDesiredState({
+      ...desired,
+      availableVersion: PRODUCT_VERSION,
+      lastCheckAt: checkedAt,
+      autoUpdate: { ...desired.autoUpdate, nextCheckAt: next },
+    });
+    await writeAutoUpdateReceipt({
+      version: PRODUCT_VERSION,
+      checkedAt,
+      hosts: hosts.map((host) => ({ host, result: "blocked-major" })),
+      result: "blocked",
+      errorCategory: "major-policy",
+    });
+    console.log(`OpenSocrates ${PRODUCT_VERSION} is available but blocked by the major-version policy.`);
+    return;
+  }
+  try {
+    const ready = [];
+    for (const host of hosts) ready.push(await preflightHost(host, "update"));
+    const alreadyCurrent =
+      desired.activeVersion === PRODUCT_VERSION &&
+      ready.every(
+        (item) =>
+          item.previousState.kind === "installed" && item.previousState.version === PRODUCT_VERSION,
+      );
+    if (!alreadyCurrent) {
+      if (hosts.length === SUPPORTED_HOSTS.length) {
+        await runInstallOrUpdate({ ...options, host: ALL_HOST }, "update");
+      } else {
+        const [host] = hosts;
+        const local = localAssetInputs(options, host);
+        await runInstallOrUpdate(
+          { ...options, host, asset: local.asset, checksum: local.checksum },
+          "update",
+        );
+      }
+    }
+    const refreshed = await readDesiredState();
+    desired = await writeDesiredState({
+      ...refreshed,
+      availableVersion: PRODUCT_VERSION,
+      lastCheckAt: checkedAt,
+      lastSuccessfulUpdateAt: alreadyCurrent
+        ? refreshed.lastSuccessfulUpdateAt
+        : checkedAt,
+      autoUpdate: { ...refreshed.autoUpdate, nextCheckAt: next },
+    });
+    await writeAutoUpdateReceipt({
+      version: PRODUCT_VERSION,
+      checkedAt,
+      hosts: hosts.map((host) => ({ host, result: alreadyCurrent ? "current" : "updated" })),
+      result: alreadyCurrent ? "no-update" : "updated",
+      errorCategory: null,
+    });
+    console.log(
+      alreadyCurrent
+        ? `OpenSocrates ${PRODUCT_VERSION} is already current on every managed host.`
+        : `OpenSocrates ${PRODUCT_VERSION} was reconciled across ${hosts.join(", ")}.`,
+    );
+  } catch (error) {
+    await recoveryStep("record the failed automatic update", async () => {
+      desired = await writeDesiredState({
+        ...(await readDesiredState()),
+        availableVersion: PRODUCT_VERSION,
+        lastCheckAt: checkedAt,
+        autoUpdate: { ...desired.autoUpdate, nextCheckAt: next },
+      });
+      await writeAutoUpdateReceipt({
+        version: PRODUCT_VERSION,
+        checkedAt,
+        hosts: hosts.map((host) => ({ host, result: "failed" })),
+        result: "failed",
+        errorCategory: errorCategory(error),
+      });
+    });
+    throw error;
+  }
+}
+
+function requireSupportedPlatform() {
+  if (process.platform !== "darwin" || process.arch !== "arm64") {
     fail(
       `OpenSocrates ${PRODUCT_VERSION} prebuilt installation supports darwin-arm64 only; ` +
         `detected ${process.platform}-${process.arch}`,
     );
   }
+}
 
-  const prepared = await prepareVerifiedPackage(options);
+async function verifyPackages(options) {
+  const hosts = options.host === ALL_HOST ? SUPPORTED_HOSTS : [options.host];
+  const prepared = await prepareVerifiedPackages(options, hosts);
   try {
-    console.log(
-      `Verified OpenSocrates ${PRODUCT_VERSION} release and ${prepared.checkedFiles} package files.`,
+    for (const item of prepared) {
+      console.log(
+        `${item.host}: verified OpenSocrates ${PRODUCT_VERSION} release and ` +
+          `${item.checkedFiles} package files.`,
+      );
+    }
+  } finally {
+    await Promise.all(
+      prepared.map((item) => rm(item.scratch, { recursive: true, force: true })),
     );
-    if (options.action === "verify") {
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = parseCli(argv);
+  if (options.action === "help") {
+    showHelp();
+    return 0;
+  }
+  if (options.action === "status") {
+    await showStatus(options.host);
+    return 0;
+  }
+  if (options.action === "verify") {
+    await verifyPackages(options);
+    return 0;
+  }
+  if (options.action === "auto-update" && options.autoUpdateAction === "status") {
+    await showAutoUpdateStatus();
+    return 0;
+  }
+  return withOperationLock(async () => {
+    if (options.action === "remove") {
+      await runRemove(options);
+      return 0;
+    }
+    if (options.action === "auto-update") {
+      if (options.autoUpdateAction === "enable") {
+        await enableAutoUpdate(options);
+      } else if (options.autoUpdateAction === "disable") {
+        await disableAutoUpdate();
+      } else {
+        requireSupportedPlatform();
+        await runScheduledUpdate(options);
+      }
       return 0;
     }
-    await installVerifiedPackage(prepared.pluginRoot, options.action);
+    requireSupportedPlatform();
+    await runInstallOrUpdate(options, options.action);
     return 0;
-  } finally {
-    await rm(prepared.scratch, { recursive: true, force: true });
-  }
+  });
 }
 
 let invokedDirectly = false;