external-subagent 0.1.0

package/cli/commands/tasks.mjs

@@ -0,0 +1,64 @@
+import { CliError } from '../errors.mjs';
+
+const SPAWN_FIELDS = new Set(['subagent', 'repository', 'permission_mode', 'prompt', 'model', 'effort', 'write_manifest']);
+const FLAG_FIELDS = new Map([
+  ['--subagent', 'subagent'],
+  ['--repository', 'repository'],
+  ['--prompt', 'prompt'],
+  ['--permission-mode', 'permission_mode'],
+  ['--model', 'model'],
+  ['--effort', 'effort'],
+]);
+
+function flagValue(args, option) {
+  const value = args.shift();
+  if (value === undefined || value === '' || value.startsWith('--')) {
+    throw new CliError('INVALID_ARGUMENT', `${option} requires a non-null value`, 2);
+  }
+  return value;
+}
+
+export function parseSpawnArgs(args) {
+  const input = {};
+  const remaining = [...args];
+  while (remaining.length > 0) {
+    const option = remaining.shift();
+    if (option === '--write-manifest') {
+      (input.write_manifest ||= []).push(flagValue(remaining, option));
+      continue;
+    }
+    const field = FLAG_FIELDS.get(option);
+    if (!field) throw new CliError('INVALID_ARGUMENT', `unsupported spawn option: ${option}`, 2);
+    if (Object.hasOwn(input, field)) throw new CliError('INVALID_ARGUMENT', `${option} may be provided only once`, 2);
+    input[field] = flagValue(remaining, option);
+  }
+  if (!Object.hasOwn(input, 'repository')) throw new CliError('INVALID_ARGUMENT', '--repository is required', 2);
+  if (!Object.hasOwn(input, 'prompt')) throw new CliError('INVALID_ARGUMENT', '--prompt is required', 2);
+  return prepareSpawnInput(input);
+}
+
+export function prepareSpawnInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new CliError('INVALID_ARGUMENT', 'spawn input must be an object', 2);
+  for (const key of Object.keys(input)) {
+    if (!SPAWN_FIELDS.has(key)) throw new CliError('INVALID_ARGUMENT', `spawn contains unsupported field: ${key}`, 2);
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'subagent') && input.subagent === null) {
+    throw new CliError('INVALID_ARGUMENT', 'subagent must be omitted or a supported subagent id; null is invalid', 2);
+  }
+  if (input.subagent !== undefined && (typeof input.subagent !== 'string' || input.subagent.length === 0)) {
+    throw new CliError('INVALID_ARGUMENT', 'subagent must be a non-empty string', 2);
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'model') && input.model === null) {
+    throw new CliError('INVALID_ARGUMENT', 'model must be omitted or a non-null model token', 2);
+  }
+  if (input.model !== undefined && (typeof input.model !== 'string' || input.model.length === 0)) {
+    throw new CliError('INVALID_ARGUMENT', 'model must be a non-empty string', 2);
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'effort') && input.effort === null) {
+    throw new CliError('INVALID_ARGUMENT', 'effort must be omitted or a non-null effort token', 2);
+  }
+  if (input.effort !== undefined && (typeof input.effort !== 'string' || input.effort.length === 0)) {
+    throw new CliError('INVALID_ARGUMENT', 'effort must be a non-empty string', 2);
+  }
+  return { ...input };
+}

package/cli/commands/update.mjs

@@ -0,0 +1,219 @@
+import { npmUpdateCoordination, reconcileCodexHomes } from '../install/reconcile.mjs';
+import { reconcileZcodeBinding } from '../install/zcode.mjs';
+import { preflightUpdate, reconcileInstallation, updateInstallation } from '../install/update.mjs';
+import { callDaemon, canonicalDaemonCode } from '../rpc.mjs';
+import { CliError } from '../errors.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWrite, jsonBytes } from '../fs-atomic.mjs';
+import { activateService, hasInstalledService } from '../install/service-activation.mjs';
+
+const receiptPath = (paths) => `${paths.state}.activation.json`;
+
+// AUD-003: the ONE bounded reducer over the two supported host integrations.
+// Codex homes and the ZCode binding refresh as part of the same activation,
+// so the top-level verdict must reduce BOTH outcomes on every
+// update/reconcile path — including pure reconcile and service-less runs,
+// where a failed host integration used to hide behind a success receipt.
+// Per-host detail is preserved verbatim for the receipt and the error; an
+// absent zcode binding is not a failure, and an unbound host is never
+// touched.  Returns null when every host is fully reconciled.
+function partialHostSync(result) {
+  const homes = Array.isArray(result?.homes?.homes) ? result.homes.homes : [];
+  const failures = (homes.length > 0 && !result.homes.all_updated
+    ? homes.filter((home) => home.status !== 'updated')
+    : []).map((home) => `codex ${home.home}: ${home.status}${home.error ? ` (${home.error.code}: ${home.error.message})` : ''}`);
+  const zcodeFailed = result?.zcode?.status === 'failed';
+  if (zcodeFailed) {
+    const { error } = result.zcode;
+    failures.push(`zcode: ${error ? `${error.code}: ${error.message}` : 'binding refresh failed'}`);
+  }
+  return failures.length > 0 ? { zcodeFailed, failures } : null;
+}
+
+export async function updateCommand(paths, args = [], daemon = {}) {
+  const cancelActive = args.includes('--cancel-active');
+  const yes = args.includes('--yes');
+  if (cancelActive && !yes) throw new Error('--cancel-active requires --yes');
+  const prior = (() => { try { return JSON.parse(fs.readFileSync(receiptPath(paths), 'utf8')); } catch { return null; } })();
+  const priorStateBytes = (() => { try { return fs.readFileSync(paths.state); } catch { return null; } })();
+  const registryPath = paths.data ? path.join(paths.data, 'codex-homes.json') : null;
+  const priorRegistryBytes = (() => { try { return fs.readFileSync(registryPath); } catch { return null; } })();
+  const requestedVersion = args.find((arg) => arg.startsWith('--version='))?.slice(10) || 'current';
+  const socket = daemon.socket || process.env.ZCODE_AGENTD_SOCKET || paths.socket;
+  const rpc = daemon.callDaemon || callDaemon;
+  const drainDeadline = Number.isFinite(daemon.drainTimeoutMs) && daemon.drainTimeoutMs > 0
+    ? Date.now() + daemon.drainTimeoutMs : null;
+  // npm auto-coordination (U06): an already-initialized product whose
+  // installed package drifted from the published active payload coordinates
+  // through the full update path even when invoked as `reconcile` — the
+  // ignore-scripts flow, where no lifecycle hook ever fired. A matching
+  // version merely re-affirms, and a never-initialized product stays
+  // stage-only.
+  const detected = npmUpdateCoordination(paths);
+  const reconciling = args.includes('reconcile');
+  const coordinate = !reconciling || detected.update_pending;
+  // A doomed candidate must never take the working daemon offline: whenever
+  // this run may activate a payload, the SAME pure validation the locked
+  // updater owns runs BEFORE the drain RPC, so a bad version or manifest
+  // returns with the daemon still serving spawns. A pure reaffirmal that
+  // activates nothing drains only for its claim and needs no candidate.
+  const preflight = daemon.preflightUpdate || preflightUpdate;
+  if (!(reconciling && !coordinate)) preflight({ version: requestedVersion });
+  let status = null;
+  let online = true;
+  try {
+    status = await rpc(socket, 'drain', cancelActive ? { cancel_active: true } : {});
+  } catch (error) {
+    // A legacy daemon answers the cancel_active param with the raw wire code
+    // ("validation"), so the check matches the canonicalized form.
+    if (cancelActive && ['VALIDATION', 'UNKNOWN_METHOD'].includes(canonicalDaemonCode(error.code))) {
+      throw new CliError('CANCEL_ACTIVE_UNSUPPORTED', 'running daemon does not support explicit drain cancellation; cancellation was not downgraded to passive drain');
+    }
+    // No daemon is listening and none answered: an already-initialized
+    // service is (re)started by the activation itself, so there is nothing
+    // to drain and the CLI coordination stays reachable after an
+    // ignore-scripts install. A daemon that ANSWERED with a protocol-level
+    // error still fails loudly instead of being treated as offline.
+    if (error.code !== 'SOCKET_UNAVAILABLE' || error.daemonResponded) throw error;
+    online = false;
+  }
+  if (online) {
+    while (!status.ready_for_activation) {
+      if (drainDeadline !== null && Date.now() >= drainDeadline) {
+        try { await rpc(socket, 'drain-abort', {}); } catch { /* preserve timeout as the primary error */ }
+        throw new CliError('UPDATE_DRAIN_TIMEOUT', 'update drain exceeded its bounded deadline; daemon drain was aborted');
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      status = await rpc(socket, 'drain-status', {});
+    }
+    status = await rpc(socket, 'activate-ready', {});
+  }
+  const claim = online ? status.activation_claim : `offline-${process.pid}-${Date.now()}-activation`;
+  if (!claim) return { ...status, activation_claim: null, update: 'not_activated' };
+  if (prior?.status === 'success' && prior.claim === claim
+    && (requestedVersion === 'current' || prior.version === requestedVersion)) return prior.result;
+  // The rollback source for service activation: the retained copy of the
+  // PREVIOUS active payload, staged outside the npm directory the new
+  // version may already have replaced.
+  const previousActive = (() => {
+    if (!priorStateBytes) return null;
+    try { return JSON.parse(priorStateBytes)?.active ?? null; } catch { return null; }
+  })();
+  const rollbackPayload = previousActive?.retained?.daemon_entry
+    ? { path: previousActive.retained.daemon_entry, sha256: previousActive.retained.daemon_entry_sha256 ?? previousActive.daemon_entry_sha256 }
+    : (previousActive?.daemon_entry ? { path: previousActive.daemon_entry, sha256: previousActive.daemon_entry_sha256 } : null);
+  let result;
+  // Set when the verified activation completed but a host binding sync
+  // (Codex homes, ZCode config) is partial or failed: every such host is
+  // retryable through the public reconcile owner, so the completed
+  // activation stays published and the partial sync is reported AFTER the
+  // guarded block — never as success, and never as a reason to roll a
+  // healthy service or payload back.
+  let partialHosts = null;
+  try {
+    const serviceInstalled = typeof daemon.hasInstalledService === 'function' ? daemon.hasInstalledService(paths) : hasInstalledService(paths);
+    const serviceDue = serviceInstalled && !daemon.skipServiceActivation;
+    result = (reconciling && !coordinate)
+      ? { ...reconcileInstallation(paths, { cancelActive, yes }), homes: reconcileCodexHomes(paths), zcode: reconcileZcodeBinding(paths) }
+      : await (daemon.updateInstallation || updateInstallation)(paths, { version: requestedVersion, deferCodexSync: serviceDue });
+    // The zcode binding has neither a registry nor a service dependency, so
+    // it refreshes on every activation attempt — including service-less
+    // installs, where the codex homes sync runs inside updateInstallation
+    // instead of the service activation block below.
+    if (!result.zcode) result.zcode = reconcileZcodeBinding(paths);
+    if (!result || typeof result !== 'object' || result.phase !== 'active') {
+      throw new Error(`installation update did not activate payload (phase=${result?.phase ?? 'none'})`);
+    }
+    if (serviceDue && coordinate && (!result.active?.entry || !result.active?.entry_sha256
+      || !result.active?.daemon_entry || !result.active?.daemon_entry_sha256)) {
+      // An explicit update exists to switch the service onto the verified
+      // daemon payload; an identity it cannot verify must fail rather than
+      // silently skip activation.
+      throw new CliError('ACTIVE_ENTRY_UNVERIFIED', 'activated payload has no verified daemon artifact to activate');
+    }
+    if (result?.active?.daemon_entry && result?.active?.daemon_entry_sha256 && serviceDue) {
+      const activate = daemon.activateService || activateService;
+      // The LaunchAgent runs the native daemon, so activation carries the
+      // verified daemon artifact identity — never the npm bin shim. Prefer
+      // the retained immutable copy so a later npm replacement cannot alter
+      // the bytes the service executes.
+      const serviceArtifact = result.active.retained?.daemon_entry
+        ? { path: result.active.retained.daemon_entry, sha256: result.active.retained.daemon_entry_sha256 ?? result.active.daemon_entry_sha256 }
+        : { path: result.active.daemon_entry, sha256: result.active.daemon_entry_sha256 };
+      result.service = await activate(paths, {
+        path: serviceArtifact.path,
+        sha256: serviceArtifact.sha256,
+        version: result.active.version,
+      }, { ...daemon, rollbackPayload });
+      result.homes = reconcileCodexHomes(paths);
+    }
+    const receiptVersion = result?.active?.version || result?.version || requestedVersion;
+    partialHosts = partialHostSync(result);
+    atomicWrite(receiptPath(paths), jsonBytes(partialHosts
+      ? { claim, version: receiptVersion, status: 'partial', retryable: true, homes: result.homes, zcode: result.zcode, result }
+      : { claim, version: receiptVersion, status: 'success', result }));
+    if (partialHosts === null) return result;
+  } catch (error) {
+    // Snapshot what the updater recorded before rollback replaces it, so the
+    // receipt keeps the candidate and active evidence the retry will need.
+    const failedInstall = (() => {
+      try { return JSON.parse(fs.readFileSync(paths.state, 'utf8')); } catch { return null; }
+    })();
+    let rollback = { attempted: false, restored: false };
+    if (priorStateBytes && paths.state) {
+      rollback.attempted = true;
+      try { atomicWrite(paths.state, priorStateBytes); rollback.restored = true; } catch (restoreError) { rollback.error = restoreError.message; }
+    } else if (paths.state) {
+      rollback.attempted = true;
+      try { fs.rmSync(paths.state, { force: true }); rollback.restored = true; } catch (restoreError) { rollback.error = restoreError.message; }
+    }
+    if (registryPath) {
+      try {
+        if (priorRegistryBytes) atomicWrite(registryPath, priorRegistryBytes);
+        else if (fs.existsSync(registryPath)) fs.rmSync(registryPath, { force: true });
+      } catch (restoreError) {
+        rollback.registry_error = restoreError.message;
+      }
+    }
+    if (result?.service?.rollback) {
+      try { await result.service.rollback(); rollback.service_restored = true; } catch (restoreError) { rollback.service_error = restoreError.message; }
+    }
+    if (error.rollback) {
+      rollback.service = error.rollback;
+      rollback.service_restored = Boolean(error.rollback.pid && error.rollback.artifact);
+    }
+    const receipt = { claim, version: requestedVersion, status: 'failed', retryable: true, error: error.message, rollback };
+    // This run drained a live daemon and never completed an activation:
+    // bounded recovery reopens admission on the still-running old daemon so
+    // it keeps serving spawns, while its completed-task and reap facts stay
+    // untouched. A daemon that cannot abort (legacy, answering the raw
+    // snake_case wire code) or will not yet (a --cancel-active worker still
+    // in flight) keeps that evidence in the receipt — the canonical abort
+    // code plus an explicit marker that the daemon may still be draining —
+    // and the failure stays retryable; the abort outcome never masks the
+    // original update error.
+    if (online && !result?.service) {
+      try {
+        await rpc(socket, 'drain-abort', {});
+        receipt.drain_aborted = true;
+      } catch (abortError) {
+        receipt.drain_aborted = false;
+        receipt.drain_abort_error = { code: canonicalDaemonCode(abortError.code), message: abortError.message };
+        receipt.daemon_may_be_draining = true;
+      }
+    }
+    if (failedInstall && typeof failedInstall === 'object' && failedInstall.phase) {
+      receipt.install_state = { phase: failedInstall.phase, candidate: failedInstall.candidate ?? null, active: failedInstall.active ?? null };
+    }
+    atomicWrite(receiptPath(paths), jsonBytes(receipt));
+    throw error;
+  }
+  // Reached only with a completed, verified activation whose host binding
+  // sync is partial (AUD-003).  The per-host facts stay actionable — in the
+  // error, the receipt, and the per-host registries the reconcile owners
+  // already persisted — and the public reconcile command finishes the
+  // remaining hosts idempotently.  The activation itself stays published.
+  throw new CliError(partialHosts.zcodeFailed ? 'ZCODE_SYNC_PARTIAL' : 'CODEX_SYNC_PARTIAL',
+    `activation completed at ${result?.active?.version || requestedVersion}, but host binding reconciliation is partial — ${partialHosts.failures.join('; ')}; run 'external-subagent reconcile' after fixing the listed hosts`);
+}

package/cli/config/read.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import { defaultConfig, validateConfig } from './schema.mjs';
+import { CliError } from '../errors.mjs';
+
+function migrateLegacyConfig(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+  if (value.schema_version !== undefined && value.schema_version !== 1) return value;
+  const legacy = Object.hasOwn(value, 'agents') || Object.hasOwn(value, 'default_agent');
+  if (Object.hasOwn(value, 'subagents') || Object.hasOwn(value, 'default_subagent')) {
+    if (legacy || value.schema_version === 1) throw new CliError('CONFIG_INVALID', 'schema-1 config cannot contain canonical subagent fields', 2);
+    return value;
+  }
+  const { agents, default_agent, ...rest } = value;
+  return { ...rest, schema_version: 2, ...(agents === undefined ? {} : { subagents: agents }), ...(default_agent === undefined ? {} : { default_subagent: default_agent }) };
+}
+
+export function parseConfig(value) {
+  return validateConfig(migrateLegacyConfig(value));
+}
+
+export function readConfig(file) {
+  try { return parseConfig(JSON.parse(fs.readFileSync(file, 'utf8'))); }
+  catch (error) { if (error?.code === 'ENOENT') return defaultConfig(); if (error instanceof SyntaxError) error.code = 'CONFIG_INVALID'; throw error; }
+}

package/cli/config/schema.mjs

@@ -0,0 +1,75 @@
+import { CliError } from '../errors.mjs';
+
+export const CONFIG_SCHEMA_VERSION = 2;
+export const SUBAGENT_IDS = Object.freeze(['zcode', 'dsh', 'codex']);
+const CONFIG_FIELDS = new Set(['schema_version', 'revision', 'default_subagent', 'subagents']);
+const AGENT_FIELDS = new Set(['enabled', 'spawn_supported', 'default_model', 'runtime_path', 'home', 'profile', 'version']);
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function rejectUnknownFields(value, allowed, scope) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new CliError('CONFIG_INVALID', `${scope} contains unknown field: ${key}`, 2);
+  }
+}
+
+export function defaultConfig() {
+  return {
+    schema_version: CONFIG_SCHEMA_VERSION,
+    revision: 0,
+    default_subagent: null,
+    subagents: {
+      zcode: { enabled: true, spawn_supported: true, default_model: null },
+      dsh: { enabled: false, spawn_supported: false, default_model: null, runtime_path: null, home: null, profile: null, version: null },
+      codex: { enabled: false, spawn_supported: false, default_model: null, runtime_path: null, home: null, profile: null, version: null },
+    },
+  };
+}
+
+function rejectModel(agent, value, field) {
+  if (agent === 'zcode' && value != null) {
+    throw new CliError('model_selection_unsupported', `${field} is unsupported for zcode`, 2);
+  }
+}
+
+// AUD-005/D1: a zcode runtime_path has no consumer — the service resolves the
+// pinned packaged ZCode runtime itself (see service-macos.mjs) — so the config
+// gate must reject it instead of silently accepting a no-op.  dsh and codex
+// consume runtime_path on every service path and stay configurable.
+function rejectZcodeRuntimePath(agent, value) {
+  if (agent === 'zcode' && value != null) {
+    throw new CliError('runtime_path_unsupported', 'runtime_path is unsupported for zcode: the service resolves the pinned packaged ZCode runtime; only dsh and codex consume runtime_path', 2);
+  }
+}
+
+export function validateConfig(input) {
+  if (!plainObject(input)) throw new CliError('CONFIG_INVALID', 'config must be an object', 2);
+  rejectUnknownFields(input, CONFIG_FIELDS, 'config');
+  const config = defaultConfig();
+  if (input.schema_version !== undefined && input.schema_version !== CONFIG_SCHEMA_VERSION) throw new CliError('CONFIG_INVALID', 'unsupported config schema version', 2);
+  if (input.revision !== undefined && (!Number.isInteger(input.revision) || input.revision < 0)) throw new CliError('CONFIG_INVALID', 'revision must be a non-negative integer', 2);
+  if (input.default_subagent !== undefined && input.default_subagent !== null && !SUBAGENT_IDS.includes(input.default_subagent)) throw new CliError('CONFIG_INVALID', 'default_subagent is unknown', 2);
+  config.revision = input.revision ?? 0;
+  config.default_subagent = input.default_subagent ?? null;
+  if (input.subagents !== undefined && !plainObject(input.subagents)) throw new CliError('CONFIG_INVALID', 'subagents must be an object', 2);
+  for (const agent of Object.keys(input.subagents || {})) {
+    if (!SUBAGENT_IDS.includes(agent)) throw new CliError('CONFIG_INVALID', `subagents contains unknown subagent: ${agent}`, 2);
+  }
+  for (const agent of SUBAGENT_IDS) {
+    const value = input.subagents?.[agent];
+    if (value === undefined) continue;
+    if (!plainObject(value)) throw new CliError('CONFIG_INVALID', `subagents.${agent} must be an object`, 2);
+    rejectUnknownFields(value, AGENT_FIELDS, `subagents.${agent}`);
+    if (value.enabled !== undefined && typeof value.enabled !== 'boolean') throw new CliError('CONFIG_INVALID', `subagents.${agent}.enabled must be boolean`, 2);
+    if (value.spawn_supported !== undefined && typeof value.spawn_supported !== 'boolean') throw new CliError('CONFIG_INVALID', `subagents.${agent}.spawn_supported must be boolean`, 2);
+    if (value.default_model !== undefined && value.default_model !== null && (typeof value.default_model !== 'string' || value.default_model.length === 0)) throw new CliError('CONFIG_INVALID', `subagents.${agent}.default_model must be a non-empty string or null`, 2);
+    for (const field of ['runtime_path', 'home', 'profile', 'version']) { if (value[field] !== undefined && value[field] !== null && (typeof value[field] !== 'string' || value[field].length === 0)) throw new CliError('CONFIG_INVALID', `subagents.${agent}.${field} must be a non-empty string or null`, 2); }
+    rejectModel(agent, value.default_model, 'default_model');
+    rejectZcodeRuntimePath(agent, value.runtime_path);
+    config.subagents[agent] = { ...config.subagents[agent], ...value };
+  }
+  if (config.default_subagent && !config.subagents[config.default_subagent].enabled) throw new CliError('CONFIG_INVALID', 'default_subagent must be enabled', 2);
+  return config;
+}

package/cli/config/write.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { atomicWrite, jsonBytes } from '../fs-atomic.mjs';
+import { validateConfig } from './schema.mjs';
+import { readConfig } from './read.mjs';
+
+export function writeConfig(file, value) {
+  const config = validateConfig(value);
+  config.revision += 1;
+  atomicWrite(file, jsonBytes(config));
+  return config;
+}
+
+export function updateConfig(file, updater) {
+  const lock = `${path.resolve(file)}.lock`;
+  fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+  const ready = `${lock}.${process.pid}.${Date.now()}.ready`;
+  const helper = spawn('/usr/bin/lockf', ['-t', '2', lock, '/bin/sh', '-c',
+    'ready="$1"; parent="$2"; printf ready > "$ready"; while kill -0 "$parent" 2>/dev/null; do sleep 0.05; done',
+    'external-subagent-lock', ready, String(process.pid)], { stdio: 'ignore', detached: true });
+  const wait = new Int32Array(new SharedArrayBuffer(4));
+  const deadline = Date.now() + 2500;
+  while (!fs.existsSync(ready)) {
+    if (helper.exitCode !== null || Date.now() >= deadline) {
+      try { process.kill(-helper.pid, 'SIGTERM'); } catch {}
+      throw new Error('CONFIG_LOCK_TIMEOUT');
+    }
+    Atomics.wait(wait, 0, 0, 5);
+  }
+  try {
+    const current = readConfig(file);
+    const next = updater(current);
+    return writeConfig(file, next);
+  } finally {
+    try { process.kill(-helper.pid, 'SIGTERM'); } catch {}
+    try { fs.unlinkSync(ready); } catch {}
+  }
+}

package/cli/constants.mjs

@@ -0,0 +1,24 @@
+// Development variant: EXTERNAL_SUBAGENT_VARIANT=debug selects a fully
+// parallel installation (its own binaries, state directory, LaunchAgent
+// label, plugin identity, and socket) so a development checkout can run a
+// debug build beside the released product without touching it.  The token is
+// read once at module load; the debug bin shims set it before importing the
+// CLI, so every derived name below is stable for the process lifetime.
+const IS_DEBUG_VARIANT = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug';
+
+export const PRODUCT_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug' : 'external-subagent';
+export const PRODUCT_ID = IS_DEBUG_VARIANT ? 'external_subagent_debug' : 'external_subagent';
+export const VERSION = '0.1.0';
+export const LAUNCH_AGENT_LABEL = IS_DEBUG_VARIANT ? 'com.external-subagent-debug.daemon' : 'com.external-subagent.daemon';
+export const DAEMON_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debugd' : 'external-subagentd';
+export const MCP_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug-mcp' : 'external-subagent-mcp';
+export const NATIVE_DIR_NAME = IS_DEBUG_VARIANT ? 'native-debug' : 'native';
+export const CLI_ENTRY_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug.mjs' : 'external-subagent.mjs';
+export const ZCODE_RUNTIME = '/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs';
+
+export const BUSINESS_COMMANDS = new Set([
+  'init', 'hooks', 'status', 'diagnose', 'backup', 'restore', 'start', 'stop',
+  'uninstall', 'purge', 'cleanup-legacy', 'install-plugin', 'install-mcp', 'create', 'spawn', 'wait', 'list', 'send',
+  'respond', 'cancel', 'result', 'close', 'config', 'agents', 'subagents',
+  'observe', 'update', 'reconcile',
+]);

package/cli/errors.mjs

@@ -0,0 +1,7 @@
+export class CliError extends Error {
+  constructor(code, message, exitCode = 1) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}

package/cli/fs-atomic.mjs

@@ -0,0 +1,36 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+export const jsonBytes = (value) => Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+
+export function atomicWrite(file, bytes, mode = 0o600) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, bytes, { mode, flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally {
+    try { fs.unlinkSync(temporary); } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+export function readOptional(file) {
+  try { return fs.readFileSync(file); } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function restoreOptional(file, bytes) {
+  if (bytes === null) {
+    try { fs.unlinkSync(file); } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  } else {
+    atomicWrite(file, bytes);
+  }
+}