external-subagent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iBobby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# external-subagent
+
+A local service that manages bounded, repository-scoped external subagent
+tasks and exposes them over MCP. Hosts (the applications that call the MCP
+tools) and subagents (the execution targets that run the tasks) are two
+independent axes:
+
+- **Hosts** — Codex (`install-plugin codex` or `install-mcp`), ZCode
+  (`install-plugin zcode`), and any custom local MCP client that connects
+  directly to the facade without registration.
+- **Subagents** — ZCode, DeepSeek Harness (DSH), and Codex, each routed
+  through an internal adapter and subject to the per-subagent limitations
+  listed in [docs/product.md](docs/product.md) and
+  [docs/mcp-api.md](docs/mcp-api.md).
+
+## Status
+
+Current work happens on the `audit/external-subagent-20260917` branch; the
+productization closeout below is the historical record of that stage. DSH and
+ZCode installed-artifact lifecycles, active-task upgrade, and standalone
+initialization are implemented and reviewed. `init` installs the standalone
+daemon service only — no host is bound implicitly; hosts are bound through the
+explicit `install-plugin` (Codex or ZCode) / `install-mcp` (Codex-only TOML
+binding) commands. Installing from a packed artifact and explicitly
+initializing to a launchd-resident service (idempotent repeat init/start) is
+live-verified on a real GUI session. Both productization
+candidates passed the four-cell consumer matrix — DSH/ZCode × public CLI /
+real Codex CLI via the managed plugin over MCP, each against its own tarball:
+the pre-fix candidate C1 (`0.1.1`, historical) and the post-installer-fix
+final candidate C2 (`0.1.2`), whose fresh consumer verification passed
+through the public install surface — all four cells COMPLETED with the
+plugin cache verified against the staged binding (`cache_verified: true`;
+see [docs/acceptance/productization.md](docs/acceptance/productization.md)).
+The managed plugin manifest is versioned per released candidate because its
+version is codex's plugin-cache identity, and codex resolves the reserved
+`personal` marketplace name machine-globally to the real user root
+(regardless of `CODEX_HOME`), so each candidate's consumer runs pin that
+identity's bytes there and any later candidate bumps again. The installer
+re-verified on 0.154.0; DSH admission currently supports `build` and strict
+`plan`; its model selection is explicit spawn model, configured default, then
+the native default. The package is published to the public npm registry as
+`external-subagent@0.1.0` (macOS arm64 only; `os`/`cpu` in `package.json`
+reject installation on other platforms at npm install time).
+
+## Versioning
+
+The product version has a single source: `package.json` (`0.1.0`). The CLI
+constant (`cli/constants.mjs`), the daemon crates, and the native payload
+manifest all carry the same version, and `scripts/release/check-native-tarball.mjs`
+enforces payload/package agreement. The managed Codex plugin manifest
+(`plugins/codex/external-subagent/.codex-plugin/plugin.json`, currently
+`0.1.3`) is deliberately **not** tied to the product version: it is codex's
+plugin-cache identity (`plugin@marketplace@version`; under the reserved
+`personal` marketplace name codex resolves the real user root
+machine-globally, ignoring `CODEX_HOME`), which
+must carry a fresh version per released candidate (`0.1.1` for C1, `0.1.2`
+for C2, `0.1.3` for the boundary-fixes candidate) so no home silently
+receives another installation's cached bytes. The two numbers therefore
+intentionally diverge; see
+[docs/operations.md](docs/operations.md) for the full rule.
+
+## Install
+
+```
+npm install -g external-subagent     # stages package + payload only (macOS arm64)
+external-subagent init               # explicit: standalone daemon service only
+external-subagent install-plugin zcode   # optional host binding (or: install-plugin codex / install-mcp)
+```
+
+Packing and publishing are gated by npm lifecycle scripts: `prepack` always
+rebuilds the native payload from source (so a tarball can never silently ship
+stale or missing binaries) and `postpack` runs the static tarball checks. A
+development checkout packs the same way (`npm pack` after `cargo` is
+available); see [docs/operations.md](docs/operations.md) for release checks.
+
+## Publishing
+
+Releases publish from CI via npm Trusted Publishing (OIDC): pushing a `vX.Y.Z`
+tag runs [.github/workflows/npm-publish.yml](.github/workflows/npm-publish.yml)
+on an Apple Silicon runner, which rebuilds the payload, runs the pack gates,
+and publishes with no npm token in the environment — the runner's OIDC
+identity is the credential. npm does not support trusted publishing for a
+package's first release, so the initial version was published manually once
+and the trusted publisher was then linked on npmjs.com; the workflow filename
+is part of that link and must not be renamed.
+
+A plain install stages the package and payload only. `init` never binds a
+host or touches Codex state; host binding is a separate explicit step
+(`install-plugin codex|zcode`, or `install-mcp` for the direct Codex TOML
+binding), and any custom local MCP client may connect without either. On an
+already initialized installation, npm's postinstall hook detects a local
+version drift and reuses
+the existing reconcile/update owner; it never initializes a fresh home or
+probes a provider. A same-version reinstall does not drift and therefore
+does not trigger that update path — rebind hosts explicitly with
+`external-subagent reconcile` and restart the service per
+[docs/operations.md](docs/operations.md) instead of expecting npm reinstall
+to refresh a running daemon. `init` remains the explicit first activation
+step. A
+completed update whose registered Codex homes only partially rebind reports
+`CODEX_SYNC_PARTIAL` per home and keeps the verified activation; the public
+`stop` confirms launchd removal before returning, and `uninstall` boots out
+the ES-owned service before removing its registration while retaining all
+data. Supported platform: macOS arm64 — `os`/`cpu` in `package.json` make npm
+refuse installation elsewhere up front; the CLI additionally keeps
+`help`/`version` working on other platforms and rejects business commands
+without writing HOME.
+
+See [docs/operations.md](docs/operations.md) for service control, PATH
+behavior, the Codex homes registry, backup/removal, and release checks; and
+[docs/compatibility/codex.md](docs/compatibility/codex.md) for the verified
+codex-cli interface. See [docs/product.md](docs/product.md) for the product
+workflow, provider configuration, and CLI/MCP acceptance boundary.
+
+See [docs/mcp-api.md](docs/mcp-api.md) for the complete MCP tool reference,
+field usage, defaults, design rationale, and omission/removal impacts.
+
+## Development
+
+```
+cargo test --workspace
+node --test tests/install/*.test.mjs tests/platform/*.test.mjs tests/cli/*.test.mjs tests/contract/*.test.mjs
+node --test tests/integration/*.test.mjs tools/probes/dsh-acp/probe.test.mjs
+```

package/bin/external-subagent-debug-mcp.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Debug-variant MCP facade entry: selects the debug payload before
+// delegating to the shared spawn shim.
+process.env.EXTERNAL_SUBAGENT_VARIANT = 'debug';
+await import('./external-subagent-mcp.mjs');

package/bin/external-subagent-debug.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Debug-variant CLI entry: selects the parallel external-subagent-debug
+// installation (own payload, state directory, LaunchAgent, plugin identity,
+// and socket) before the CLI derives any name from the variant token.  The
+// release installation is never touched by commands run through this shim.
+process.env.EXTERNAL_SUBAGENT_VARIANT = 'debug';
+const { main } = await import('../cli/main.mjs');
+
+main(process.argv.slice(2)).catch((error) => {
+  const code = typeof error?.code === 'string' ? error.code : 'INTERNAL_ERROR';
+  process.stderr.write(`${JSON.stringify({ ok: false, error: { code, message: error.message, ...(error.agentId ? { agent_id: error.agentId } : {}), ...(Number.isInteger(error.promptCount) ? { prompt_count: error.promptCount } : {}) } })}\n`);
+  process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+});

package/bin/external-subagent-mcp.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+// The debug shims set EXTERNAL_SUBAGENT_VARIANT before re-entering this file,
+// so the facade resolves to the variant payload staged beside the release one.
+const debug = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug';
+const facade = path.join(packageRoot, 'npm', debug ? 'native-debug' : 'native', 'darwin-arm64',
+  debug ? 'external-subagent-debug-mcp' : 'external-subagent-mcp');
+const child = spawn(facade, process.argv.slice(2), { stdio: 'inherit', env: process.env });
+child.on('error', (error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
+child.on('exit', (code, signal) => {
+  process.exitCode = code ?? (signal ? 1 : 0);
+});

package/bin/external-subagent.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../cli/main.mjs';
+
+main(process.argv.slice(2)).catch((error) => {
+  const code = typeof error?.code === 'string' ? error.code : 'INTERNAL_ERROR';
+  process.stderr.write(`${JSON.stringify({ ok: false, error: { code, message: error.message, ...(error.agentId ? { agent_id: error.agentId } : {}), ...(Number.isInteger(error.promptCount) ? { prompt_count: error.promptCount } : {}) } })}\n`);
+  process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+});

package/bin/zas.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../cli/main.mjs';
+
+main(process.argv.slice(2)).catch((error) => {
+  const code = typeof error?.code === 'string' ? error.code : 'INTERNAL_ERROR';
+  process.stderr.write(`${JSON.stringify({ ok: false, error: { code, message: error.message, ...(error.agentId ? { agent_id: error.agentId } : {}) } })}\n`);
+  process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+});

package/cli/commands/agents.mjs

@@ -0,0 +1,117 @@
+import { readConfig } from '../config/read.mjs';
+import { CliError } from '../errors.mjs';
+
+const INPUT_FIELDS = new Set(['operation', 'subagent', 'through', 'workspace', 'home']);
+
+function validateInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new CliError('INVALID_ARGUMENT', 'subagents input must be an object', 2);
+  for (const key of Object.keys(input)) {
+    if (!INPUT_FIELDS.has(key)) throw new CliError('INVALID_ARGUMENT', `subagents contains unsupported field: ${key}`, 2);
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'subagent')) {
+    if (input.subagent === null) throw new CliError('INVALID_ARGUMENT', 'subagent must be omitted or a supported subagent id; null is invalid', 2);
+    if (typeof input.subagent !== 'string' || input.subagent.length === 0) throw new CliError('INVALID_ARGUMENT', 'subagent must be a non-empty string', 2);
+  }
+}
+
+function parseProbeArgs(rest) {
+  const subagent = rest.shift();
+  if (!subagent || subagent.startsWith('--')) throw new CliError('subagent_required', 'subagents probe requires a subagent', 2);
+  let through = 'local';
+  let selectedLayer = false;
+  const input = { operation: 'probe', subagent };
+  while (rest.length > 0) {
+    const option = rest.shift();
+    if (['--local', '--auth', '--hi'].includes(option)) {
+      if (selectedLayer) throw new CliError('INVALID_ARGUMENT', 'subagents probe accepts exactly one of --local, --auth, or --hi', 2);
+      through = option.slice(2);
+      selectedLayer = true;
+      continue;
+    }
+    if (option === '--workspace' || option === '--home') {
+      const name = option.slice(2);
+      const value = rest.shift();
+      if (!value || value.startsWith('--')) throw new CliError('INVALID_ARGUMENT', `${option} requires a value`, 2);
+      if (input[name] !== undefined) throw new CliError('INVALID_ARGUMENT', `${option} may be provided only once`, 2);
+      input[name] = value;
+      continue;
+    }
+    throw new CliError('INVALID_ARGUMENT', `unsupported subagents probe option: ${option}`, 2);
+  }
+  return { ...input, through };
+}
+
+function parseModelsArgs(rest) {
+  const subagent = rest.shift();
+  if (!subagent || subagent.startsWith('--')) throw new CliError('subagent_required', 'subagents models requires a subagent', 2);
+  const input = { operation: 'models', subagent };
+  while (rest.length > 0) {
+    const option = rest.shift();
+    if (option !== '--workspace' && option !== '--home') throw new CliError('INVALID_ARGUMENT', `unsupported subagents models option: ${option}`, 2);
+    const name = option.slice(2);
+    const value = rest.shift();
+    if (!value || value.startsWith('--')) throw new CliError('INVALID_ARGUMENT', `${option} requires a value`, 2);
+    if (input[name] !== undefined) throw new CliError('INVALID_ARGUMENT', `${option} may be provided only once`, 2);
+    input[name] = value;
+  }
+  return input;
+}
+
+export function parseSubagentsArgs(args) {
+  if (args.length === 0) return { operation: 'list' };
+  const [operation, ...rest] = args;
+  if (!['list', 'status', 'probe', 'models'].includes(operation)) throw new CliError('INVALID_ARGUMENT', `unsupported subagents operation: ${operation}`, 2);
+  if (operation === 'probe') return parseProbeArgs(rest);
+  if (operation === 'models') return parseModelsArgs(rest);
+  if (operation === 'list' && rest.length !== 0) throw new CliError('INVALID_ARGUMENT', 'usage: subagents list', 2);
+  if (operation !== 'list' && rest.length > 1) throw new CliError('INVALID_ARGUMENT', `usage: subagents ${operation} [subagent]`, 2);
+  return { operation, ...(rest[0] ? { subagent: rest[0] } : {}) };
+}
+
+export async function subagentsCommand(paths, input = {}, options = {}) {
+  validateInput(input);
+  const operation = input.operation ?? 'list';
+  const config = readConfig(paths.config);
+  if (operation === 'list') {
+    return { default_subagent: config.default_subagent, config_revision: config.revision, subagents: Object.entries(config.subagents).map(([id, value]) => ({ subagent: id, ...value })) };
+  }
+  if (operation === 'models') {
+    if (typeof options.callDaemon !== 'function' || typeof options.socket !== 'string') throw new CliError('INTERNAL_ERROR', 'subagents models requires a daemon connection');
+    if (!input.subagent) throw new CliError('subagent_required', 'subagents models requires a subagent', 2);
+    const scope = {};
+    if (input.workspace !== undefined) scope.workspace = input.workspace;
+    if (input.home !== undefined) scope.home = input.home;
+    const result = await options.callDaemon(options.socket, 'agent-models', { subagent: input.subagent, scope });
+    return subagentView(result);
+  }
+  if (operation === 'probe') {
+    if (typeof options.callDaemon !== 'function' || typeof options.socket !== 'string') throw new CliError('INTERNAL_ERROR', 'subagents probe requires a daemon connection');
+    if (!input.subagent) throw new CliError('subagent_required', 'subagents probe requires a subagent', 2);
+    const scope = {};
+    if (input.workspace !== undefined) scope.workspace = input.workspace;
+    if (input.home !== undefined) scope.home = input.home;
+    const result = await options.callDaemon(options.socket, 'agent-probe', { subagent: input.subagent, through: input.through ?? 'local', scope });
+    return { ...result, evidence: subagentView(result.evidence), status: subagentView(result.status) };
+  }
+  if (operation !== 'status') throw new CliError('INVALID_ARGUMENT', `unsupported subagents operation: ${operation}`, 2);
+  if (typeof options.callDaemon !== 'function' || typeof options.socket !== 'string') throw new CliError('INTERNAL_ERROR', 'subagents status requires a daemon connection');
+  const status = await options.callDaemon(options.socket, 'status', {});
+  const entries = status.subagents ?? status.agents;
+  if (!Array.isArray(entries)) throw new CliError('PROTOCOL_ERROR', 'daemon status did not include subagent status');
+  const subagents = entries.filter((entry) => input.subagent === undefined || (entry.subagent ?? entry.agent) === input.subagent).map(subagentView);
+  if (input.subagent !== undefined && subagents.length === 0) throw new CliError('subagent_unknown', `daemon did not report subagent: ${input.subagent}`, 2);
+  return { service_generation: status.service_generation ?? null, subagents };
+}
+
+// Source compatibility for internal callers while the public CLI name is
+// `subagents`; wire-level agent fields remain S02's responsibility.
+export const agentsCommand = subagentsCommand;
+export const parseAgentsArgs = parseSubagentsArgs;
+
+// The daemon wire contract is migrated by S02; the CLI already exposes the
+// canonical execution-target name at its own boundary.
+function subagentView(value) {
+  if (!value) return value;
+  const { agent, ...rest } = value;
+  return { subagent: value.subagent ?? agent, ...rest };
+}

package/cli/commands/config.mjs

@@ -0,0 +1,117 @@
+import { readConfig } from '../config/read.mjs';
+import { updateConfig, writeConfig } from '../config/write.mjs';
+import { SUBAGENT_IDS } from '../config/schema.mjs';
+import { CliError } from '../errors.mjs';
+
+const CONFIG_INPUT_FIELDS = new Set(['operation', 'patch', 'key']);
+const GET_KEYS = new Set([
+  'default_subagent',
+  ...SUBAGENT_IDS.flatMap((agent) => [`subagents.${agent}.enabled`, `subagents.${agent}.spawn_supported`, `subagents.${agent}.default_model`, `subagents.${agent}.runtime_path`, `subagents.${agent}.home`, `subagents.${agent}.profile`, `subagents.${agent}.version`]),
+]);
+const SET_KEYS = GET_KEYS;
+
+function rejectUnknownInput(input, allowed = CONFIG_INPUT_FIELDS) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new CliError('INVALID_ARGUMENT', 'config input must be an object', 2);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) throw new CliError('INVALID_ARGUMENT', `config contains unsupported field: ${key}`, 2);
+  }
+}
+
+function parseValue(raw) {
+  if (raw === 'null') return null;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  return raw;
+}
+
+function patchFor(key, value) {
+  if (!SET_KEYS.has(key)) throw new CliError('INVALID_ARGUMENT', `unsupported config key: ${key}`, 2);
+  const parts = key.split('.');
+  if (parts.length === 1) return { [key]: value };
+  return { subagents: { [parts[1]]: { [parts[2]]: value } } };
+}
+
+function unsetPatch(key) {
+  if (!SET_KEYS.has(key)) throw new CliError('INVALID_ARGUMENT', `unsupported config key: ${key}`, 2);
+  if (key === 'default_subagent') return { default_subagent: null };
+  const [, agent, field] = key.split('.');
+  const defaults = {
+    enabled: agent === 'zcode',
+    spawn_supported: agent === 'zcode',
+    default_model: null, runtime_path: null, home: null, profile: null, version: null,
+  };
+  return { subagents: { [agent]: { [field]: defaults[field] } } };
+}
+
+function valueFor(config, key) {
+  if (!GET_KEYS.has(key)) throw new CliError('INVALID_ARGUMENT', `unsupported config key: ${key}`, 2);
+  return key.split('.').reduce((value, part) => value?.[part], config);
+}
+
+function mergePatch(current, patch) {
+  return {
+    ...current,
+    ...patch,
+    subagents: {
+      ...current.subagents,
+      ...Object.fromEntries(Object.entries(patch.subagents || {}).map(([agent, value]) => [
+        agent,
+        { ...current.subagents[agent], ...value },
+      ])),
+    },
+  };
+}
+
+export function parseConfigArgs(args) {
+  if (args.length === 0) return { operation: 'get' };
+  const [operation, ...rest] = args;
+  if (operation === 'get') {
+    if (rest.length > 1) throw new CliError('INVALID_ARGUMENT', 'usage: config get [key]', 2);
+    return { operation, ...(rest[0] ? { key: rest[0] } : {}) };
+  }
+  if (operation === 'set') {
+    if (rest.length !== 2) throw new CliError('INVALID_ARGUMENT', 'usage: config set <key> <value>', 2);
+    return { operation, patch: patchFor(rest[0], parseValue(rest[1])) };
+  }
+  if (operation === 'show') {
+    if (rest.length !== 0) throw new CliError('INVALID_ARGUMENT', 'usage: config show', 2);
+    return { operation };
+  }
+  if (operation === 'unset') {
+    if (rest.length !== 1) throw new CliError('INVALID_ARGUMENT', 'usage: config unset <key>', 2);
+    unsetPatch(rest[0]);
+    return { operation, key: rest[0] };
+  }
+  throw new CliError('INVALID_ARGUMENT', `unsupported config operation: ${operation}`, 2);
+}
+
+export function configCommand(paths, input = {}) {
+  rejectUnknownInput(input);
+  const operation = input.operation ?? 'get';
+  const current = readConfig(paths.config);
+  if (operation === 'set') {
+    if (!input.patch || typeof input.patch !== 'object' || Array.isArray(input.patch)) throw new CliError('INVALID_ARGUMENT', 'config set requires an object patch', 2);
+    if (Object.hasOwn(input.patch, 'revision')) throw new CliError('INVALID_ARGUMENT', 'config revision is managed by the writer', 2);
+    if (input.patch.subagents !== undefined && (!input.patch.subagents || typeof input.patch.subagents !== 'object' || Array.isArray(input.patch.subagents))) {
+      throw new CliError('INVALID_ARGUMENT', 'config subagents patch must be an object', 2);
+    }
+    for (const [agent, value] of Object.entries(input.patch.subagents || {})) {
+      if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new CliError('CONFIG_INVALID', `subagents.${agent} must be an object`, 2);
+    }
+    return { config: updateConfig(paths.config, (latest) => mergePatch(latest, input.patch)) };
+  }
+  if (operation === 'show') {
+    if (input.patch !== undefined || input.key !== undefined) throw new CliError('INVALID_ARGUMENT', 'config show does not accept key or patch', 2);
+    return { config: current };
+  }
+  if (operation === 'unset') {
+    if (input.patch !== undefined || typeof input.key !== 'string') throw new CliError('INVALID_ARGUMENT', 'config unset requires exactly one supported key', 2);
+    return { config: updateConfig(paths.config, (latest) => mergePatch(latest, unsetPatch(input.key))) };
+  }
+  if (operation === 'get') {
+    if (input.patch !== undefined) throw new CliError('INVALID_ARGUMENT', 'config get does not accept patch', 2);
+    if (input.key === undefined) return { config: current };
+    return { key: input.key, value: valueFor(current, input.key), revision: current.revision };
+  }
+  throw new CliError('INVALID_ARGUMENT', `unsupported config operation: ${operation}`, 2);
+}

package/cli/commands/daemon.mjs

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import { bootoutService, bootstrapService } from '../install/service-macos.mjs';
+import { loadCodexHomes } from '../install/reconcile.mjs';
+import { verifyPayload } from '../install/payload.mjs';
+
+// Daemon/service command surface: explicit start/stop through the managed
+// LaunchAgent, and the local installation summary consumed by `status`.
+
+export function startDaemon(paths) {
+  return bootstrapService(paths);
+}
+
+export function stopDaemon(paths) {
+  return bootoutService(paths);
+}
+
+export function localInstallStatus(paths, { verbose = false } = {}) {
+  let payload = { status: 'unverified' };
+  try { payload = verifyPayload(); } catch (error) {
+    payload = { status: 'invalid', error: { code: error.code || 'PAYLOAD_INVALID', message: error.message } };
+  }
+  const registry = loadCodexHomes(paths);
+  const publicPayload = verbose
+    ? payload
+    : { status: payload.status, platform: payload.platform, version: payload.version };
+  return {
+    installed: fs.existsSync(paths.state),
+    launch_agent: fs.existsSync(paths.launchAgent),
+    data: fs.existsSync(paths.data),
+    payload: publicPayload,
+    // Home paths are installation internals; status reports only the
+    // aggregate binding state. Detailed paths remain available to diagnose.
+    codex_homes: registry.registry.homes.map((entry) => ({ version: entry.version, last_status: entry.last_status })),
+    ...(verbose && registry.recovery ? { codex_homes_recovery: registry.recovery } : {}),
+  };
+}

package/cli/commands/maintenance.mjs

@@ -0,0 +1,27 @@
+import { backupData, cleanupLegacy, purge, restoreData, uninstall as removeService } from '../maintenance.mjs';
+import { unregisterAllCodexHomes } from '../install/reconcile.mjs';
+import { uninstallZcodePlugin } from '../install/zcode.mjs';
+
+// Maintenance command coordination.  The ES-owned service is booted out and
+// its definition removed before any D08 claim is released: a bootout that
+// cannot complete fails the command with the registry exactly as it was, so
+// an uninstall retry (or a reconcile) still sees every claimed home instead
+// of a wiped registry.  Only a fully removed service releases the claims;
+// product data is retained by contract, and the emptied registry travels
+// with it so no home remains claimed.  The stateless ZCode binding is
+// released the same way: the product-owned staging tree and its single
+// plugins.dirs entry go away together.
+
+export function uninstall(paths, options = {}) {
+  const removed = removeService(paths, options);
+  const released = unregisterAllCodexHomes(paths);
+  // An unreadable ZCode config is foreign state, not a product claim: report
+  // the release failure instead of failing the whole uninstall over it.
+  let zcode;
+  try { zcode = uninstallZcodePlugin(paths); } catch (error) {
+    zcode = { uninstalled: false, error: { code: error.code || 'ZCODE_BINDING_FAILED', message: error.message } };
+  }
+  return { ...removed, codex_homes_unregistered: released.unregistered, zcode_binding: zcode };
+}
+
+export { backupData, cleanupLegacy, purge, restoreData };

package/cli/commands/plugin.mjs

@@ -0,0 +1,96 @@
+import { CliError } from '../errors.mjs';
+import { installMcp, installPlugin, uninstallPlugin } from '../install/codex.mjs';
+import { installZcodePlugin, uninstallZcodePlugin } from '../install/zcode.mjs';
+import { registerCodexHome, unregisterCodexHome } from '../install/reconcile.mjs';
+import { verifyPayload } from '../install/payload.mjs';
+
+// Command surface for the managed host bindings.  `install-plugin` takes an
+// optional host argument: codex (the default, for backward compatibility)
+// stages the plugin and goes through the official codex CLI, claiming the
+// Codex home in the D08 registry; zcode stages the same plugin into a
+// product-owned tree and registers it through the ZCode config's inline
+// plugin dirs.  The MCP TOML binding stays an explicit codex-only
+// alternative for hosts without plugin support.
+
+const PLUGIN_HOSTS = ['codex', 'zcode'];
+
+function parseCommon(args, flags) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith('--')) {
+      if (options.host) throw new CliError('INVALID_ARGUMENT', `plugin host was already given: ${options.host}`, 2);
+      if (!PLUGIN_HOSTS.includes(arg)) throw new CliError('INVALID_ARGUMENT', `unsupported plugin host: ${arg} (expected ${PLUGIN_HOSTS.join(' or ')})`, 2);
+      options.host = arg;
+    } else if (flags.includes(arg)) {
+      options[flagName(arg)] = true;
+    } else if (arg === '--codex-home') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new CliError('INVALID_ARGUMENT', '--codex-home requires a value', 2);
+      options.codexHome = value;
+      index += 1;
+    } else {
+      throw new CliError('INVALID_ARGUMENT', `unsupported plugin option: ${arg}`, 2);
+    }
+  }
+  return options;
+}
+
+function flagName(flag) {
+  return flag.replace(/^--/u, '').replaceAll('-', '_');
+}
+
+export function pluginCommand(paths, args) {
+  const options = parseCommon(args, ['--dry-run', '--uninstall']);
+  const installerOptions = withInstallerFlags(options);
+  if (options.host === 'zcode') {
+    if (options.codexHome) throw new CliError('INVALID_ARGUMENT', '--codex-home applies to the codex host only', 2);
+    return options.uninstall ? uninstallZcodePlugin(paths, installerOptions) : installZcodePlugin(paths, installerOptions);
+  }
+  if (options.uninstall) {
+    const result = uninstallPlugin(paths, installerOptions);
+    if (!options.dry_run && result.uninstalled) {
+      const claim = unregisterCodexHome(paths, result.codex_home, 'plugin');
+      result.claim_released = claim.unregistered;
+    }
+    return result;
+  }
+  const result = installPlugin(paths, installerOptions);
+  if (!options.dry_run && result.installed) {
+    const payload = safePayloadVersion();
+    const claim = registerCodexHome(paths, result.codex_home, { version: payload, digest: result.digest, binding_mode: 'plugin' });
+    result.claim = { registered: claim.registered, deduplicated: claim.deduplicated, homes: claim.homes };
+  }
+  return result;
+}
+
+export function mcpCommand(paths, args) {
+  const options = parseCommon(args, ['--dry-run', '--uninstall']);
+  // The MCP TOML binding is codex-only (see the header note): a non-codex
+  // host must fail here, before any installer or registry call, instead of
+  // being silently ignored while the codex config is rewritten.
+  if (options.host && options.host !== 'codex') {
+    throw new CliError('INVALID_ARGUMENT', `unsupported mcp host: ${options.host} (install-mcp binds the codex host only)`, 2);
+  }
+  const installerOptions = withInstallerFlags(options);
+  const result = installMcp(paths, installerOptions);
+  if (!options.dry_run && result.installed) {
+    const claim = registerCodexHome(paths, result.codex_home || installerOptions.codexHome, { binding_mode: 'mcp', status: 'claimed' });
+    result.claim = { registered: claim.registered, deduplicated: claim.deduplicated, homes: claim.homes };
+  } else if (!options.dry_run && options.uninstall) {
+    const claim = unregisterCodexHome(paths, result.codex_home || installerOptions.codexHome, 'mcp');
+    result.claim_released = claim.unregistered;
+  }
+  return result;
+}
+
+// The install layer speaks camelCase (dryRun); CLI parsing produces snake_case
+// flags.  Normalize at the boundary so --dry-run actually holds the installers
+// back instead of running a real install/uninstall.
+function withInstallerFlags(options) {
+  return { ...options, dryRun: Boolean(options.dry_run) };
+}
+
+function safePayloadVersion() {
+  try { return verifyPayload().version; } catch { return null; }
+}