external-subagent 0.1.0

package/cli/install/codex.mjs

@@ -0,0 +1,352 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { isDeepStrictEqual } from 'node:util';
+import { CliError } from '../errors.mjs';
+import { atomicWrite, jsonBytes, readOptional, restoreOptional } from '../fs-atomic.mjs';
+import { MCP_BIN_NAME, PRODUCT_ID } from '../constants.mjs';
+import { nativeBinary, pluginSourceRoot, PLUGIN_NAME } from './layout.mjs';
+import { pluginManifest, treeDigest, preparePluginStage, guardedRestores } from './plugin-stage.mjs';
+
+// Managed Codex binding.  The staging tree plus a local source marketplace are
+// the product-owned half; every installation/removal goes through the official
+// codex CLI (verified against codex-cli 0.153.4 and re-verified on 0.154.0,
+// see docs/compatibility/codex.md):
+//   codex plugin marketplace add <root> --json
+//   codex plugin add <name> --marketplace <marketplace> --json
+//   codex plugin remove <name>@<marketplace> --json
+// The codex CLI owns its own config/cache writes; this module never edits the
+// Codex cache directly.
+
+const CODEX_MCP_SECTION = `mcp_servers.${PRODUCT_ID}`;
+const MARKETPLACE_NAME = 'personal';
+
+export const CODEX_TOOLS = Object.freeze([
+  'external_subagent_cancel',
+  'external_subagent_close',
+  'external_subagent_list',
+  'external_subagent_observe',
+  'external_subagent_respond',
+  'external_subagent_result',
+  'external_subagent_send',
+  'external_subagent_spawn',
+  'external_subagent_status',
+  'external_subagent_wait',
+]);
+
+export function codexHomeFor(options = {}, paths) {
+  if (typeof options.codexHome === 'string' && options.codexHome.length > 0) return options.codexHome;
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+  return path.join((paths && paths.home) || os.homedir(), '.codex');
+}
+
+function runCodex(args, options = {}) {
+  const cli = options.codexCli || 'codex';
+  const result = spawnSync(cli, args, { encoding: 'utf8', env: { ...process.env, ...(options.env || {}) } });
+  if (result.error) throw new CliError('CODEX_CLI_UNAVAILABLE', result.error.message);
+  if (result.status !== 0) throw new CliError('CODEX_CLI_FAILED', (result.stderr || result.stdout || '').trim() || `codex exited ${result.status}`);
+  let parsed = null;
+  if ((result.stdout || '').trim()) { try { parsed = JSON.parse(result.stdout); } catch { /* help text is not JSON */ } }
+  return { status: result.status, stdout: result.stdout || '', stderr: result.stderr || '', json: parsed };
+}
+
+// Claiming a Codex home includes bringing it into existence; codex itself
+// refuses to resolve a CODEX_HOME that is missing.
+function ensureCodexHome(codexHome) {
+  if (!fs.existsSync(codexHome)) fs.mkdirSync(codexHome, { recursive: true, mode: 0o700 });
+  return codexHome;
+}
+
+function marketplaceRootFor(file) {
+  return path.basename(path.dirname(file)) === 'plugins' && path.basename(path.dirname(path.dirname(file))) === '.agents'
+    ? path.dirname(path.dirname(path.dirname(file)))
+    : path.dirname(file);
+}
+
+function updateMarketplace(file, staging) {
+  const root = marketplaceRootFor(file);
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  let doc = { name: MARKETPLACE_NAME, interface: { displayName: 'Personal' }, plugins: [] };
+  if (fs.existsSync(file)) doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!Array.isArray(doc.plugins)) throw new CliError('PLUGIN_MARKETPLACE_CONFLICT', 'marketplace file is not a source marketplace manifest');
+  const rel = `./${path.relative(root, staging)}`;
+  const entry = { name: PLUGIN_NAME, source: { source: 'local', path: rel }, policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' }, category: 'Productivity' };
+  const index = doc.plugins.findIndex((p) => p.name === PLUGIN_NAME);
+  if (index >= 0) {
+    const current = doc.plugins[index];
+    const currentPath = current?.source?.path;
+    const resolved = currentPath ? path.resolve(root, currentPath) : null;
+    const manifest = resolved && fs.existsSync(path.join(resolved, '.codex-plugin', 'plugin.json')) ? JSON.parse(fs.readFileSync(path.join(resolved, '.codex-plugin', 'plugin.json'), 'utf8')) : null;
+    if (currentPath !== entry.source.path || !manifest || manifest.name !== PLUGIN_NAME) throw new CliError('PLUGIN_MARKETPLACE_CONFLICT', 'marketplace entry is not a managed external-subagent source');
+    return { marketplace: file, marketplace_name: doc.name || MARKETPLACE_NAME, entry: currentPath, digest: treeDigest(staging) };
+  }
+  doc.plugins.push(entry);
+  // atomicWrite, not a bare writeFileSync: a failed/partial write either
+  // lands whole or leaves the prior bytes untouched, so the rollback below
+  // never inherits a half-written manifest it might skip restoring.
+  atomicWrite(file, jsonBytes(doc));
+  return { marketplace: file, marketplace_name: doc.name || MARKETPLACE_NAME, entry: rel, digest: treeDigest(staging) };
+}
+
+// The staged managed binding this install just wrote: the manifest identity
+// plus the facade command and daemon socket stagePlugin pinned.  The cache
+// verification below compares the codex-materialized copy against exactly
+// these values, never against recomputed guesses.
+function stagedManagedBinding(staging) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(staging, '.codex-plugin', 'plugin.json'), 'utf8'));
+  const server = JSON.parse(fs.readFileSync(path.join(staging, '.mcp.json'), 'utf8')).mcpServers?.external_subagent;
+  if (!server || typeof server.command !== 'string' || typeof server.env?.ZCODE_AGENTD_SOCKET !== 'string') {
+    throw new CliError('INVALID_PLUGIN_SOURCE', 'staged plugin MCP binding is incomplete');
+  }
+  return { manifest, command: server.command, socket: server.env.ZCODE_AGENTD_SOCKET };
+}
+
+function readCacheJson(file, cache, identity) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new CliError('CODEX_CACHE_UNVERIFIABLE', `codex plugin cache for ${identity} is present but unreadable (${file}: ${error.message})`);
+  }
+}
+
+// Shared remediation for any cache that kept another installation's bytes
+// for this identity: the identity (plugin version) must move, or the
+// resolved root must be refreshed — the codex-owned cache is never edited.
+const CACHE_REUSE_REMEDIATION = 'The cache kept another installation\'s content for the same identity: when the CLI freezes cached content for an identity (codex 0.153.4 store behavior), release a distinct plugin version instead of accepting it; when the CLI re-materializes the cache from the registered root (codex 0.154.0, non-reserved marketplace names), refresh the registered marketplace root and re-add';
+
+// codex materializes `plugin add` caches from a resolved root, and the
+// resolution differs by codex version and marketplace name (verified on
+// 0.153.4 and 0.154.0, see docs/compatibility/codex.md).  0.153.4 froze the
+// first-cached bytes in a machine-global store keyed by
+// plugin@marketplace@version, so the same identity reinstalled from a
+// different binding (another staging root, installed facade, or daemon
+// socket) or from newer managed content received those foreign bytes while
+// `plugin add` still reported success.  0.154.0 re-materializes non-reserved
+// names from the registered root on every add, but resolves the reserved
+// marketplace name `personal` machine-globally to the real user root,
+// ignoring CODEX_HOME — so an isolated home under the reserved name still
+// meets the real root's foreign bytes.  Before installPlugin may return
+// success, the materialized cache is read back and compared with this run's
+// staged binding AND staged managed content; any surprise fails closed
+// below (the checks stay even where 0.154.0 re-materializes, as defense
+// against freeze-behavior CLIs and future regressions).  The cache is only
+// ever READ here — codex-owned state is never edited, and the remediation
+// is a distinct release identity (frozen stores), refreshing/re-registering
+// the resolved root, or a non-reserved marketplace name in isolated homes —
+// never a rewrite.
+function verifyCodexCache(add, { codexHome, staging, marketplaceName }) {
+  const expected = stagedManagedBinding(staging);
+  const identity = `${PLUGIN_NAME}@${marketplaceName}@${expected.manifest.version}`;
+  const candidates = [];
+  const reported = add.json?.installedPath || add.json?.installed_path;
+  if (typeof reported === 'string' && reported.length > 0) candidates.push(reported);
+  candidates.push(path.join(codexHome, 'plugins', 'cache', add.json?.marketplaceName || marketplaceName, PLUGIN_NAME, String(expected.manifest.version)));
+  for (const cache of [...new Set(candidates)]) {
+    if (!fs.existsSync(cache)) continue;
+    const manifest = readCacheJson(path.join(cache, '.codex-plugin', 'plugin.json'), cache, identity);
+    for (const field of ['name', 'version', 'skills', 'mcpServers']) {
+      if (manifest[field] !== expected.manifest[field]) {
+        throw new CliError('CODEX_CACHE_BINDING_MISMATCH', `codex plugin cache for ${identity} has manifest ${field}=${JSON.stringify(manifest[field])}, expected the staged ${JSON.stringify(expected.manifest[field])} (${cache})`);
+      }
+    }
+    const server = readCacheJson(path.join(cache, '.mcp.json'), cache, identity).mcpServers?.external_subagent;
+    const socket = server?.env?.ZCODE_AGENTD_SOCKET;
+    if (!server || server.command !== expected.command || socket !== expected.socket) {
+      throw new CliError('CODEX_CACHE_BINDING_MISMATCH', `codex plugin cache for ${identity} carries a different managed binding (command=${server?.command}, socket=${socket}); expected this install's staged binding (command=${expected.command}, socket=${expected.socket}). The cache resolved to another installation's bytes (${cache}); either the machine-global content store reused them for the same identity (release a distinct plugin version instead of accepting them), or the reserved marketplace name personal resolved machine-globally to the real user root regardless of CODEX_HOME (refresh or re-register that root, or use a non-reserved marketplace name in isolated homes)`);
+    }
+    // AUD-010: identity and binding alone do not prove the cache carries THIS
+    // candidate.  A freeze-behavior CLI (0.153.4's machine-global store keyed
+    // by plugin@marketplace@version) keeps whatever bytes the FIRST install
+    // of that identity staged, so a same-identity refresh can meet every
+    // metadata/binding check above while the materialized tree still holds
+    // an older SKILL, lacks a file this candidate added, or retains a file
+    // the source deleted.  codex 0.154.0 re-materializes non-reserved names
+    // from the registered root before this read, so on that baseline this
+    // comparison is defense-in-depth rather than a live stale-content
+    // catch; it stays for freeze-behavior CLIs and future regressions.  The
+    // managed content is therefore compared with this run's staged tree via
+    // treeDigest (every file and byte except `.mcp.json` — that exclusion
+    // is treeDigest's existing rule, because the machine-local binding must
+    // not churn the content digest).  The `.mcp.json` gap that exclusion
+    // would leave is closed by a direct comparison right after the binding
+    // check: command and socket there, then the whole managed document.
+    // Real codex materializes the cache as a verbatim copy of the staged
+    // plugin tree with no host-generated additions inside it (see
+    // docs/compatibility/codex.md), so the staged file set IS the managed
+    // set; any difference fails closed through the existing error chain
+    // (S01 keeps staging/marketplace recoverable) instead of reporting
+    // cache_verified for stale bytes.
+    const stagedMcp = readCacheJson(path.join(staging, '.mcp.json'), staging, identity);
+    const cacheMcp = readCacheJson(path.join(cache, '.mcp.json'), cache, identity);
+    if (!isDeepStrictEqual(cacheMcp, stagedMcp)) {
+      throw new CliError('CODEX_CACHE_CONTENT_MISMATCH', `codex plugin cache for ${identity} carries a different managed MCP config (command and socket already matched, so the divergence is in the remaining .mcp.json fields such as args or env; ${cache}). ${CACHE_REUSE_REMEDIATION}`);
+    }
+    const stagedDigest = treeDigest(staging);
+    const cacheDigest = treeDigest(cache);
+    if (cacheDigest !== stagedDigest) {
+      throw new CliError('CODEX_CACHE_CONTENT_MISMATCH', `codex plugin cache for ${identity} does not carry this candidate's managed content (staged tree digest ${stagedDigest}, cache digest ${cacheDigest}; ${cache}). ${CACHE_REUSE_REMEDIATION}`);
+    }
+    return cache;
+  }
+  // `plugin add` reported success, yet neither the CLI-reported path nor the
+  // derived cache location exists on disk — there are no bytes to verify this
+  // install against.  Real codex always materializes the cache, so a success
+  // without one is an unverifiable install: fail closed here instead of
+  // reporting installed/cache_verified:false, which let public installs and
+  // reconciles record success (claims, last_status=updated) for an install
+  // whose binding this run never saw.
+  const lookedIn = [...new Set(candidates)].join(', ');
+  throw new CliError('CODEX_CACHE_UNVERIFIABLE', `codex plugin add reported success for ${identity} but no plugin cache was materialized to verify (looked in: ${lookedIn}); refusing to record an unverified install`);
+}
+
+export function resolveStaging(home, options) {
+  let staging = options.stagingPath || path.join(home, 'plugins', PLUGIN_NAME);
+  let marketplace = options.marketplacePath || path.join(home, '.agents', 'plugins', 'marketplace.json');
+  // The default ~/.agents file can be an installed-registry projection, not a
+  // source. Never overwrite it; use a private local marketplace root instead.
+  if (!options.marketplacePath && fs.existsSync(marketplace)) {
+    const reprobe = () => {
+      const root = path.join(home, '.external-subagent-marketplace');
+      staging = path.join(root, 'plugins', PLUGIN_NAME);
+      marketplace = path.join(root, '.agents', 'plugins', 'marketplace.json');
+    };
+    try {
+      if (!Array.isArray(JSON.parse(fs.readFileSync(marketplace, 'utf8')).plugins)) reprobe();
+    } catch { reprobe(); }
+  }
+  return { staging, marketplace };
+}
+
+export function installPlugin(paths, options = {}) {
+  const source = options.source || pluginSourceRoot();
+  const home = options.home || paths.home;
+  const { staging, marketplace } = resolveStaging(home, options);
+  const codexHome = ensureCodexHome(codexHomeFor(options, paths));
+  const env = { ...(options.env || {}), CODEX_HOME: codexHome };
+  const cli = { codexCli: options.codexCli, env };
+  const probe = runCodex(['plugin', 'add', '--help'], cli);
+  if (options.dryRun) {
+    return { dry_run: true, operation: options.uninstall ? 'uninstall' : 'install', source, staging, marketplace, codex_home: codexHome, cli: 'codex', help_exit: probe.status };
+  }
+  if (options.uninstall) return uninstallPlugin(paths, options);
+  pluginManifest(source);
+  const priorMarketplace = fs.existsSync(marketplace) ? fs.readFileSync(marketplace) : null;
+  const staged = preparePluginStage(source, staging, paths);
+  // AUD-002: stage by validated replacement.  publish() is self-contained
+  // (a failed copy/parse/swap never leaves the live tree moved or damaged);
+  // every later failure rolls the marketplace back to its prior bytes and
+  // restores the prior coherent staging tree — each as an INDEPENDENT
+  // guarded attempt, so a restore that itself fails (a marketplace parent
+  // that stays read-only) neither skips the staging restore nor masks the
+  // original error, and the unrestored resources ride the thrown error.
+  const restoreStaging = () => {
+    if (!staged.restore()) {
+      throw new CliError('PLUGIN_STAGING_RESTORE_FAILED', `the prior staging tree could not be restored at ${staging}; the retained prior copy is left beside it as recovery material`);
+    }
+  };
+  const restoreMarketplace = () => restoreOptional(marketplace, priorMarketplace);
+  let market;
+  try {
+    staged.publish();
+    market = updateMarketplace(marketplace, staging);
+  } catch (error) {
+    // The marketplace restore runs here too: updateMarketplace may already
+    // have written the managed entry (its write is atomic, but a later step
+    // in it can still fail), and those bytes must go back to the prior
+    // backup — foreign entries included — alongside the staging restore.
+    throw guardedRestores(error, [
+      { resource: marketplace, restore: restoreMarketplace },
+      { resource: staging, restore: restoreStaging },
+    ]);
+  }
+  // Explicitly configured marketplaces must be registered; the personal
+  // default is implicit. Both registrations are idempotent in codex.
+  let add;
+  let verifiedCache = null;
+  try {
+    if (options.registerMarketplace !== false) runCodex(['plugin', 'marketplace', 'add', marketplaceRootFor(marketplace), '--json'], cli);
+    add = runCodex(['plugin', 'add', PLUGIN_NAME, '--marketplace', market.marketplace_name, '--json'], cli);
+    verifiedCache = verifyCodexCache(add, { codexHome, staging, marketplaceName: market.marketplace_name });
+  } catch (error) {
+    throw guardedRestores(error, [
+      { resource: marketplace, restore: restoreMarketplace },
+      { resource: staging, restore: restoreStaging },
+    ]);
+  }
+  staged.complete();
+  return {
+    installed: true, source, staging, marketplace, codex_home: codexHome,
+    cache: verifiedCache,
+    cache_verified: true,
+    codex: add.json || add.stdout.trim(), ...market,
+  };
+}
+
+export function uninstallPlugin(paths, options = {}) {
+  const source = options.source || pluginSourceRoot();
+  const home = options.home || paths.home;
+  const { staging, marketplace } = resolveStaging(home, options);
+  const codexHome = codexHomeFor(options, paths);
+  const env = { ...(options.env || {}), CODEX_HOME: codexHome };
+  if (options.dryRun) {
+    return { dry_run: true, operation: 'uninstall', source, staging, marketplace, codex_home: codexHome, cli: 'codex' };
+  }
+  let marketplaceName = MARKETPLACE_NAME;
+  try {
+    if (fs.existsSync(marketplace)) marketplaceName = JSON.parse(fs.readFileSync(marketplace, 'utf8')).name || MARKETPLACE_NAME;
+  } catch { /* keep the default marketplace name */ }
+  if (!fs.existsSync(codexHome)) {
+    return { uninstalled: true, source, staging, marketplace, codex_home: codexHome, marketplace_name: marketplaceName, codex: null, note: 'codex home absent; nothing to remove' };
+  }
+  // The verified removal form is <plugin>@<marketplace>; a bare name is
+  // rejected by codex 0.153.4.
+  const result = runCodex(['plugin', 'remove', `${PLUGIN_NAME}@${marketplaceName}`, '--json'], { codexCli: options.codexCli, env });
+  return { uninstalled: true, source, staging, marketplace, codex_home: codexHome, marketplace_name: marketplaceName, codex: result.json || result.stdout.trim() };
+}
+
+function codexMcpConfig(paths) {
+  const command = nativeBinary(MCP_BIN_NAME);
+  const tools = CODEX_TOOLS.map((tool) => `  "${tool}",`).join('\n');
+  return `[${CODEX_MCP_SECTION}]\ncommand = ${JSON.stringify(command)}\nenabled = true\nrequired = true\nstartup_timeout_sec = 10\ntool_timeout_sec = 304\nenabled_tools = [\n${tools}\n]\ndefault_tools_approval_mode = "prompt"\n\n[${CODEX_MCP_SECTION}.env]\nZCODE_AGENTD_SOCKET = ${JSON.stringify(paths.socket)}\n\n[${CODEX_MCP_SECTION}.tools.external_subagent_status]\napproval_mode = "auto"\n\n[${CODEX_MCP_SECTION}.tools.external_subagent_list]\napproval_mode = "auto"\n\n[${CODEX_MCP_SECTION}.tools.external_subagent_wait]\napproval_mode = "auto"\n\n[${CODEX_MCP_SECTION}.tools.external_subagent_result]\napproval_mode = "auto"\n`;
+}
+
+function removeTomlSection(text, section) {
+  const lines = text.split(/(?<=\n)/u);
+  let removing = false;
+  const kept = [];
+  for (const line of lines) {
+    const match = line.match(/^\s*\[([^\]]+)\]\s*\r?\n?$/u);
+    if (match) removing = match[1] === section || match[1].startsWith(`${section}.`);
+    if (!removing) kept.push(line);
+  }
+  return kept.join('').replace(/\n{3,}$/u, '\n\n');
+}
+
+export function installMcp(paths, options = {}) {
+  // The TOML binding lives inside the Codex home, so an explicit --codex-home
+  // (then CODEX_HOME) selects the config file for install and removal alike.
+  const config = options.configPath || path.join(codexHomeFor(options, paths), 'config.toml');
+  const codexHome = codexHomeFor(options, paths);
+  const command = nativeBinary(MCP_BIN_NAME);
+  if (options.dryRun) {
+    return { dry_run: true, operation: options.uninstall ? 'uninstall' : 'install', platform: 'codex', config, codex_home: codexHome, command, socket: paths.socket };
+  }
+  if (options.uninstall) {
+    const prior = readOptional(config);
+    if (prior === null) return { uninstalled: false, platform: 'codex', config, codex_home: codexHome };
+    const preserved = removeTomlSection(prior.toString('utf8'), CODEX_MCP_SECTION).replace(/^\n+|\n+$/gu, '');
+    atomicWrite(config, Buffer.from(preserved ? `${preserved}\n` : ''));
+    return { uninstalled: true, platform: 'codex', config, codex_home: codexHome };
+  }
+  if (!fs.existsSync(command) && !options.skipNativeProbe) {
+    throw new CliError('NATIVE_BINARY_NOT_FOUND', 'npm package does not contain the macOS MCP binary');
+  }
+  const prior = readOptional(config);
+  const base = prior === null ? '' : prior.toString('utf8');
+  const preserved = removeTomlSection(base, CODEX_MCP_SECTION).replace(/\s*$/u, '');
+  const next = `${preserved ? `${preserved}\n\n` : ''}${codexMcpConfig(paths)}`;
+  atomicWrite(config, Buffer.from(next));
+  return { installed: true, platform: 'codex', config, codex_home: codexHome, command, socket: paths.socket, tools: [...CODEX_TOOLS] };
+}

package/cli/install/init.mjs

@@ -0,0 +1,206 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { LAUNCH_AGENT_LABEL, ZCODE_RUNTIME } from '../constants.mjs';
+import { CliError } from '../errors.mjs';
+import { parseConfig } from '../config/read.mjs';
+import { writeConfig } from '../config/write.mjs';
+import { verifyPayload } from './payload.mjs';
+import { pathReport } from './path.mjs';
+import { packageRoot, payloadManifestPath } from './layout.mjs';
+import { updateInstallation } from './update.mjs';
+import { loadInstallState, markInstallStep, removeCreatedDirectories, rollbackFiles, snapshotFile } from './recovery.mjs';
+import { bootstrapService, bootoutService, installLaunchAgent } from './service-macos.mjs';
+
+// Standalone-install coordination (S05, AUD-005 decision D1).  A plain npm
+// install only stages the package and payload; an explicit `init` installs
+// the STANDALONE SERVICE ONLY — every state-changing step below is
+// host-neutral:
+//   verify-payload     the staged native payload matches the package version
+//   check-path         PATH findings are reported, never written
+//   create-data        private data/log directories
+//   write-product-config  republish the current agent config schema
+//   install-launch-agent  the one macOS service template
+//   start-service      launchctl bootstrap (best-effort, reported)
+//   publish-active-payload  the verified active identity and retained bytes
+//                      (B-3): a successful init establishes the version and
+//                      retention baseline itself, so the standard `npm A ->
+//                      init A -> use A -> npm B` sequence never depends on an
+//                      extra "A update" the user was never told to run.  The
+//                      publication reuses the existing locked update owner —
+//                      no second lifecycle or scheduler — and only runs when
+//                      this init verified the payload it installed.
+// init no longer probes a fixed ZCode runtime, no longer installs the managed
+// Codex plugin, and no longer claims a Codex home (the pre-D1 steps
+// probe-runtime, install-codex-plugin, and claim-codex-home are gone).  A
+// host is bound through the existing EXPLICIT commands — `install-plugin
+// codex|zcode` or `install-mcp` — which own staging, the official codex add,
+// and the D08 registry claim.  The pinned ZCode runtime is forwarded to the
+// service only when that installation exists (see service-macos.mjs), so a
+// missing ZCode app or Codex home never blocks standalone setup.
+// Failures roll tracked files back through recovery.mjs; a resumable journal
+// lets `init --resume` continue after environmental failures.  Journals from
+// pre-D1 inits may still list the retired codex steps; unknown completed ids
+// are simply never consulted again.
+const HOOK_INSTALLER = ['plugins', 'codex', 'external-subagent', 'scripts', 'install-agent-hooks.mjs'];
+
+function hookInstallerPath() {
+  return path.join(packageRoot(), ...HOOK_INSTALLER);
+}
+
+export function installPlan(paths, options = {}) {
+  const manifest = payloadManifestPath() ?? path.join(packageRoot(), 'npm', 'native', 'darwin-arm64', 'payload.json');
+  const plan = [
+    { id: 'verify-payload', action: 'verify staged native payload', path: manifest },
+    { id: 'check-path', action: 'report PATH availability without writing profiles' },
+    { id: 'create-data', action: 'create private product data and log directories', paths: [paths.data, paths.logs] },
+    { id: 'write-product-config', action: 'republish the product agent config schema', path: paths.config },
+    { id: 'install-launch-agent', action: 'install daemon LaunchAgent', path: paths.launchAgent, label: LAUNCH_AGENT_LABEL },
+    { id: 'start-service', action: 'bootstrap the daemon service', path: paths.launchAgent, label: LAUNCH_AGENT_LABEL },
+    { id: 'publish-active-payload', action: 'publish the verified active payload and retained-byte baseline', path: paths.state },
+  ];
+  if (options.installHooks) plan.splice(plan.findIndex((step) => step.id === 'publish-active-payload'), 0, { id: 'install-hooks', action: 'install ZCode policy hooks', path: paths.zcodeConfig, provenance: paths.hookProvenance });
+  return plan;
+}
+
+export function installHooks(paths, options = {}) {
+  if (options.dryRun) return { dry_run: true, plan: [{ id: 'install-hooks', action: 'install ZCode policy hooks', path: paths.zcodeConfig, provenance: paths.hookProvenance }] };
+  const result = spawnSync(process.execPath, [hookInstallerPath(), '--config', paths.zcodeConfig, '--provenance', paths.hookProvenance], { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    let failure;
+    try { failure = JSON.parse((result.stderr || '').trim()); } catch { /* plain-text failure */ }
+    throw new CliError(failure?.code || 'HOOK_INSTALL_FAILED', failure?.error || (result.stderr || 'hook installation failed').trim());
+  }
+  try { return JSON.parse(result.stdout); } catch { throw new CliError('HOOK_INSTALL_FAILED', 'hook installer returned invalid JSON'); }
+}
+
+export function runInit(options = {}) {
+  const paths = options.paths;
+  if (!paths) throw new CliError('INTERNAL_ERROR', 'runInit requires product paths');
+  const plan = installPlan(paths, options);
+  if (options.dryRun) return { dry_run: true, plan };
+
+  const skipPayload = Boolean(options.skipPayloadProbe);
+  const payload = skipPayload ? { status: 'skipped', platform: null, version: null, files: [] } : verifyPayload();
+  const pathFindings = pathReport();
+
+  const tracked = {
+    zcodeConfig: { file: paths.zcodeConfig, snapshot: snapshotFile(paths.zcodeConfig) },
+    hookProvenance: { file: paths.hookProvenance, snapshot: snapshotFile(paths.hookProvenance) },
+    state: { file: paths.state, snapshot: snapshotFile(paths.state) },
+    config: { file: paths.config, snapshot: snapshotFile(paths.config) },
+    launchAgent: { file: paths.launchAgent, snapshot: snapshotFile(paths.launchAgent) },
+  };
+  const directories = {
+    data: { path: paths.data, existed: fs.existsSync(paths.data) },
+    logs: { path: paths.logs, existed: fs.existsSync(paths.logs) },
+  };
+  const state = options.resume ? loadInstallState(paths.state) : { schema_version: 1, completed: [] };
+  const completed = new Set(state.completed || []);
+  const mark = (id) => markInstallStep(paths.state, completed, id);
+  const failAt = (id) => {
+    if (options._failStep === id) throw new Error(`injected failure at ${id}`);
+  };
+
+  let service = { action: 'bootstrap', skipped: true, reason: 'not attempted' };
+  // A rollback must also undo what this run itself loaded: a failure after a
+  // successful bootstrap would otherwise leave a launchd job running binary
+  // bytes the rolled-back plist/install-state no longer describe (observed
+  // live: a codex-binding conflict stranded a running candidate daemon).
+  // A service that was already loaded before this init is never touched.
+  let serviceLoadedByThisRun = false;
+  let baseline = null;
+  try {
+    if (!completed.has('verify-payload')) mark('verify-payload');
+    if (!completed.has('check-path')) mark('check-path');
+    if (!completed.has('create-data')) {
+      fs.mkdirSync(paths.data, { recursive: true, mode: 0o700 });
+      fs.mkdirSync(paths.logs, { recursive: true, mode: 0o700 });
+      mark('create-data');
+    }
+    if (!completed.has('write-product-config')) {
+      // The daemon takes its database/socket/runtime from service arguments,
+      // never from this file; drop the retired top-level path fields so an
+      // install over an older local config republishes the current schema.
+      // S05-F01: `subagents.zcode.runtime_path` was a first-class config key
+      // before D1 rejected it, so a pre-S05 install can carry it in either
+      // the schema-2 or the legacy schema-1 shape.  Retire it here — before
+      // parseConfig migrates/validates — so `npm new -> init` self-heals such
+      // configs instead of failing closed at the read gate (which stays
+      // fully strict for every other read/write path).
+      const prior = fs.existsSync(paths.config)
+        ? JSON.parse(fs.readFileSync(paths.config, 'utf8'))
+        : {};
+      for (const field of ['runtime', 'database', 'socket']) delete prior[field];
+      for (const map of ['subagents', 'agents']) delete prior[map]?.zcode?.runtime_path;
+      writeConfig(paths.config, parseConfig(prior));
+      failAt('write-product-config');
+      mark('write-product-config');
+    }
+    if (!completed.has('install-launch-agent')) {
+      installLaunchAgent(paths);
+      failAt('install-launch-agent');
+      mark('install-launch-agent');
+    }
+    if (!completed.has('start-service') && !options.skipServiceStart) {
+      service = bootstrapService(paths, process.getuid(), { launchctl: options.launchctl });
+      serviceLoadedByThisRun = !service.skipped && !service.already_loaded;
+      mark('start-service');
+    }
+    if (options.installHooks && !completed.has('install-hooks')) {
+      installHooks(paths);
+      mark('install-hooks');
+    }
+    // The baseline publication runs LAST and only for an init that verified
+    // the payload it installed (a skipped probe — test harnesses only —
+    // leaves the resume journal as the sole state).  It reuses the locked
+    // update owner, so the active identity and retained bytes are published
+    // under the exact verification/retention rules every later update
+    // follows.  The Codex-home sync stays deferred: init binds no host, so
+    // any registered homes belong to explicit install-plugin/install-mcp
+    // bindings and remain the reconcile owner's to refresh.  The step is
+    // recorded in the in-memory report only — writing the schema-1 journal
+    // here would clobber the schema-2 activation state it just published.
+    if (payload.status === 'verified') {
+      failAt('publish-active-payload');
+      const published = updateInstallation(paths, { deferCodexSync: true });
+      if (published.phase !== 'active' || !published.active) {
+        throw new CliError('INIT_BASELINE_FAILED', `activation baseline publication did not complete (phase=${published.phase ?? 'none'})`);
+      }
+      completed.add('publish-active-payload');
+      baseline = {
+        version: published.active.version,
+        entry_sha256: published.active.entry_sha256,
+        daemon_entry: published.active.daemon_entry,
+        daemon_entry_sha256: published.active.daemon_entry_sha256,
+        retained_root: published.active.retained?.root ?? null,
+      };
+    }
+  } catch (error) {
+    const rollbackErrors = [
+      ...rollbackFiles(tracked),
+      ...removeCreatedDirectories(directories),
+    ];
+    if (serviceLoadedByThisRun) {
+      try { bootoutService(paths, process.getuid(), { launchctl: options.launchctl }); } catch (bootoutError) {
+        rollbackErrors.push(`service rollback (bootout) failed: ${bootoutError.message}`);
+      }
+    }
+    if (rollbackErrors.length > 0) error.rollbackErrors = rollbackErrors;
+    throw error;
+  }
+  return {
+    installed: true,
+    resumed: Boolean(options.resume),
+    completed: [...completed],
+    // Honest runtime report instead of a hard dependency: the pinned ZCode
+    // runtime is an adapter capability, observed and forwarded by the service
+    // template only when present.
+    runtime: { path: ZCODE_RUNTIME, present: fs.existsSync(ZCODE_RUNTIME) },
+    payload,
+    baseline,
+    path_report: pathFindings,
+    service,
+  };
+}

package/cli/install/layout.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DAEMON_BIN_NAME, MCP_BIN_NAME, NATIVE_DIR_NAME, PRODUCT_NAME, VERSION } from '../constants.mjs';
+
+// Package and payload layout is the single source of truth for where the
+// staged npm artifact keeps its managed entry points.  The MCP binding and
+// the LaunchAgent reference absolute paths below this root, never a shell or
+// GUI PATH lookup.  Identity names derive from the variant token in
+// constants.mjs, so the debug variant resolves its own payload directory,
+// binary names, and plugin source without a parallel code path.
+export const PLUGIN_NAME = PRODUCT_NAME;
+export const NATIVE_PLATFORM = 'darwin-arm64';
+export const NATIVE_BINARIES = Object.freeze([DAEMON_BIN_NAME, MCP_BIN_NAME]);
+
+export function packageRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+export function nativePlatform(platform = process.platform, arch = process.arch) {
+  if (platform === 'darwin' && arch === 'arm64') return NATIVE_PLATFORM;
+  return null;
+}
+
+export function nativePayloadDir(platform = nativePlatform()) {
+  if (platform !== NATIVE_PLATFORM) return null;
+  return path.join(packageRoot(), 'npm', NATIVE_DIR_NAME, platform);
+}
+
+export function nativeBinary(name, platform = nativePlatform()) {
+  const dir = nativePayloadDir(platform);
+  if (!dir || !NATIVE_BINARIES.includes(name)) return null;
+  return path.join(dir, name);
+}
+
+export function payloadManifestPath(platform = nativePlatform()) {
+  const dir = nativePayloadDir(platform);
+  return dir === null ? null : path.join(dir, 'payload.json');
+}
+
+export function pluginSourceRoot() {
+  return path.join(packageRoot(), 'plugins', 'codex', PLUGIN_NAME);
+}
+
+// The npm package version and the in-repo CLI version must agree; payload
+// verification rejects any drift between the two.
+export function packageVersion() {
+  const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
+  return manifest.version;
+}
+
+export function cliVersion() {
+  return VERSION;
+}