@volter/supercode-orchestrator 0.4.4

package/bin/orchestrator.mjs

@@ -0,0 +1,730 @@
+#!/usr/bin/env node
+// The orchestrator daemon entry (ORC-7).
+//
+//   node bin/orchestrator.mjs --root <home> [--once]
+//   node bin/orchestrator.mjs access <verb> [args] [--root <home>] [--profile <name>]
+//
+// `supercode orchestrator start` spawns the daemon form; the daemon itself
+// writes the lease (`<home>/orchestrator.lock`) naming this process and
+// removes it on the way out, so a service-managed daemon reports the same
+// lease a foreground one does. `supercode orchestrator stop` sends SIGTERM.
+// A lock left behind by a process that is gone is the mark of a daemon that
+// died: this one dispatches `restart` (§4.7) before it accepts anything.
+//
+// The `access` form is the COLD path of §4.6's operator verbs: it loads the
+// home, applies the reducer's own event, and saves through `save()`. It is
+// the only writer of the folder — `supercode orchestrator pair|access ...`
+// spawns this rather than encoding the YAML a second time.
+//
+// It is deliberately thin: load the home strictly through the IR, build the
+// `Orchestrator` (ORC-4/ORC-5) over a `SupercodeHarnessClient` and the adapters
+// the profiles' `platforms:` blocks name, `start()` it, and stay up until
+// SIGTERM — at which point `stop()` closes the tick, the webhook listener,
+// every runtime and every adapter. The loop owns its own clock and its own
+// `/webhooks/<name>` listener; nothing here schedules or serves anything. The
+// only policy in this file is which adapter class serves which platform:
+// `loopback`, the `api_server`-compatible HTTP surface, and the Chat SDK
+// sidecar a block selects with `extra.adapter: chat-sdk` (§7, ORC-9).
+//
+// Beside the daemon it carries the two migration verbs (ORC-12):
+//
+//   node bin/orchestrator.mjs import --from hermes|openclaw [--home <path>] [--into <root>]
+//   node bin/orchestrator.mjs export --to   hermes|openclaw [--from <root>] [--into <dest>]
+//
+// `import` is a compile followed by a `save`; `export` is the codec, and it
+// prints the tier of every file it wrote. A refused write (the session half,
+// behind the UNI-22 stability gate) prints its reason and exits 2 — a partial
+// migration is never reported as a whole one.
+//
+// And it carries the COLD PATH of the operator door (ORC-13, §4.6):
+//
+//   node bin/orchestrator.mjs <op> --root <home> [--profile <p>] --json '<args>'
+//
+// where `<op>` is one of `operator.mjs`'s `OPERATOR_OPS`. It loads the home,
+// applies the verb through the very same `applyOperator` the daemon's socket
+// uses, performs the effects (`save`, `remove_profile_dir`) and prints one
+// `{ok, result}` line — the identical answer the socket gives, so `supercode
+// jobs create --harness orchestrator` writes the same bytes whether the daemon
+// is up or down. It exits 0 on `ok`, 1 on a refusal.
+//
+// Everything it prints is one JSON object per line on stdout.
+
+import { existsSync, mkdirSync, rmdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { LOCK_FILE, leaseIsLive, readLease, thisHost } from '../lease.mjs';
+import { socketPathFor } from '../mcp/server.mjs';
+import { GATEWAY_KIND, holdGatewayLock } from '../hermes-locks.mjs';
+import { adoptHome } from '../hermes-home.mjs';
+import { hermesAccess } from '../hermes-cli.mjs';
+
+import {
+  load, save, step, importFrom, exportTo, closeWorld, Orchestrator, LoopbackAdapter,
+  ChatSdkAdapter, ApiServerAdapter, Rh2Adapter,
+  TICK_MS, accessPolicy, applyOperator, performRemoveProfileDir, OPERATOR_OPS,
+} from '../index.mjs';
+import * as events from '../events.mjs';
+import { httpJobExecutor } from '../hosted.mjs';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+
+/// Adapter selector -> constructor. A `platforms:` block picks its adapter by
+/// `extra.adapter` when it has one and by the block's own name otherwise, so
+/// `platforms.slack.extra.adapter: chat-sdk` and `platforms.api_server` both
+/// resolve here. §7's build order is loopback, then the api_server-compatible
+/// HTTP surface, then the Chat SDK sidecar (ORC-9); Claude Code's channel
+/// plugins are NOT an adapter family (ORC-1 F4) and have no entry. A block
+/// whose selector is missing here is reported and left unconnected, never faked.
+const ADAPTERS = {
+  loopback: (platform, profile) => new LoopbackAdapter({ platform, profile }),
+  'chat-sdk': (platform, profile, ctx) => new ChatSdkAdapter({ platform, profile, profileDir: ctx.state.profiles[profile]?.dir ?? null, channel: ctx.channel, vault: ctx.vault, log: ctx.log }),
+  api_server: (platform, profile, ctx) => new ApiServerAdapter({ platform, profile, channel: ctx.channel, vault: ctx.vault, state: ctx.state, log: ctx.log }),
+  rh2: (platform, profile, ctx) => new Rh2Adapter({ platform, profile, channel: ctx.channel, vault: ctx.vault, log: ctx.log }),
+};
+
+/// The selector a `platforms:` block resolves through: its `extra.adapter`
+/// when it names one (the loader prefixes `extra:` keys with `extra.`), else
+/// the block's own name.
+function adapterSelector(platform, channel) {
+  const named = channel?.extra?.['extra.adapter'] ?? channel?.extra?.adapter;
+  if (typeof named === 'string' && named) return named;
+  // a Hermes-shaped slack/telegram/discord block is served by the Chat SDK
+  // sidecar, with Hermes's own variables and ingress (HERMES_PLATFORMS)
+  return ['slack', 'telegram', 'discord'].includes(platform) ? 'chat-sdk' : platform;
+}
+
+function parseArgs(argv) {
+  const args = { root: null, once: false, version: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const take = () => {
+      const value = argv[i + 1];
+      i += 1;
+      return value;
+    };
+    if (arg === '--executor-url') args.executorUrl = take();
+    else if (arg === '--executor-token-file') args.executorTokenFile = take();
+    else if (arg === '--root') args.root = take();
+    else if (arg.startsWith('--root=')) args.root = arg.slice('--root='.length);
+    else if (arg === '--once') args.once = true;
+    else if (arg === '--version') args.version = true;
+    else throw new Error(`unknown argument \`${arg}\``);
+  }
+  return args;
+}
+
+function say(event, fields) {
+  process.stdout.write(`${JSON.stringify({ event, ...fields })}\n`);
+}
+
+function packageVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version;
+}
+
+function defaultRoot() {
+  return process.env.SUPERCODE_ORCHESTRATOR_HOME || join(homedir(), '.supercode/orchestrator');
+}
+
+// --------------------------------------------------------------- migration
+
+/**
+ * Each gateway harness's own home resolution, mirrored exactly (the same
+ * semantics `crates/interchange/src/catalog.rs` mirrors), so an inherited
+ * environment means the same thing here as to the harness itself.
+ */
+const HOMES = {
+  hermes: () => process.env.HERMES_HOME || join(homedir(), '.hermes'),
+  openclaw: () => process.env.OPENCLAW_STATE_DIR
+    || (process.env.OPENCLAW_HOME ? join(process.env.OPENCLAW_HOME, '.openclaw') : null)
+    || join(homedir(), '.openclaw'),
+};
+
+function parseMigrationArgs(argv, verb) {
+  const args = { harness: null, home: null, into: null };
+  const harnessFlag = verb === 'import' ? '--from' : '--to';
+  const homeFlag = verb === 'import' ? '--home' : '--from';
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const take = () => { const value = argv[i + 1]; i += 1; return value; };
+    if (arg === harnessFlag) args.harness = take();
+    else if (arg.startsWith(`${harnessFlag}=`)) args.harness = arg.slice(harnessFlag.length + 1);
+    else if (arg === homeFlag) args.home = take();
+    else if (arg.startsWith(`${homeFlag}=`)) args.home = arg.slice(homeFlag.length + 1);
+    else if (arg === '--into') args.into = take();
+    else if (arg.startsWith('--into=')) args.into = arg.slice('--into='.length);
+    else throw new Error(`unknown argument \`${arg}\``);
+  }
+  if (!args.harness) throw new Error(`\`${verb}\` needs ${harnessFlag} ${Object.keys(HOMES).join('|')}`);
+  if (!HOMES[args.harness]) {
+    throw new Error(`unknown harness \`${args.harness}\`; ${verb} supports: ${Object.keys(HOMES).join(', ')}`);
+  }
+  return args;
+}
+
+function profileCounts(state) {
+  return Object.entries(state.profiles).map(([name, profile]) => profileReport(name, profile));
+}
+
+/**
+ * `import --from <harness>`: that harness's home becomes our folder, through
+ * `world.import` — a compile and a save composed in the harness process, so
+ * the credentials land in our `.env` without crossing the wire, and the
+ * files the world does not model (`MEMORY.md`, `skills/`, an agent's
+ * transcripts) are carried by path.
+ */
+async function runImport(argv) {
+  const args = parseMigrationArgs(argv, 'import');
+  const home = resolve(args.home ?? HOMES[args.harness]());
+  const into = resolve(args.into ?? defaultRoot());
+  const imported = await importFrom(args.harness, home, into);
+  say('imported', {
+    from: args.harness,
+    home,
+    into,
+    profiles: profileCounts(imported.orchestration),
+    carried: imported.carried,
+    secrets: [...imported.vault_keys].sort(),
+  });
+  return 0;
+}
+
+/**
+ * `export --to <harness>`: our folder becomes that harness's home, through
+ * `world.export`. Our `state.db` is never a Hermes session store — it carries
+ * the world's `bindings`, not Hermes's `sessions` — so the codec's own UNI-22
+ * gate refuses the session half, and a refused half is exit 2, never a whole
+ * migration.
+ */
+async function runExport(argv) {
+  const args = parseMigrationArgs(argv, 'export');
+  const root = resolve(args.home ?? defaultRoot());
+  const into = resolve(args.into ?? join(root, `export-${args.harness}`));
+  const report = await exportTo(args.harness, root, into);
+  say('exported', {
+    to: args.harness,
+    root,
+    into,
+    written: report.written,
+    notes: report.notes ?? [],
+    refused: report.refused,
+  });
+  for (const refusal of report.refused) say('refused', { file: refusal.file, reason: refusal.reason });
+  return report.refused.length ? 2 : 0;
+}
+
+// --------------------------------------------------------------- operator
+
+/**
+ * `<op> --root <home> [--profile <p>] [--json '<args>']` — the cold path of
+ * the operator door.
+ *
+ * One code path with the daemon: `applyOperator` is the same function the
+ * socket calls, and the effects it produces are performed here exactly as the
+ * loop performs them (`save` writes the folder through `save()`;
+ * `remove_profile_dir` moves a deleted profile's folder into
+ * `profiles/.trash/`). Nothing else runs — no adapters, no tick, no worker.
+ */
+/** One JSON line to a live daemon's operator door and its one-line answer. */
+async function overSocket(path, request) {
+  const { createConnection } = await import('node:net');
+  return new Promise((resolve) => {
+    const socket = createConnection(path);
+    let buffer = '';
+    const done = (answer) => { socket.destroy(); resolve(answer); };
+    socket.setTimeout(30_000, () => done({ ok: false, error: `the daemon's door at ${path} did not answer` }));
+    socket.once('connect', () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      const nl = buffer.indexOf('\n');
+      if (nl < 0) return;
+      try { done(JSON.parse(buffer.slice(0, nl))); } catch { done({ ok: false, error: 'the daemon answered with no JSON' }); }
+    });
+    socket.once('error', (error) => done({ ok: false, error: `the daemon's lease is live but its door refused: ${error.message}` }));
+  });
+}
+
+function parseOperatorArgs(argv) {
+  const args = { root: null, profile: 'default', json: '{}', at: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const take = () => { const value = argv[i + 1]; i += 1; return value; };
+    if (arg === '--root') args.root = take();
+    else if (arg.startsWith('--root=')) args.root = arg.slice('--root='.length);
+    else if (arg === '--profile') args.profile = take();
+    else if (arg.startsWith('--profile=')) args.profile = arg.slice('--profile='.length);
+    else if (arg === '--json') args.json = take();
+    else if (arg.startsWith('--json=')) args.json = arg.slice('--json='.length);
+    // An injected clock, so a receipt is reproducible. Never a default.
+    else if (arg === '--at') args.at = take();
+    else if (arg.startsWith('--at=')) args.at = arg.slice('--at='.length);
+    else throw new Error(`unknown argument \`${arg}\``);
+  }
+  return args;
+}
+
+async function runOperator(op, argv) {
+  const args = parseOperatorArgs(argv);
+  const root = resolve(args.root ?? defaultRoot());
+  let payload;
+  try {
+    payload = JSON.parse(args.json || '{}');
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: `--json is not JSON: ${error.message}` })}\n`);
+    return 1;
+  }
+  // A live daemon holds the home's state in memory and re-saves it: a write made beside it would be lost on its next
+  // save. While its lease is live the verb goes over its socket, as supercode's own client sends it (ORC-13).
+  const lease = readLease(root);
+  if (lease && leaseIsLive(lease)) {
+    const answer = await overSocket(socketPathFor(root), { op, args: payload, profile: args.profile });
+    process.stdout.write(`${JSON.stringify({ ...answer, root, door: 'live', context_profile: args.profile })}\n`);
+    return answer.ok ? 0 : 1;
+  }
+  let state;
+  let vault;
+  try {
+    ({ state, vault } = await load(root));
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: `${root}: ${String(error.message ?? error)}` })}\n`);
+    return 1;
+  }
+  const now = args.at ?? new Date().toISOString();
+  const logs = [];
+  const dispatch = async (event) => {
+    const effects = step(state, event);
+    for (const effect of effects) {
+      if (effect.type === 'save') await save(state, root);
+      else if (effect.type === 'remove_profile_dir') performRemoveProfileDir(root, effect, now);
+      else if (effect.type === 'log') logs.push(`${effect.level}: ${effect.message}`);
+      // Every other effect needs a running loop (a worker, an adapter). The
+      // cold path performs none of them and says so rather than pretending.
+      else logs.push(`skipped: ${effect.type} needs the daemon`);
+    }
+    return effects;
+  };
+  const answer = await applyOperator(state, op, payload, args.profile, now, dispatch);
+  // `root`/`door` ride BESIDE the result, never inside it: `profiles.create`
+  // answers with a `profile` record of its own, and the door must not clobber
+  // the verb's own row.
+  const line = answer.ok
+    ? { ok: true, result: answer.result, root, door: 'cold', context_profile: args.profile }
+    : { ok: false, error: answer.error, root, door: 'cold', context_profile: args.profile };
+  if (logs.length) line.log = logs;
+  process.stdout.write(`${JSON.stringify(line)}\n`);
+  return answer.ok ? 0 : 1;
+}
+
+/**
+ * One adapter per (platform, owning profile) named by an enabled `platforms:`
+ * block. A platform whose adapter does not exist yet is listed as
+ * `unsupported`: the daemon never pretends a channel is connected.
+ */
+function buildAdapters(state, vault = new Map(), log = () => {}) {
+  const adapters = {};
+  const report = [];
+  for (const [profileName, profile] of Object.entries(state.profiles)) {
+    for (const [platform, channel] of Object.entries(profile.channels)) {
+      if (!channel.enabled) {
+        report.push({ platform, profile: profileName, state: 'disabled' });
+        continue;
+      }
+      if (adapters[platform]) {
+        report.push({ platform, profile: profileName, state: 'already owned by another profile' });
+        continue;
+      }
+      const selector = adapterSelector(platform, channel);
+      const make = ADAPTERS[selector];
+      if (!make) {
+        report.push({ platform, profile: profileName, state: `unsupported (no adapter \`${selector}\` for this platform yet)` });
+        continue;
+      }
+      adapters[platform] = make(platform, profileName, { channel, state, vault, log });
+      report.push({ platform, profile: profileName, adapter: selector, state: 'connecting' });
+    }
+  }
+  return { adapters, report };
+}
+
+function profileReport(name, profile) {
+  return {
+    profile: name,
+    dir: profile.dir,
+    worker: profile.worker ? profile.worker.harness : null,
+    model: profile.worker?.model ?? null,
+    jobs: Object.keys(profile.jobs).length,
+    routes: profile.routes.length,
+    subscriptions: Object.keys(profile.subscriptions).length,
+    bindings: Object.keys(profile.bindings).length,
+    fires: profile.fires.length,
+    obligations: profile.obligations.length,
+  };
+}
+
+// ---------------------------------------------------------------- the lease
+
+/** The lease file, shared with `supercode orchestrator status|stop` (Rust `Lease`). */
+const readLock = readLease;
+
+function writeLock(root, lease) {
+  writeFileSync(join(root, LOCK_FILE), `${JSON.stringify(lease, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+}
+
+/** Only ever removes a lease this process holds. */
+function clearLock(root) {
+  const held = readLock(root);
+  if (held && held.pid !== process.pid) return;
+  try { unlinkSync(join(root, LOCK_FILE)); } catch { /* already gone */ }
+}
+
+// ---------------------------------------------------------------- access verbs
+
+/** `<verb> <positional...>` -> the operator event §4.6 defines for it. */
+
+function parseAccessArgs(argv) {
+  const args = { root: null, profile: 'default', rest: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--root') args.root = argv[(i += 1)];
+    else if (arg.startsWith('--root=')) args.root = arg.slice('--root='.length);
+    else if (arg === '--profile') args.profile = argv[(i += 1)];
+    else if (arg.startsWith('--profile=')) args.profile = arg.slice('--profile='.length);
+    else if (arg.startsWith('--')) throw new Error(`unknown argument \`${arg}\``);
+    else args.rest.push(arg);
+  }
+  return args;
+}
+
+/** Pending pairings as Hermes's pairing store lists them (codes are stored hashed; a row names who asked). */
+function pairingRows(profile) {
+  return hermesAccess(profile.dir, 'pending').map((p) => ({ ...p, policy: accessPolicy(profile, p.platform) }));
+}
+
+function accessReport(root, name, profile, extra = {}) {
+  return {
+    root,
+    profile: name,
+    policy: profile.access.policy,
+    default_policy: 'allowlist',
+    allowlist: profile.access.allowlist,
+    admins: profile.access.admins,
+    pending: pairingRows(profile),
+    ...extra,
+  };
+}
+
+/** What each access verb asks of Hermes's own store and writers (docs/plans/hermes-compat.md row 8). */
+const ACCESS_OPS = {
+  'pair-approve': (profile, rest) => ['approve', { code: rest[0], platforms: [...new Set([...Object.keys(profile.channels ?? {}), ...hermesAccess(profile.dir, 'pending').map((p) => p.platform)])] }],
+  allow: (profile, rest) => ['allow', { platform: rest[0], user_id: rest[1] }],
+  revoke: (profile, rest) => ['revoke', { platform: rest[0], user_id: rest[1] }],
+  'admin-add': (profile, rest) => ['admin_add', { platform: rest[0], user_id: rest[1] }],
+  'admin-remove': (profile, rest) => ['admin_remove', { platform: rest[0], user_id: rest[1] }],
+};
+
+/**
+ * `access <verb> ...`: the COLD path. Access lives in Hermes's stores, so each verb is performed through
+ * Hermes's own pairing store and writers, then the home is loaded again to report what stands.
+ */
+async function accessMain(argv) {
+  let parsed;
+  try {
+    parsed = parseAccessArgs(argv);
+  } catch (error) {
+    say('error', { message: error.message });
+    process.exit(2);
+  }
+  const [verb, ...rest] = parsed.rest;
+  const root = resolve(parsed.root ?? defaultRoot());
+  let state;
+  let vault;
+  try {
+    ({ state, vault } = await load(root));
+  } catch (error) {
+    say('error', { root, message: String(error.message ?? error), name: error.name ?? 'Error' });
+    process.exit(1);
+  }
+  const profile = state.profiles[parsed.profile];
+  if (!profile) {
+    say('error', { root, message: `unknown profile \`${parsed.profile}\` (have: ${Object.keys(state.profiles).join(', ')})` });
+    process.exit(1);
+  }
+  if (verb === 'pair-list') {
+    say('access', accessReport(root, parsed.profile, profile, { verb }));
+    return;
+  }
+  const make = ACCESS_OPS[verb];
+  if (!make) {
+    say('error', { root, message: `unknown access verb \`${verb ?? ''}\` (have: pair-list, ${Object.keys(ACCESS_OPS).join(', ')})` });
+    process.exit(2);
+  }
+  const [op, args] = make(profile, rest);
+  if ((op === 'approve' && !args.code) || (op !== 'approve' && (!args.platform || !args.user_id))) {
+    say('error', { root, profile: parsed.profile, verb, message: op === 'approve' ? 'pair-approve takes a code' : `${verb} takes a platform and a user id` });
+    process.exit(2);
+  }
+  let got;
+  try {
+    got = hermesAccess(profile.dir, op, args);
+  } catch (error) {
+    say('error', { root, profile: parsed.profile, verb, message: error.message });
+    process.exit(1);
+  }
+  if (op === 'approve' && !got) {
+    say('error', { root, profile: parsed.profile, verb, message: `pairing code ${args.code} is not pending in Hermes's pairing store (wrong, expired, or locked out)` });
+    process.exit(1);
+  }
+  const fresh = (await load(root)).state.profiles[parsed.profile];
+  say('access', accessReport(root, parsed.profile, fresh, { verb, changed: true, ...(op === 'approve' ? { approved: got } : {}) }));
+}
+
+/**
+ * The agent-setup applier (plan §7), one home per call:
+ *
+ *   apply plan|apply|adopt|resolve|provision --home-id <id> (--hermes <home> | --orchestrator <root> [--profile <p>])
+ *         [--spec <file.json>] [--param name=value ...] [--plan-hash <h>] [--reviewed] [--keys a,b]
+ *         [--python <py> --source <dir>] [--container <name>]   (--container: HERMES_HOME is the container's path)
+ *
+ * Prints one {ok, result} line. `plan` never changes anything; `apply` refuses a
+ * stale --plan-hash; `delete` runs only with --reviewed; a home with no apply
+ * state is plan-only until `provision` or `adopt`.
+ */
+async function runApply(argv) {
+  const [verb, ...rest] = argv;
+  const opts = {};
+  const params = {};
+  for (let i = 0; i < rest.length; i += 1) {
+    const flag = rest[i];
+    if (flag === '--reviewed') { opts.reviewed = true; continue; }
+    if (flag === '--param') {
+      const pair = String(rest[i + 1] ?? '');
+      const eq = pair.indexOf('=');
+      if (eq < 1) throw new Error(`apply: --param takes name=value, got ${JSON.stringify(pair)}`);
+      params[pair.slice(0, eq)] = pair.slice(eq + 1);
+      i += 1;
+      continue;
+    }
+    if (!flag.startsWith('--') || rest[i + 1] === undefined) throw new Error(`apply: unexpected argument ${JSON.stringify(flag)}`);
+    opts[flag.slice(2)] = rest[i + 1];
+    i += 1;
+  }
+  const applier = await import('../apply/index.mjs');
+  const doors = await import('../apply/doors.mjs');
+  if (!opts['home-id']) throw new Error('apply: --home-id is required (the runtime names each home)');
+  if (verb === 'provision') {
+    const state = applier.provision({ homeId: opts['home-id'] });
+    process.stdout.write(`${JSON.stringify({ ok: true, result: { provisioned: opts['home-id'], generation: state.generation } })}\n`);
+    return 0;
+  }
+  let door;
+  if (opts.hermes && opts.container) door = doors.hermesDoor({ home: opts.hermes, runner: doors.containerRunner({ container: opts.container }) });
+  else if (opts.hermes) door = doors.hermesDoor({ home: resolve(opts.hermes), ...doors.locateHermes({ python: opts.python ?? null, source: opts.source ?? null }) });
+  else if (opts.orchestrator) door = await doors.orchestratorDoor({ root: resolve(opts.orchestrator), profile: opts.profile ?? 'default', load });
+  else throw new Error('apply: name the home with --hermes <HERMES_HOME> or --orchestrator <root>');
+  const spec = opts.spec ? JSON.parse(readFileSync(resolve(opts.spec), 'utf8')) : null;
+  let result;
+  if (verb === 'plan') result = await applier.plan({ door, homeId: opts['home-id'], spec, params });
+  else if (verb === 'apply') result = await applier.apply({ door, homeId: opts['home-id'], spec, params, planHash: opts['plan-hash'] ?? null, reviewedPlan: Boolean(opts.reviewed) });
+  else if (verb === 'adopt') result = await applier.adopt({ door, homeId: opts['home-id'], keys: String(opts.keys ?? '').split(',').filter(Boolean) });
+  else if (verb === 'resolve') result = await applier.resolve({ door, homeId: opts['home-id'], keys: String(opts.keys ?? '').split(',').filter(Boolean) });
+  else throw new Error(`apply: ${JSON.stringify(verb)} is not plan | apply | adopt | resolve | provision`);
+  process.stdout.write(`${JSON.stringify({ ok: true, result })}\n`);
+  return 0;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (OPERATOR_OPS.includes(argv[0])) {
+    try {
+      const code = await runOperator(argv[0], argv.slice(1));
+      await closeWorld();
+      process.exit(code);
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: String(error.message ?? error) })}\n`);
+      process.exit(1);
+    }
+  }
+  if (argv[0] === 'import' || argv[0] === 'export') {
+    try {
+      const code = await (argv[0] === 'import' ? runImport(argv.slice(1)) : runExport(argv.slice(1)));
+      await closeWorld();
+      process.exit(code);
+    } catch (error) {
+      say('error', { verb: argv[0], message: String(error.message ?? error), name: error.name ?? 'Error' });
+      await closeWorld();
+      process.exit(1);
+    }
+  }
+  if (argv[0] === 'access') {
+    await accessMain(argv.slice(1));
+    return;
+  }
+  if (argv[0] === 'apply') {
+    try {
+      const code = await runApply(argv.slice(1));
+      await closeWorld();
+      process.exit(code);
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: String(error.message ?? error) })}\n`);
+      await closeWorld();
+      process.exit(1);
+    }
+  }
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (error) {
+    say('error', { message: error.message });
+    process.exit(2);
+  }
+  if (args.version) {
+    say('version', { version: packageVersion() });
+    return;
+  }
+  // The daemon runs as `hermes-gateway`: its home is a Hermes home, and Hermes calls a lock holder live only
+  // when its command line is a gateway's (hermes-locks.mjs). A launcher that did not name it so is re-run as it.
+  if (!args.once && basename(process.argv0) !== GATEWAY_KIND) {
+    const child = spawn(process.execPath, process.argv.slice(1), { argv0: GATEWAY_KIND, stdio: 'inherit', env: process.env });
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => child.kill(signal));
+    child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+    return;
+  }
+  const root = resolve(args.root ?? defaultRoot());
+  let crashed = false;
+  let gatewayLock = null;
+  if (!args.once) {
+    // Serialize lease replacement before loading state. An acquisition guard
+    // left by a crash fails closed; inspect it before removing it manually.
+    const guard = join(root, 'orchestrator.acquire');
+    mkdirSync(guard);
+    try {
+      const previous = readLock(root);
+      if (previous && leaseIsLive(previous)) {
+        say('error', { root, message: `already serving ${root} (pid ${previous.pid})` });
+        throw new Error(`already serving ${root}`);
+      }
+      crashed = Boolean(previous);
+      if (previous) unlinkSync(join(root, LOCK_FILE));
+      writeLock(root, { pid: process.pid, started_at: new Date().toISOString(), root, ...thisHost(), executor_url: args.executorUrl ?? null });
+    } finally {
+      rmdirSync(guard);
+    }
+    // One runtime per home: Hermes's own gateway lock, held for as long as this daemon lives, so a Hermes
+    // gateway on this home refuses to start, and this daemon refuses a home a Hermes gateway serves.
+    try {
+      gatewayLock = await holdGatewayLock(root);
+      // the home in both forms before it is loaded: a Hermes home is adopted as it stands
+      for (const change of adoptHome(root)) say('log', { level: 'info', message: `home: ${change}` });
+    } catch (error) {
+      say('error', { root, message: error.message });
+      gatewayLock?.release();
+      clearLock(root);
+      process.exit(1);
+    }
+  }
+  let state;
+  let vault;
+  try {
+    ({ state, vault } = await load(root));
+  } catch (error) {
+    // A home that does not load is a refused start, never a partial one.
+    say('error', { root, message: String(error.message ?? error), name: error.name ?? 'Error' });
+    process.exit(1);
+  }
+  // Under Hermes each named profile is a home of its own (`<root>/profiles/<name>`) with its own gateway; this daemon
+  // serves them all, so it holds each profile's gateway lock too: `hermes -p <name> cron status` reads the profile's
+  // scheduler as running, and a Hermes gateway started on the profile refuses, as it does on the root.
+  const profileLocks = [];
+  if (gatewayLock) {
+    for (const profile of Object.values(state.profiles)) {
+      if (!profile?.dir || resolve(profile.dir) === root) continue;
+      try {
+        profileLocks.push(await holdGatewayLock(profile.dir));
+      } catch (error) {
+        say('error', { root, message: error.message });
+        for (const lock of profileLocks) lock.release();
+        gatewayLock.release();
+        clearLock(root);
+        process.exit(1);
+      }
+    }
+  }
+
+  const { adapters, report } = buildAdapters(state, vault, (level, message) => say('log', { level, message }));
+  // `SUPERCODE_BIN` is set by `supercode orchestrator start` to the very
+  // binary that spawned this daemon, so the worker doors it opens are that
+  // build's, not whatever `supercode` a PATH lookup happens to find.
+  const client = new SupercodeHarnessClient(process.env.SUPERCODE_BIN ? { command: process.env.SUPERCODE_BIN } : {});
+  const orchestrator = new Orchestrator({
+    executeJob: args.executorUrl ? httpJobExecutor({ url: args.executorUrl, tokenFile: args.executorTokenFile, root }) : null,
+    state,
+    vault,
+    client,
+    adapters,
+    log: (level, message) => say('log', { level, message }),
+  });
+
+  say('loaded', {
+    root,
+    pid: process.pid,
+    version: packageVersion(),
+    started_at: new Date().toISOString(),
+    profiles: Object.entries(state.profiles).map(([name, profile]) => profileReport(name, profile)),
+    adapters: report,
+  });
+
+  if (args.once) {
+    // `--once` proves the home loads and the loop builds without connecting
+    // anything: the check `setup` and a service unit's dry run want.
+    say('ready', { root, pid: process.pid, connected: [], once: true });
+    return;
+  }
+
+
+  await orchestrator.start();
+  // A daemon that came BACK replays pending obligations, re-attaches or
+  // interrupts the bindings that held a lease, and clears the stale ones
+  // before it accepts anything new (§4.7). A clean stop removes its own lock,
+  // so an ordinary start finds none and replays nothing.
+  if (crashed) await orchestrator.dispatch(events.restart(new Date().toISOString()));
+  say('ready', {
+    root,
+    pid: process.pid,
+    // an adapter that refused to come up is `down`, never counted as connected
+    connected: Object.entries(state.runtime.adapters ?? {}).filter(([, a]) => a.state === 'up').map(([p]) => p),
+    down: Object.entries(state.runtime.adapters ?? {}).filter(([, a]) => a.state !== 'up').map(([p]) => p),
+    webhook_port: orchestrator.webhookPort,
+    tick_ms: TICK_MS,
+    restarted: crashed,
+  });
+
+  // The loop's own tick timer is `unref`'d, and the webhook listener may bind
+  // nothing a profile uses; this timer is what keeps the daemon alive on
+  // purpose, so "up" always means a process that will still be here next tick.
+  const keepalive = setInterval(() => {}, TICK_MS);
+
+  let stopping = false;
+  const stop = async (signal) => {
+    if (stopping) return;
+    stopping = true;
+    clearInterval(keepalive);
+    say('stopping', { root, pid: process.pid, signal });
+    try {
+      await orchestrator.stop();
+      await client.close?.();
+      await closeWorld();
+    } catch (error) {
+      say('log', { level: 'error', message: `stop: ${String(error.message ?? error)}` });
+    }
+    for (const lock of profileLocks) lock.release();
+    gatewayLock?.release();
+    clearLock(root);
+    say('stopped', { root, pid: process.pid });
+    process.exit(0);
+  };
+  process.on('SIGTERM', () => void stop('SIGTERM'));
+  process.on('SIGINT', () => void stop('SIGINT'));
+}
+
+await main();