external-subagent 0.1.0

package/cli/install/npm-hook.mjs

@@ -0,0 +1,49 @@
+import { productPaths } from '../paths.mjs';
+import { npmUpdateCoordination } from './reconcile.mjs';
+import { updateCommand } from '../commands/update.mjs';
+import { callDaemon } from '../rpc.mjs';
+
+// npm runs this hook after replacing an installed package.  A package that
+// has never been initialized must remain stage-only; only an initialized
+// installation with a locally detectable active-version drift enters the
+// existing reconcile owner.  No provider probe or daemon RPC is performed by
+// the detection itself.
+const paths = productPaths();
+const globalInstall = process.env.npm_config_global === 'true';
+let detected;
+try {
+  detected = npmUpdateCoordination(paths);
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({ external_subagent: 'postinstall', coordinated: false, error: { code: error.code || 'UPDATE_STATE_READ_FAILED', message: error.message } })}\n`);
+  process.exit(1);
+}
+
+if (!globalInstall || !detected.initialized || !detected.update_pending) {
+  process.stdout.write(`${JSON.stringify({ external_subagent: 'postinstall', ...detected })}\n`);
+  process.exit(0);
+}
+
+let interrupted = false;
+let handlingSignal = null;
+const abortOnSignal = (signal) => {
+  if (handlingSignal) return;
+  interrupted = true;
+  handlingSignal = callDaemon(paths.socket, 'drain-abort', {})
+    .catch(() => null)
+    .finally(() => { process.exitCode = signal === 'SIGINT' ? 130 : 143; });
+};
+process.once('SIGINT', () => abortOnSignal('SIGINT'));
+process.once('SIGTERM', () => abortOnSignal('SIGTERM'));
+
+try {
+  const result = await updateCommand(paths, ['reconcile'], { drainTimeoutMs: 30_000 });
+  if (interrupted) {
+    if (handlingSignal) await handlingSignal;
+    process.exit(process.exitCode || 130);
+  }
+  process.stdout.write(`${JSON.stringify({ external_subagent: 'postinstall', coordinated: true, result })}\n`);
+} catch (error) {
+  if (handlingSignal) await handlingSignal;
+  process.stderr.write(`${JSON.stringify({ external_subagent: 'postinstall', coordinated: false, error: { code: error.code || 'UPDATE_FAILED', message: error.message } })}\n`);
+  process.exitCode = 1;
+}

package/cli/install/path.mjs

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { nativeBinary } from './layout.mjs';
+
+// The launchd/GUI environment does not inherit the interactive shell PATH.
+// Every managed entry point therefore resolves to an absolute file inside the
+// installed package, and the fixed PATH below is only what the daemon itself
+// may use to locate system tools.  This module never writes user profiles;
+// PATH findings are reported so an explicit repair stays a user decision.
+export const LAUNCHD_FIXED_PATH = '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin';
+
+export function which(name, env = process.env) {
+  const searchPath = (env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const dir of searchPath) {
+    const candidate = path.join(dir, name);
+    try {
+      const stat = fs.statSync(candidate);
+      if (stat.isFile() && (stat.mode & 0o111) !== 0) return candidate;
+    } catch { /* keep scanning */ }
+  }
+  return null;
+}
+
+export function pathReport(options = {}) {
+  const env = options.env || process.env;
+  const daemon = nativeBinary('external-subagentd');
+  const facade = nativeBinary('external-subagent-mcp');
+  return {
+    shell: {
+      path: env.PATH || null,
+      cli_on_path: which('external-subagent', env),
+      mcp_on_path: which('external-subagent-mcp', env),
+    },
+    launchd: {
+      path: LAUNCHD_FIXED_PATH,
+      daemon_entry: daemon,
+      mcp_entry: facade,
+    },
+    stable_entries_absolute: Boolean(daemon && facade && path.isAbsolute(daemon) && path.isAbsolute(facade)),
+    shell_profile_writes: 'none',
+    node_executable: process.execPath,
+  };
+}

package/cli/install/payload.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../errors.mjs';
+import { sha256 } from '../fs-atomic.mjs';
+import { NATIVE_DIR_NAME, PRODUCT_NAME } from '../constants.mjs';
+import {
+  NATIVE_PLATFORM, cliVersion, nativePayloadDir, nativePlatform, packageVersion, payloadManifestPath,
+} from './layout.mjs';
+
+const MH_MAGIC_64 = 0xfeedfacf;
+const CPU_TYPE_ARM64 = 0x0100000c;
+
+export function machoArch(bytes) {
+  if (bytes.length < 8) return null;
+  if (bytes.readUInt32LE(0) !== MH_MAGIC_64) return null;
+  return bytes.readUInt32LE(4) === CPU_TYPE_ARM64 ? 'arm64' : null;
+}
+
+export function readPayloadManifest(options = {}) {
+  const platform = options.platform || nativePlatform();
+  const root = options.root || undefined;
+  const file = root ? path.join(root, 'npm', NATIVE_DIR_NAME, platform || '', 'payload.json') : payloadManifestPath(platform);
+  if (file === null || !fs.existsSync(file)) {
+    throw new CliError('PAYLOAD_MANIFEST_MISSING', `the ${platform || 'current'} platform payload manifest is missing from this package`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new CliError('PAYLOAD_MANIFEST_INVALID', `payload manifest is not valid JSON: ${error.message}`);
+  }
+  if (manifest?.schema_version !== 1 || manifest?.product !== PRODUCT_NAME || !Array.isArray(manifest.files)) {
+    throw new CliError('PAYLOAD_MANIFEST_INVALID', 'payload manifest identity or file table is invalid');
+  }
+  return manifest;
+}
+
+// Verify the staged native payload: the manifest, package, and CLI versions
+// must agree, and every binary must exist with release permissions and a
+// little-endian Mach-O arm64 image.  A failed verification is an installation
+// defect, never a silent downgrade path.
+export function verifyPayload(options = {}) {
+  const platform = options.platform || nativePlatform();
+  if (platform === null) {
+    throw new CliError('UNSUPPORTED_PAYLOAD_PLATFORM', `no native payload exists for ${process.platform}-${process.arch}; supported platforms: ${NATIVE_PLATFORM}`);
+  }
+  const manifest = readPayloadManifest({ platform, root: options.root });
+  if (manifest.platform !== platform) {
+    throw new CliError('PAYLOAD_PLATFORM_MISMATCH', `payload manifest declares ${manifest.platform}, expected ${platform}`);
+  }
+  let candidatePackage = packageVersion();
+  if (options.root) {
+    try { candidatePackage = JSON.parse(fs.readFileSync(path.join(options.root, 'package.json'), 'utf8')).version; }
+    catch (error) { throw new CliError('PAYLOAD_PACKAGE_INVALID', `candidate package manifest is unavailable: ${error.message}`); }
+  }
+  const versions = { package: candidatePackage, cli: options.root ? candidatePackage : cliVersion(), payload: manifest.version };
+  if (versions.package !== versions.cli || versions.payload !== versions.cli) {
+    throw new CliError('PAYLOAD_VERSION_MISMATCH', `payload ${versions.payload}, package ${versions.package}, and CLI ${versions.cli} versions disagree`);
+  }
+  const dir = options.root ? path.join(options.root, 'npm', NATIVE_DIR_NAME, platform) : nativePayloadDir(platform);
+  const files = manifest.files.map((record) => {
+    if (!record || typeof record.name !== 'string' || path.basename(record.name) !== record.name || record.name.includes('..')) {
+      throw new CliError('PAYLOAD_MANIFEST_INVALID', 'payload file name must be a direct child');
+    }
+    const target = path.join(dir, record.name);
+    let stat;
+    try { stat = fs.statSync(target); } catch (error) {
+      throw new CliError('PAYLOAD_FILE_MISSING', `native payload file is missing: ${record.name} (${error.code})`);
+    }
+    if (!stat.isFile() || fs.lstatSync(target).isSymbolicLink() || (stat.mode & 0o777) !== 0o755) {
+      throw new CliError('PAYLOAD_PERMISSIONS_INVALID', `native payload file ${record.name} must be a regular file with mode 755`);
+    }
+    const bytes = fs.readFileSync(target);
+    if (bytes.length !== record.bytes || sha256(bytes) !== record.sha256) {
+      throw new CliError('PAYLOAD_DIGEST_MISMATCH', `native payload file ${record.name} does not match the release digest`);
+    }
+    const arch = machoArch(bytes);
+    if (arch !== 'arm64') {
+      throw new CliError('PAYLOAD_ARCH_UNSUPPORTED', `native payload file ${record.name} is not a Mach-O arm64 image`);
+    }
+    return { name: record.name, bytes: bytes.length, mode: '755', sha256: record.sha256, arch };
+  });
+  return { status: 'verified', platform, version: manifest.version, files };
+}

package/cli/install/plugin-stage.mjs

@@ -0,0 +1,232 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { CliError } from '../errors.mjs';
+import { MCP_BIN_NAME } from '../constants.mjs';
+import { nativeBinary, PLUGIN_NAME } from './layout.mjs';
+
+// Host-agnostic plugin staging: validating the shipped plugin source,
+// materializing it into a product-owned staging tree, and fingerprinting
+// that tree.  Every host binding (codex, zcode) stages the same source and
+// pins the same MCP binding — the facade command plus the daemon socket —
+// into the staged `.mcp.json`; only the registration surface around the
+// staged tree differs per host.
+//
+// Publishing is a REPLACEMENT, never an overlay (AUD-002): the candidate
+// tree is built, parsed, and rewritten with its final binding paths in an
+// owned sibling directory BESIDE the target — never inside the live managed
+// tree — so a file deleted from the source disappears from the published
+// tree and an invalid candidate never moves a managed byte.  The publish
+// itself is two same-directory renames (target -> retained prior tree,
+// candidate -> target); the prior tree survives until the caller commits,
+// and restore() puts it back when the host binding transaction fails.  The
+// boundary is honest, not journaling: a process crash between the two
+// publish renames can leave the target absent with the prior tree at its
+// sibling path, and nothing here detects or repairs that automatically.
+
+export function pluginManifest(source) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(source, '.codex-plugin', 'plugin.json'), 'utf8'));
+  if (manifest.name !== PLUGIN_NAME || manifest.skills !== './skills/' || manifest.mcpServers !== './.mcp.json') {
+    throw new CliError('INVALID_PLUGIN_SOURCE', 'plugin manifest identity or relative paths are invalid');
+  }
+  return manifest;
+}
+
+// Digest of the staged plugin tree.  Valid symlinks are followed: the linked
+// content is hashed under the link's own relative path, so an edit of a
+// target that lives OUTSIDE the traversed root and is reachable only through
+// the link still changes the digest.  Dangling links are skipped (there is
+// no content to hash) and directory loops/diamonds are bounded by resolved
+// real path plus a depth backstop, so the walk always terminates.
+export function treeDigest(root) {
+  const hash = crypto.createHash('sha256');
+  const seen = new Set([fs.realpathSync(root)]);
+  const walk = (dir, depth) => {
+    if (depth > 64) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const target = path.join(dir, entry.name);
+      const isLink = entry.isSymbolicLink();
+      let resolvedStat = entry;
+      if (isLink) {
+        try { resolvedStat = fs.statSync(target); } catch { continue; }
+      }
+      if (resolvedStat.isDirectory()) {
+        const real = fs.realpathSync(target);
+        if (seen.has(real)) continue;
+        seen.add(real);
+        walk(target, depth + 1);
+      } else if (resolvedStat.isFile() && entry.name !== '.mcp.json') {
+        hash.update(path.relative(root, target));
+        hash.update(fs.readFileSync(target));
+      }
+    }
+  };
+  walk(root, 0); return hash.digest('hex');
+}
+
+// `binding` overrides what gets pinned as the staged MCP command.  Codex
+// hosts spawn the native facade directly (the default); hosts with
+// restricted spawn environments (zcode) pass an interpreter command plus
+// args — e.g. the installing node running the staged stdio bridge.  A
+// binding may also carry `timeoutMs`, pinned onto the server entry for
+// hosts whose MCP client caps tool calls at a short default (zcode:
+// 30000ms) that a long `external_subagent_wait` would exceed.
+//
+// The publish protocol keeps two private sibling trees beside the target,
+// named `.<target>.candidate.<pid>.<uuid>` and `.<target>.prior.<pid>.<uuid>`.
+
+const siblingSuffix = () => `${process.pid}.${crypto.randomUUID()}`;
+
+function discardTree(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort cleanup */ }
+}
+
+// Parse and rewrite the CANDIDATE tree's `.mcp.json` for the final binding
+// paths.  This runs before any managed byte moves, so an unreadable or
+// incomplete MCP payload fails the refresh while the live tree stays intact.
+function bindCandidate(candidate, paths, command, args, timeoutMs) {
+  const mcpPath = path.join(candidate, '.mcp.json');
+  let mcp;
+  try {
+    mcp = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+  } catch (error) {
+    throw new CliError('INVALID_PLUGIN_SOURCE', `plugin MCP config is not readable JSON (${error.message})`);
+  }
+  const server = mcp.mcpServers?.external_subagent;
+  if (!server) throw new CliError('INVALID_PLUGIN_SOURCE', 'plugin MCP server is missing');
+  server.command = command;
+  if (args !== null) server.args = args;
+  if (timeoutMs !== null) server.timeoutMs = timeoutMs;
+  server.env = { ...(server.env || {}), ZCODE_AGENTD_SOCKET: paths.socket };
+  fs.writeFileSync(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`, { mode: 0o600 });
+}
+
+// Prepare a validated replacement for `staging` (AUD-002).  Ownership of an
+// existing managed tree is checked first; publish() then builds the
+// candidate beside the target — same parent directory, so every swap step
+// is a rename — and the returned handle coordinates the publish with the
+// caller's host binding transaction: restore() undoes a published swap,
+// complete() drops the retained prior tree once the transaction committed.
+export function preparePluginStage(source, staging, paths, binding = {}) {
+  const command = binding.command || nativeBinary(MCP_BIN_NAME);
+  const args = Array.isArray(binding.args) ? binding.args : null;
+  const timeoutMs = Number.isFinite(binding.timeoutMs) ? binding.timeoutMs : null;
+  if (fs.existsSync(staging)) {
+    const existing = path.join(staging, '.codex-plugin', 'plugin.json');
+    if (!fs.existsSync(existing) || JSON.parse(fs.readFileSync(existing, 'utf8')).name !== PLUGIN_NAME) {
+      throw new CliError('PLUGIN_STAGING_CONFLICT', `staging path is not managed by ${PLUGIN_NAME}`);
+    }
+    // Managed staging is refreshable: skill/docs may have changed since the
+    // last install. Keep the ownership check above, then replace its contents
+    // from the current source.
+    const priorMcp = JSON.parse(fs.readFileSync(path.join(staging, '.mcp.json'), 'utf8'));
+    const priorServer = priorMcp.mcpServers?.external_subagent;
+    const priorCommand = priorServer?.command;
+    // Refreshable when the prior binding is any form this product wrote:
+    // the requested binding, the native facade (earlier managed binding),
+    // or the shipped placeholder.
+    const managedCommands = new Set([command, nativeBinary(MCP_BIN_NAME), '__EXTERNAL_SUBAGENT_MCP_EXECUTABLE__']);
+    const commandMatches = managedCommands.has(priorCommand);
+    // An interpreter-form binding also pins its script inside the staged
+    // tree itself, so a prior args[0] living in this staging proves the
+    // binding is ours even after the pinned interpreter path drifted
+    // (e.g. a Homebrew node upgrade replaced the Cellar path).
+    const priorArgs = Array.isArray(priorServer?.args) ? priorServer.args : [];
+    const argsOwned = typeof priorArgs[0] === 'string'
+      && path.resolve(priorArgs[0]).startsWith(`${path.resolve(staging)}${path.sep}`);
+    // Args are only load-bearing for interpreter bindings (e.g. node running
+    // the staged bridge); a prior native-form binding carried none, and the
+    // rewrite below installs the requested form regardless.
+    const argsMatch = args === null || priorCommand !== command || JSON.stringify(priorArgs) === JSON.stringify(args);
+    if (!priorServer || (!commandMatches && !argsOwned) || !argsMatch || priorServer.env?.ZCODE_AGENTD_SOCKET !== paths.socket) {
+      throw new CliError('PLUGIN_STAGING_CONFLICT', 'staging MCP binding differs from the managed product endpoint');
+    }
+  }
+  const parent = path.dirname(staging);
+  const candidate = path.join(parent, `.${path.basename(staging)}.candidate.${siblingSuffix()}`);
+  const prior = path.join(parent, `.${path.basename(staging)}.prior.${siblingSuffix()}`);
+  let published = false;
+  return {
+    staging,
+    // Build and validate the candidate, then swap it in with same-directory
+    // renames: target -> prior (when a managed tree exists), candidate ->
+    // target.  If the second rename fails, the first is undone before the
+    // error surfaces, so publish either replaces the target completely or
+    // leaves the prior tree live at the target path.
+    publish() {
+      fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+      try {
+        fs.cpSync(source, candidate, { recursive: true });
+        bindCandidate(candidate, paths, command, args, timeoutMs);
+        if (fs.existsSync(staging)) {
+          fs.renameSync(staging, prior);
+          try {
+            fs.renameSync(candidate, staging);
+          } catch (error) {
+            try { fs.renameSync(prior, staging); } catch { /* prior stays at its sibling path; see the crash boundary */ }
+            throw error;
+          }
+        } else {
+          fs.renameSync(candidate, staging);
+        }
+        published = true;
+      } catch (error) {
+        discardTree(candidate);
+        throw error;
+      }
+    },
+    // Undo a published swap: drop the freshly published tree and put the
+    // retained prior tree back (or remove the target entirely when this was
+    // a first install).  Best-effort by design — the caller's original
+    // failure is the one that must surface, so secondary cleanup errors
+    // here are suppressed rather than thrown; the boolean return reports
+    // whether the pre-publish state was actually restored, so the caller
+    // can attach an unrestored staging tree to its error chain (AUD-002)
+    // instead of letting the failed restore pass silently.  A restore that
+    // cannot put the prior tree back never discards it: the retained
+    // sibling stays on disk as the last-good recovery material.
+    restore() {
+      if (!published) return true;
+      const hadPrior = fs.existsSync(prior);
+      discardTree(staging);
+      if (hadPrior) {
+        try { fs.renameSync(prior, staging); } catch { /* prior stays at its sibling path; see the crash boundary */ }
+      }
+      published = false;
+      return hadPrior ? !fs.existsSync(prior) : !fs.existsSync(staging);
+    },
+    // Drop the retained prior tree once the host transaction committed; a
+    // cleanup failure never fails a verified install.
+    complete() {
+      published = false;
+      discardTree(prior);
+    },
+  };
+}
+
+// One-shot form for callers without a host transaction around the swap.
+export function stagePlugin(source, staging, paths, binding = {}) {
+  const staged = preparePluginStage(source, staging, paths, binding);
+  staged.publish();
+  staged.complete();
+}
+
+// AUD-002: a failed install must still attempt every independent restore.
+// Each attempt runs guarded — one restore throwing (a host config or
+// marketplace parent that STAYS read-only, say) neither skips the remaining
+// restores nor replaces the caller's original error.  Attempts that failed
+// are attached to that error as `restoreFailures: [{ resource, code,
+// message }]`, so the unrestored-resource list rides the thrown error chain
+// where callers and tests can assert it; this is not a log line.
+export function guardedRestores(error, attempts) {
+  const restoreFailures = [];
+  for (const attempt of attempts) {
+    try {
+      attempt.restore();
+    } catch (restoreError) {
+      restoreFailures.push({ resource: attempt.resource, code: restoreError.code || 'RESTORE_FAILED', message: restoreError.message });
+    }
+  }
+  if (restoreFailures.length > 0) error.restoreFailures = restoreFailures;
+  return error;
+}

package/cli/install/reconcile.mjs

@@ -0,0 +1,209 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../errors.mjs';
+import { atomicWrite, jsonBytes, readOptional } from '../fs-atomic.mjs';
+import { installMcp, installPlugin } from './codex.mjs';
+import { packageVersion } from './layout.mjs';
+
+// D08: the single owner of the global installed-Codex-homes registry.  The
+// registry records every Codex home this product has successfully claimed via
+// an explicit init or plugin install; reconcile only ever writes homes that
+// are both registered and actually writable, so unrelated CODEX_HOME
+// directories are never touched.  A corrupted registry is atomically replaced
+// and reported as a recoverable error instead of aborting the caller.
+
+const REGISTRY_SCHEMA_VERSION = 1;
+
+export function codexHomesRegistryPath(paths) {
+  return path.join(paths.data, 'codex-homes.json');
+}
+
+function emptyRegistry() {
+  return { schema_version: REGISTRY_SCHEMA_VERSION, product: 'external-subagent', homes: [] };
+}
+
+function resolveHome(home) {
+  if (typeof home !== 'string' || home.length === 0) throw new CliError('INVALID_ARGUMENT', 'codex home must be a non-empty string', 2);
+  const absolute = path.resolve(home);
+  try { return fs.realpathSync(absolute); } catch { return absolute; }
+}
+
+function normalizeEntry(entry) {
+  if (!entry || typeof entry.home !== 'string') throw new CliError('CODEX_HOMES_REGISTRY_INVALID', 'registry entry is missing its home path');
+  const hasMode = Object.prototype.hasOwnProperty.call(entry, 'binding_mode');
+  if (hasMode && entry.binding_mode !== 'mcp' && entry.binding_mode !== 'plugin') {
+    throw new CliError('CODEX_HOMES_REGISTRY_INVALID', 'registry entry has an unsupported binding mode');
+  }
+  return {
+    home: entry.home,
+    claimed_at_ms: Number.isInteger(entry.claimed_at_ms) ? entry.claimed_at_ms : null,
+    version: typeof entry.version === 'string' ? entry.version : null,
+    digest: typeof entry.digest === 'string' ? entry.digest : null,
+    // Schema-1 claims were plugin-only; default omitted modes accordingly.
+    binding_mode: hasMode ? entry.binding_mode : 'plugin',
+    last_sync_ms: Number.isInteger(entry.last_sync_ms) ? entry.last_sync_ms : null,
+    last_status: typeof entry.last_status === 'string' ? entry.last_status : null,
+  };
+}
+
+function parseRegistry(bytes, file) {
+  const doc = JSON.parse(bytes.toString('utf8'));
+  if (doc?.schema_version !== REGISTRY_SCHEMA_VERSION || doc?.product !== 'external-subagent' || !Array.isArray(doc.homes)) {
+    throw new CliError('CODEX_HOMES_REGISTRY_INVALID', 'registry identity or homes table is invalid');
+  }
+  const registry = emptyRegistry();
+  registry.homes = doc.homes.map(normalizeEntry);
+  return registry;
+}
+
+export function loadCodexHomes(paths) {
+  const file = codexHomesRegistryPath(paths);
+  const bytes = readOptional(file);
+  if (bytes === null) return { registry: emptyRegistry(), recovery: null };
+  try {
+    return { registry: parseRegistry(bytes, file), recovery: null };
+  } catch (error) {
+    // Corrupted registry: preserve the bytes for inspection, atomically stage
+    // a fresh registry, and report a recoverable error to the caller.
+    const backup = `${file}.corrupt-${Date.now()}`;
+    try { fs.renameSync(file, backup); } catch (renameError) {
+      throw new CliError('CODEX_HOMES_REGISTRY_CORRUPT', `registry is corrupted and could not be preserved: ${renameError.message}`);
+    }
+    atomicWrite(file, jsonBytes(emptyRegistry()));
+    return {
+      registry: emptyRegistry(),
+      recovery: { status: 'recovered', code: 'CODEX_HOMES_REGISTRY_CORRUPT', backup, error: error.message },
+    };
+  }
+}
+
+function persistRegistry(paths, registry) {
+  atomicWrite(codexHomesRegistryPath(paths), jsonBytes(registry));
+}
+
+export function registerCodexHome(paths, home, meta = {}) {
+  const { registry, recovery } = loadCodexHomes(paths);
+  const resolved = resolveHome(home);
+  const existing = registry.homes.find((entry) => entry.home === resolved);
+  let entry;
+  if (existing) {
+    entry = existing;
+    if (typeof meta.version === 'string') entry.version = meta.version;
+    if (typeof meta.digest === 'string') entry.digest = meta.digest;
+    if (typeof meta.status === 'string') entry.last_status = meta.status;
+    if (meta.binding_mode === 'mcp' || meta.binding_mode === 'plugin') entry.binding_mode = meta.binding_mode;
+  } else {
+    entry = {
+      home: resolved,
+      claimed_at_ms: Date.now(),
+      version: typeof meta.version === 'string' ? meta.version : null,
+      digest: typeof meta.digest === 'string' ? meta.digest : null,
+      binding_mode: meta.binding_mode === 'mcp' ? 'mcp' : 'plugin',
+      last_sync_ms: null,
+      last_status: typeof meta.status === 'string' ? meta.status : 'claimed',
+    };
+    registry.homes.push(entry);
+  }
+  persistRegistry(paths, registry);
+  return { registered: true, home: resolved, deduplicated: Boolean(existing), homes: registry.homes.length, recovery };
+}
+
+export function unregisterCodexHome(paths, home, bindingMode = null) {
+  const { registry } = loadCodexHomes(paths);
+  const resolved = resolveHome(home);
+  const remaining = registry.homes.filter((entry) => entry.home !== resolved
+    || (bindingMode !== null && entry.binding_mode !== bindingMode));
+  const unregistered = remaining.length !== registry.homes.length;
+  registry.homes = remaining;
+  if (unregistered) persistRegistry(paths, registry);
+  return { unregistered, home: resolved, homes: registry.homes.length };
+}
+
+// Product uninstall: release every claim at once.  The registry file itself
+// stays inside retained product data, but no home remains claimed.  A
+// never-initialized product is not given a registry file by uninstalling.
+export function unregisterAllCodexHomes(paths) {
+  const { registry } = loadCodexHomes(paths);
+  const released = registry.homes.map((entry) => entry.home);
+  const file = codexHomesRegistryPath(paths);
+  if (released.length > 0 || fs.existsSync(file)) {
+    registry.homes = [];
+    persistRegistry(paths, registry);
+  }
+  return { unregistered: released.length, homes: released };
+}
+
+function writableDirectory(home) {
+  try {
+    const stat = fs.statSync(home);
+    if (!stat.isDirectory()) return false;
+    fs.accessSync(home, fs.constants.W_OK);
+    return true;
+  } catch { return false; }
+}
+
+// The auto-coordination entry for npm-driven updates (U06): npm replaces the
+// package directory in place, so an ALREADY-INITIALIZED product detects here
+// that the installed package and its published active payload have drifted.
+// Detection is strictly local: no daemon RPC, no codex invocation, no provider
+// probe, and not one byte of product state is written, so an ordinary
+// read-only status can never fire a paid probe through this path.  A product
+// that was never initialized stays stage-only — first installs never activate —
+// and a corrupted state coordinates through the updater, which preserves the
+// corrupted bytes as evidence instead of treating them as an empty state.
+export function npmUpdateCoordination(paths) {
+  const installed = packageVersion();
+  const file = readOptional(paths.state);
+  let state = null;
+  let readable = true;
+  if (file !== null) {
+    try { state = JSON.parse(file); } catch { state = null; readable = false; }
+  }
+  const active = state && typeof state === 'object' && state.active && typeof state.active === 'object' ? state.active : null;
+  if (!active) {
+    return file === null
+      ? { initialized: false, stage_only: true, package_version: installed, active_version: null, update_pending: false, coordination: 'none' }
+      : { initialized: false, state_readable: readable, stage_only: false, package_version: installed, active_version: null, update_pending: true, coordination: 'update' };
+  }
+  const update_pending = installed !== active.version;
+  return {
+    initialized: true,
+    stage_only: false,
+    package_version: installed,
+    active_version: active.version,
+    update_pending,
+    coordination: update_pending ? 'update' : 'reaffirm',
+  };
+}
+
+// Refresh the managed binding in every registered, writable Codex home.
+// Results are reported per home; a skipped or failed home never collapses
+// into a single success for the whole reconcile (P13).
+export function reconcileCodexHomes(paths, options = {}) {
+  const { registry } = loadCodexHomes(paths);
+  const results = [];
+  for (const entry of registry.homes) {
+    if (!writableDirectory(entry.home)) {
+      entry.last_status = 'skipped_not_writable';
+      results.push({ home: entry.home, status: 'skipped_not_writable' });
+      continue;
+    }
+    try {
+      const installer = options.installer || (entry.binding_mode === 'mcp' ? installMcp : installPlugin);
+      if (typeof installer !== 'function') throw new CliError('CODEX_BINDING_FAILED', `no installer is available for ${entry.binding_mode} binding`);
+      const install = installer(paths, { ...options, codexHome: entry.home });
+      entry.last_status = 'updated';
+      entry.last_sync_ms = Date.now();
+      if (install.digest) entry.digest = install.digest;
+      results.push({ home: entry.home, status: 'updated', cache: install.cache || null });
+    } catch (error) {
+      entry.last_status = 'failed';
+      results.push({ home: entry.home, status: 'failed', error: { code: error.code || 'CODEX_BINDING_FAILED', message: error.message } });
+    }
+  }
+  persistRegistry(paths, registry);
+  return {
+    homes: results,
+    all_updated: results.length > 0 && results.every((result) => result.status === 'updated'),
+  };
+}