external-subagent 0.1.0

package/cli/install/recovery.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import { CliError } from '../errors.mjs';
+import { atomicWrite, jsonBytes, readOptional, restoreOptional, sha256 } from '../fs-atomic.mjs';
+
+// Install-state snapshots, step journal, and rollback.  A failed init restores
+// every tracked file to its prior bytes (or removes files it created) and
+// removes directories it created, so a partial installation never masquerades
+// as a complete one.
+
+export function loadInstallState(file) {
+  const bytes = readOptional(file);
+  if (bytes === null) return { schema_version: 1, completed: [] };
+  try { return JSON.parse(bytes); } catch { throw new CliError('INVALID_INSTALL_STATE', 'install state is invalid JSON'); }
+}
+
+// The updater's schema-2 state (candidate/active/phase).  Corrupted bytes
+// are evidence, never an empty state: the original file is preserved under a
+// timestamped name so the recovery can be inspected, and the caller restarts
+// from an empty state with the preservation reported alongside the result.
+export function loadUpdateState(file) {
+  const bytes = readOptional(file);
+  if (bytes === null) return { state: null, recovery: null };
+  try {
+    const state = JSON.parse(bytes);
+    if (!state || typeof state !== 'object' || Array.isArray(state)) {
+      throw new SyntaxError('update state is not a JSON object');
+    }
+    return { state, recovery: null };
+  } catch (error) {
+    const backup = `${file}.corrupt-${Date.now()}`;
+    try { fs.renameSync(file, backup); } catch (renameError) {
+      throw new CliError('INSTALL_STATE_CORRUPT', `install state is corrupted and could not be preserved: ${renameError.message}`);
+    }
+    return {
+      state: null,
+      recovery: { status: 'recovered', code: 'INSTALL_STATE_CORRUPT', backup, error: error.message },
+    };
+  }
+}
+
+export function markInstallStep(file, completed, id) {
+  completed.add(id);
+  atomicWrite(file, jsonBytes({ schema_version: 1, completed: [...completed] }));
+}
+
+export function snapshotFile(file) {
+  const bytes = readOptional(file);
+  return { bytes, sha256: bytes === null ? null : sha256(bytes) };
+}
+
+export function restoreSnapshotFile(file, snapshot) {
+  if (snapshot.bytes !== null && sha256(snapshot.bytes) !== snapshot.sha256) {
+    throw new Error(`snapshot hash mismatch for ${file}`);
+  }
+  restoreOptional(file, snapshot.bytes);
+  const restored = readOptional(file);
+  if ((snapshot.bytes === null && restored !== null)
+    || (snapshot.bytes !== null && (!restored || sha256(restored) !== snapshot.sha256))) {
+    throw new Error(`rollback verification failed for ${file}`);
+  }
+}
+
+export function rollbackFiles(tracked) {
+  const rollbackErrors = [];
+  for (const entry of Object.values(tracked)) {
+    try { restoreSnapshotFile(entry.file, entry.snapshot); } catch (rollbackError) { rollbackErrors.push(rollbackError); }
+  }
+  return rollbackErrors;
+}
+
+export function removeCreatedDirectories(directories) {
+  const rollbackErrors = [];
+  for (const [name, directory] of Object.entries(directories)) {
+    if (!directory.existed && fs.existsSync(directory.path)) {
+      try { fs.rmSync(directory.path, { recursive: true, force: true }); } catch (rollbackError) { rollbackErrors.push(rollbackError); }
+    }
+  }
+  return rollbackErrors;
+}

package/cli/install/service-activation.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { atomicWrite } from '../fs-atomic.mjs';
+import { CliError } from '../errors.mjs';
+import { callDaemon } from '../rpc.mjs';
+import { LAUNCH_AGENT_LABEL } from '../constants.mjs';
+import { launchctl } from './service-macos.mjs';
+
+const xml = (s) => s.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+const unxml = (s) => s.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&amp;', '&');
+const program = /(<key>ProgramArguments<\/key>\s*<array>\s*<string>)([^<]+)(<\/string>)/;
+const digest = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+export function hasInstalledService(paths) {
+  return Boolean(paths.launchAgent && fs.existsSync(paths.launchAgent));
+}
+
+// The service definition is the executable entry: change only its first argv,
+// retaining the installed configuration/environment and rollback bytes exactly.
+export async function activateService(paths, candidate, options = {}) {
+  const control = options.launchctl || launchctl;
+  const rpc = options.callDaemon || callDaemon;
+  const target = `gui/${process.getuid()}/${LAUNCH_AGENT_LABEL}`;
+  const oldPlist = fs.readFileSync(paths.launchAgent);
+  const match = oldPlist.toString().match(program);
+  if (!match) throw new CliError('SERVICE_DEFINITION_INVALID', 'installed service has no executable entry');
+  const oldPath = unxml(match[2]);
+  const servicePid = async () => {
+    const result = await control(['print', target]);
+    if (result.absent) return null;
+    if (result.skipped) throw new CliError('SERVICE_NOT_VERIFIED', 'service control was skipped');
+    const pid = Number(result.stdout?.match(/\bpid = (\d+)/)?.[1]);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  };
+  const oldPid = await servicePid();
+  const oldStatus = oldPid ? await rpc(paths.socket, 'status', {}) : null;
+  // The running daemon's self-reported digest is the truth about which bytes
+  // the service was executing (bound to the running executable at startup);
+  // the file at oldPath may already carry the NEXT version after an npm
+  // install replaced the package directory in place.
+  const runningArtifact = oldStatus?.identity?.daemon?.artifact;
+  const oldSha = (typeof runningArtifact?.sha256 === 'string' && runningArtifact.sha256) || digest(oldPath);
+  if (oldPid) {
+    const drain = await rpc(paths.socket, 'drain-status', {});
+    if (!drain.ready_for_activation) throw new CliError('DAEMON_NOT_DRAINED', 'daemon still owns active or unreaped work');
+    const claim = await rpc(paths.socket, 'activate-ready', {});
+    if (!claim.activation_claim) throw new CliError('ACTIVATION_NOT_CLAIMED', 'daemon did not grant activation');
+  }
+  // npm may have replaced the old program path with the new payload: rolling
+  // the service back must run the OLD bytes, from the original path when they
+  // are still intact or from the retained payload copy the updater staged
+  // for exactly this recovery.
+  const rollbackExecutable = () => {
+    if (fs.existsSync(oldPath) && digest(oldPath) === oldSha) return { path: oldPath, sha256: oldSha };
+    const retained = options.rollbackPayload;
+    if (retained && typeof retained.path === 'string' && typeof retained.sha256 === 'string'
+      && fs.existsSync(retained.path) && digest(retained.path) === retained.sha256) {
+      return { path: retained.path, sha256: retained.sha256 };
+    }
+    throw new CliError('ROLLBACK_PAYLOAD_UNAVAILABLE', 'previous payload bytes are unavailable; automatic rollback refused');
+  };
+  const healthy = async (expected, previousPid, previousGeneration) => {
+    const deadline = Date.now() + (options.healthTimeoutMs ?? 10_000);
+    let last;
+    do {
+      try {
+        const pid = await servicePid();
+        if (!pid || pid === previousPid) throw new Error('service has no new process');
+        const status = await rpc(paths.socket, 'status', {});
+        const identity = status.identity?.daemon;
+        // Health verification uses the service generation and the running
+        // artifact identity. The diagnostic-only mcp_version never gates
+        // admission.
+        if (!status.service_generation || status.service_generation === previousGeneration
+          || identity?.artifact?.path !== expected.path || identity?.artifact?.sha256 !== expected.sha256
+          || (expected.version && identity?.version !== expected.version)) throw new Error('running daemon identity does not match selected payload');
+        if (await servicePid() !== pid) throw new Error('service process changed during health verification');
+        return { pid, version: identity.version, artifact: identity.artifact, service_generation: status.service_generation };
+      } catch (error) { last = error; }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    } while (Date.now() < deadline);
+    throw new CliError('SERVICE_HEALTH_FAILED', last?.message || 'service did not become healthy');
+  };
+  const unload = async () => {
+    const result = await control(['print', target]);
+    if (result.absent) return;
+    await control(['bootout', target]);
+    const deadline = Date.now() + (options.unloadTimeoutMs ?? 10_000);
+    do {
+      const probe = await control(['print', target]);
+      if (probe.absent) return;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    } while (Date.now() < deadline);
+    throw new CliError('SERVICE_UNLOAD_TIMEOUT', 'launchd service remained registered after bootout');
+  };
+  const writeProgram = (entryPath) => atomicWrite(paths.launchAgent, Buffer.from(oldPlist.toString().replace(program, (_, a, b, c) => `${a}${xml(entryPath)}${c}`)), 0o600);
+  const rollbackService = async () => {
+    await unload();
+    const previous = rollbackExecutable();
+    writeProgram(previous.path);
+    await control(['bootstrap', `gui/${process.getuid()}`, paths.launchAgent]);
+    return healthy({ path: previous.path, sha256: previous.sha256, version: oldStatus?.identity?.daemon?.version }, oldPid, oldStatus?.service_generation);
+  };
+  try {
+    await unload();
+    writeProgram(candidate.path);
+    await control(['bootstrap', `gui/${process.getuid()}`, paths.launchAgent]);
+    const health = await healthy(candidate, oldPid, oldStatus?.service_generation);
+      return {
+      ...health,
+      rollback: async () => {
+        const restored = await rollbackService();
+        if (digest(oldPath) !== oldSha) return { ...restored, restored_from: 'retained_payload' };
+        return restored;
+      },
+    };
+  } catch (error) {
+    if (!oldPid) {
+      try {
+        await unload();
+        atomicWrite(paths.launchAgent, oldPlist, 0o600);
+        error.rollback = { attempted: true, restored: false, plist_restored: true, error: 'no previous service identity to verify' };
+      } catch (rollbackError) {
+        error.rollback = { attempted: true, restored: false, plist_restored: false, error: rollbackError.message };
+      }
+      throw error;
+    }
+    try {
+      error.rollback = await rollbackService();
+    } catch (rollbackError) { error.rollbackError = rollbackError.message; }
+    throw error;
+  }
+}

package/cli/install/service-macos.mjs

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DAEMON_BIN_NAME, LAUNCH_AGENT_LABEL, ZCODE_RUNTIME } from '../constants.mjs';
+import { CliError } from '../errors.mjs';
+import { atomicWrite } from '../fs-atomic.mjs';
+import { nativeBinary } from './layout.mjs';
+import { LAUNCHD_FIXED_PATH } from './path.mjs';
+import { readConfig } from '../config/read.mjs';
+
+// The one macOS service template for the product daemon.  The plist pins
+// absolute payload paths and a fixed PATH so the GUI/launchd environment can
+// never depend on the interactive shell.  Launchctl activation honors the
+// EXTERNAL_SUBAGENT_TEST_NO_LAUNCHCTL seam so fixture runs never load real
+// services; everything else still writes real files.
+
+function escapeXml(value) {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+
+export function launchAgentPlist(paths, options = {}) {
+  const daemon = nativeBinary(DAEMON_BIN_NAME);
+  const config = readConfig(paths.config);
+  const { runtime_path: dshRuntime, home: dshHome, profile: dshProfile, version: dshVersion } = config.subagents.dsh;
+  const { runtime_path: codexRuntime, home: codexHome } = config.subagents.codex;
+  const configRevision = config.revision;
+  // AUD-005/D1: the standalone service never depends on an unrelated runtime.
+  // The pinned ZCode runtime is forwarded only when that installation exists;
+  // without it the daemon still starts and the zcode adapter fails closed at
+  // spawn ("ZCODE_RUNTIME_PATH is unavailable") instead of the whole service
+  // dying on launchd because --runtime cannot canonicalize.  Installing (or
+  // removing) ZCode later is picked up by the next init, which rewrites the
+  // plist.  The seam exists so tests can pin both branches deterministically.
+  const zcodeRuntime = options.zcodeRuntime ?? ZCODE_RUNTIME;
+  const programArguments = [
+    `<string>${escapeXml(daemon)}</string>`,
+    '<string>--database</string>',
+    `<string>${escapeXml(paths.database)}</string>`,
+    '<string>--socket</string>',
+    `<string>${escapeXml(paths.socket)}</string>`,
+    ...(fs.existsSync(zcodeRuntime)
+      ? ['<string>--runtime</string>', `<string>${escapeXml(zcodeRuntime)}</string>`]
+      : []),
+    '<string>--diagnostic-log</string>',
+    `<string>${escapeXml(path.join(paths.logs, 'daemon-error.log'))}</string>`,
+  ];
+  const dshEnvironment = [
+    `<key>PATH</key><string>${LAUNCHD_FIXED_PATH}</string>`,
+    ...(configRevision === null ? [] : [`<key>EXTERNAL_SUBAGENT_CONFIG_REVISION</key><string>${configRevision}</string>`]),
+    ...(dshRuntime ? [`<key>DSH_RUNTIME_PATH</key><string>${escapeXml(dshRuntime)}</string>`] : []),
+    ...(dshHome ? [`<key>DSH_HOME</key><string>${escapeXml(dshHome)}</string>`] : []),
+    ...(dshProfile ? [`<key>DSH_PROFILE</key><string>${escapeXml(dshProfile)}</string>`] : []),
+    ...(dshVersion ? [`<key>DSH_VERSION</key><string>${escapeXml(dshVersion)}</string>`] : []),
+    // The persisted Codex runtime/home pair is forwarded so the service-side
+    // daemon resolves the same launch contract the interactive one does. The
+    // home is only exported when configured; an inherited launchd CODEX_HOME
+    // (if any) stays the second-priority source, and neither being present
+    // fails Codex admission closed instead of falling back to ~/.codex.
+    ...(codexRuntime ? [`<key>CODEX_RUNTIME_PATH</key><string>${escapeXml(codexRuntime)}</string>`] : []),
+    ...(codexHome ? [`<key>CODEX_HOME</key><string>${escapeXml(codexHome)}</string>`] : []),
+  ].join('');
+  return Buffer.from(`<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${LAUNCH_AGENT_LABEL}</string>\n<key>ProgramArguments</key><array>${programArguments.join('')}</array>\n<key>EnvironmentVariables</key><dict>${dshEnvironment}</dict>\n<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>\n<key>StandardOutPath</key><string>${escapeXml(path.join(paths.logs, 'daemon.log'))}</string>\n<key>StandardErrorPath</key><string>${escapeXml(path.join(paths.logs, 'daemon-error.log'))}</string>\n</dict></plist>\n`);
+}
+
+export function installLaunchAgent(paths, options = {}) {
+  const plist = options.plist || launchAgentPlist(paths);
+  atomicWrite(paths.launchAgent, plist, 0o600);
+  return { installed: true, path: paths.launchAgent, label: LAUNCH_AGENT_LABEL };
+}
+
+export function launchctl(args) {
+  if (process.env.EXTERNAL_SUBAGENT_TEST_NO_LAUNCHCTL === '1') {
+    return { action: args[0], skipped: true, reason: 'launchd neutralized by test seam' };
+  }
+  const result = spawnSync('/bin/launchctl', args, { encoding: 'utf8' });
+  if (args[0] === 'print' && result.status === 113) return { action: 'print', absent: true };
+  if (result.error || result.status !== 0) {
+    throw new CliError('DAEMON_CONTROL_FAILED', (result.stderr || result.error?.message || 'launchctl failed').trim());
+  }
+  return { action: args[0], status: result.status, stdout: result.stdout };
+}
+
+// launchd answers a bootstrap whose label is already loaded in the target
+// domain with "Bootstrap failed: 5: Input/output error" (reproduced live on
+// this GUI session; the same EIO was logged by the first acceptance run).
+// A repeat init/start must stay idempotent instead of failing the whole run,
+// so the registration lookup below — the same print/absent discriminator the
+// update owner uses — decides between "already loaded" and a real failure.
+export function serviceRegistrationStatus(uid = process.getuid(), options = {}) {
+  const control = options.launchctl || launchctl;
+  const result = control(['print', `gui/${uid}/${LAUNCH_AGENT_LABEL}`]);
+  if (result.skipped) return { query: 'skipped', registered: null, reason: result.reason };
+  if (result.absent) return { registered: false };
+  const pid = Number(result.stdout?.match(/\bpid = (\d+)/)?.[1]);
+  const state = result.stdout?.match(/^\s*state = (\S+)$/m)?.[1] ?? null;
+  return { registered: true, state, pid: Number.isInteger(pid) && pid > 0 ? pid : null };
+}
+
+export function bootstrapService(paths, uid = process.getuid(), options = {}) {
+  const control = options.launchctl || launchctl;
+  const alreadyLoaded = (lookup) => ({
+    action: 'bootstrap', label: LAUNCH_AGENT_LABEL, already_loaded: true,
+    state: lookup.state ?? null, pid: lookup.pid ?? null,
+  });
+  const existing = serviceRegistrationStatus(uid, { launchctl: control });
+  if (existing.registered) return alreadyLoaded(existing);
+  try {
+    return control(['bootstrap', `gui/${uid}`, paths.launchAgent]);
+  } catch (error) {
+    // Another loader (a racing init, or launchd itself re-reading the plist)
+    // may have won after the check above; confirm before reporting failure.
+    const loaded = serviceRegistrationStatus(uid, { launchctl: control });
+    if (loaded.registered) return alreadyLoaded(loaded);
+    throw error;
+  }
+}
+
+// A bootout call returns before launchd has necessarily finished tearing the
+// job down, and a bootstrap issued inside that window can be swept away by the
+// still-running removal (observed live: rapid stop→start cycles left the
+// service unregistered roughly one time in three).  The stop owner therefore
+// confirms the job is actually gone — bounded, with the same print/absent
+// discriminator the update owner's unload uses — before reporting success.
+export function bootoutService(paths, uid = process.getuid(), options = {}) {
+  const control = options.launchctl || launchctl;
+  const existing = serviceRegistrationStatus(uid, { launchctl: control });
+  if (!existing.registered) return { action: 'bootout', label: LAUNCH_AGENT_LABEL, already_stopped: true };
+  let result;
+  try {
+    result = control(['bootout', `gui/${uid}/${LAUNCH_AGENT_LABEL}`]);
+  } catch (error) {
+    // A racing removal (another stop, or launchd itself) may have taken the
+    // job out between the registration probe and the bootout; confirm before
+    // reporting failure, so a repeated stop stays idempotent.
+    const settled = serviceRegistrationStatus(uid, { launchctl: control });
+    if (!settled.registered) return { action: 'bootout', label: LAUNCH_AGENT_LABEL, already_stopped: true };
+    throw error;
+  }
+  const deadline = Date.now() + (options.unloadTimeoutMs ?? 10_000);
+  for (;;) {
+    const probe = serviceRegistrationStatus(uid, { launchctl: control });
+    if (!probe.registered) return { ...result, label: LAUNCH_AGENT_LABEL, removed: true };
+    if (Date.now() >= deadline) throw new CliError('SERVICE_UNLOAD_TIMEOUT', 'launchd service remained registered after bootout');
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+  }
+}

package/cli/install/update.mjs

@@ -0,0 +1,170 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicWrite, jsonBytes, sha256 } from '../fs-atomic.mjs';
+import { CliError } from '../errors.mjs';
+import { CLI_ENTRY_NAME, DAEMON_BIN_NAME, NATIVE_DIR_NAME } from '../constants.mjs';
+import { reconcileCodexHomes } from './reconcile.mjs';
+import { packageVersion, packageRoot } from './layout.mjs';
+import { loadUpdateState } from './recovery.mjs';
+import { verifyPayload } from './payload.mjs';
+
+const SCHEMA_VERSION = 2;
+const lockPath = (paths) => path.join(paths.data, 'install.lock');
+
+function withLock(paths, fn) {
+  fs.mkdirSync(paths.data, { recursive: true, mode: 0o700 });
+  let fd;
+  try { fd = fs.openSync(lockPath(paths), 'wx', 0o600); fs.writeSync(fd, JSON.stringify({ pid: process.pid, started_at_ms: Date.now() })); } catch (error) {
+    if (error.code === 'EEXIST') {
+      let stale = false;
+      try {
+        const lock = JSON.parse(fs.readFileSync(lockPath(paths), 'utf8'));
+        if (!Number.isInteger(lock.pid) || lock.pid <= 0) stale = true;
+        else { try { process.kill(lock.pid, 0); } catch (probe) { stale = probe.code === 'ESRCH'; } }
+      } catch { stale = true; }
+      if (stale) { try { fs.unlinkSync(lockPath(paths)); } catch {} return withLock(paths, fn); }
+      throw new CliError('UPDATE_IN_PROGRESS', 'another installation update is in progress');
+    }
+    throw error;
+  }
+  try { return fn(); } finally { fs.closeSync(fd); fs.unlinkSync(lockPath(paths)); }
+}
+
+function readState(paths) {
+  const { state, recovery } = loadUpdateState(paths.state);
+  return { state: state ?? { schema_version: SCHEMA_VERSION, candidate: null, active: null, phase: 'idle' }, recovery };
+}
+
+// npm replaces the package directory in place, so the bytes the published
+// active identity was verified against disappear with the next install.  The
+// retained payload store keeps byte-for-byte copies of the verified release
+// (native artifacts, stable entry, release manifest) under versioned product
+// data, outside the directory npm is about to overwrite: active/rollback keep
+// pointing at readable, verifiable old bytes.
+function retainPayload(paths, candidateRoot, verified) {
+  const root = path.join(paths.data, 'payload-store', verified.version);
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  const platformDir = path.join(fs.realpathSync(candidateRoot), 'npm', NATIVE_DIR_NAME, verified.payload.platform);
+  for (const file of verified.payload.files) {
+    atomicWrite(path.join(root, file.name), fs.readFileSync(path.join(platformDir, file.name)), 0o755);
+  }
+  atomicWrite(path.join(root, CLI_ENTRY_NAME), fs.readFileSync(verified.stable.entry), 0o755);
+  atomicWrite(path.join(root, 'payload.json'), fs.readFileSync(path.join(platformDir, 'payload.json')));
+  const retained = {
+    root,
+    entry: path.join(root, CLI_ENTRY_NAME),
+    entry_sha256: verified.stable.digest,
+    daemon_entry: path.join(root, DAEMON_BIN_NAME),
+    daemon_entry_sha256: verified.daemon.digest,
+  };
+  for (const [file, digest] of [[retained.daemon_entry, verified.daemon.digest], [retained.entry, verified.stable.digest]]) {
+    if (sha256(fs.readFileSync(file)) !== digest) {
+      throw new CliError('PAYLOAD_RETENTION_FAILED', `retained copy of ${path.basename(file)} does not match the verified digest`);
+    }
+  }
+  return retained;
+}
+
+function verifyStableEntry(candidateRoot) {
+  const root = fs.realpathSync(candidateRoot);
+  const entry = path.join(root, 'bin', CLI_ENTRY_NAME);
+  let stat;
+  try { stat = fs.lstatSync(entry); } catch { throw new CliError('PAYLOAD_ENTRY_MISSING', 'candidate stable entry is missing'); }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new CliError('PAYLOAD_ENTRY_INVALID', 'candidate stable entry must be a regular file');
+  if ((stat.mode & 0o111) === 0) throw new CliError('PAYLOAD_ENTRY_INVALID', 'candidate stable entry must be executable');
+  const resolved = fs.realpathSync(entry);
+  if (resolved !== entry || !resolved.startsWith(`${root}${path.sep}`)) throw new CliError('PAYLOAD_ENTRY_INVALID', 'candidate stable entry escapes candidate root');
+  const digest = crypto.createHash('sha256').update(fs.readFileSync(entry)).digest('hex');
+  return { entry, digest };
+}
+
+// The service runs the native daemon binary, never the npm bin shim: the
+// activation identity is the external-subagentd payload artifact whose digest
+// verifyPayload already checked against the release manifest.
+function verifyDaemonArtifact(candidateRoot, payload) {
+  const record = payload.files.find((file) => file.name === DAEMON_BIN_NAME);
+  if (!record) throw new CliError('PAYLOAD_DAEMON_MISSING', 'candidate payload does not carry the daemon artifact');
+  const root = fs.realpathSync(candidateRoot);
+  const entry = path.join(root, 'npm', NATIVE_DIR_NAME, payload.platform, record.name);
+  let stat;
+  try { stat = fs.lstatSync(entry); } catch { throw new CliError('PAYLOAD_DAEMON_MISSING', 'candidate daemon artifact is missing'); }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new CliError('PAYLOAD_ENTRY_INVALID', 'candidate daemon artifact must be a regular file');
+  if ((stat.mode & 0o111) === 0) throw new CliError('PAYLOAD_ENTRY_INVALID', 'candidate daemon artifact must be executable');
+  const digest = crypto.createHash('sha256').update(fs.readFileSync(entry)).digest('hex');
+  if (digest !== record.sha256) throw new CliError('PAYLOAD_DIGEST_MISMATCH', 'candidate daemon artifact does not match the verified payload digest');
+  return { entry, digest };
+}
+
+// The pure validation prologue of a locked update, extracted so the
+// coordinator can run the SAME rules (verifyPayload, the stable-entry and
+// daemon-artifact owners) before it takes the working daemon offline.  It
+// writes nothing — no install state, no receipt — never contacts the daemon
+// or a provider, and derives everything from the candidate root, never the
+// user HOME, so a rejected candidate cannot disturb a working installation.
+export function preflightUpdate(options = {}) {
+  // An explicit update always has a candidate root: the controlled staged
+  // payload when the caller passes one, otherwise the installed package the
+  // CLI itself runs from.  There is no rootless "version-only" activation.
+  const candidateRoot = options.candidateRoot || packageRoot();
+  const requested = options.version || 'current';
+  const version = requested === 'current' ? packageVersion() : requested;
+  const available = options.availableVersions || [packageVersion()];
+  if (typeof version !== 'string' || !/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(version) || !available.includes(version)) {
+    throw new CliError('PAYLOAD_VERSION_UNAVAILABLE', `requested payload version is unavailable: ${version}`);
+  }
+  const payload = verifyPayload({ root: candidateRoot, platform: options.platform });
+  if (version !== payload.version) throw new CliError('PAYLOAD_VERSION_MISMATCH', `requested version ${version} differs from candidate ${payload.version}`);
+  // Reject a doomed candidate up front: an unusable stable entry or daemon
+  // artifact must never publish candidate state or touch a single Codex home.
+  const stable = verifyStableEntry(candidateRoot);
+  const daemon = verifyDaemonArtifact(candidateRoot, payload);
+  return { candidateRoot, version, payload, stable, daemon };
+}
+
+export function updateInstallation(paths, options = {}) {
+  if (options.dryRun) return { dry_run: true, phase: 'candidate', version: options.version || 'current' };
+  return withLock(paths, () => {
+    const { candidateRoot, payload, stable, daemon } = preflightUpdate(options);
+    const verifiedVersion = payload.version;
+    const { state: prior, recovery } = readState(paths);
+    const state = { schema_version: SCHEMA_VERSION, candidate: { version: verifiedVersion, root: candidateRoot, payload: payload.files }, active: prior.active, phase: 'candidate', updated_at_ms: Date.now() };
+    atomicWrite(paths.state, jsonBytes(state));
+    const publishedCandidate = state.candidate;
+    try {
+      const sync = options.deferCodexSync ? { homes: [], all_updated: true, deferred: true } : reconcileCodexHomes(paths, options);
+      const ok = sync.homes.length === 0 || sync.all_updated;
+      state.phase = ok ? 'active' : (sync.homes.some((h) => h.status === 'failed') ? 'failed' : 'partial');
+      if (ok) {
+        // Re-verify immediately before publishing: active may only ever point
+        // at the entry bytes verified above, never a candidate mutated since.
+        const stableNow = verifyStableEntry(candidateRoot);
+        const daemonNow = verifyDaemonArtifact(candidateRoot, payload);
+        if (stableNow.entry !== stable.entry || stableNow.digest !== stable.digest
+          || daemonNow.entry !== daemon.entry || daemonNow.digest !== daemon.digest) {
+          throw new CliError('PAYLOAD_ENTRY_CHANGED', 'candidate verified artifacts changed during activation');
+        }
+        state.active = state.candidate; state.candidate = null;
+        state.active.entry = stableNow.entry;
+        state.active.entry_sha256 = stableNow.digest;
+        state.active.daemon_entry = daemonNow.entry;
+        state.active.daemon_entry_sha256 = daemonNow.digest;
+        state.active.retained = retainPayload(paths, candidateRoot, { version: verifiedVersion, payload, stable: stableNow, daemon: daemonNow });
+      }
+      atomicWrite(paths.state, jsonBytes(state));
+      return recovery ? { ...state, recovery } : state;
+    } catch (error) {
+      // Record retryable failure evidence instead of a phantom in-flight
+      // candidate: the prior active stays published and the rejected
+      // candidate remains identified for the next attempt.
+      const evidence = { ...state, candidate: state.candidate ?? publishedCandidate, active: prior.active, phase: 'failed', error: { code: error.code || 'UPDATE_FAILED', message: error.message }, failed_at_ms: Date.now() };
+      try { atomicWrite(paths.state, jsonBytes(evidence)); } catch { /* evidence is best effort; the thrown error stays authoritative */ }
+      throw error;
+    }
+  });
+}
+
+export function reconcileInstallation(paths, options = {}) {
+  if (options.cancelActive && !options.yes) throw new CliError('CONFIRMATION_REQUIRED', '--cancel-active requires --yes');
+  return withLock(paths, () => readState(paths).state);
+}