@volter/supercode-orchestrator 0.4.4

package/loop.mjs

@@ -0,0 +1,864 @@
+// The orchestrator loop: events in, `step` in the middle, effects out over the
+// SDK and the adapters (docs/ORCHESTRATOR-IR.md §4–§5, §7).
+//
+// This is the only module that performs I/O for the loop. It holds the single
+// state value, the vault, the SDK client, the adapters, and an injected clock.
+
+import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { basename, join, dirname } from 'node:path';
+import { step, leaseId } from './reducer.mjs';
+import * as events from './events.mjs';
+import { save, retainWorld, releaseWorld } from './orchestration.mjs';
+import { INSTRUCTION_ARGUMENTS, NAME_ARGUMENTS, activationEnv, activationCwd, approvalPolicy, sandboxArguments, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter } from './activation.mjs';
+import { workerRoute } from './worker-route.mjs';
+import { hermesAccess, hermesApproval, untrustedServerVerdict, hermesToolEnv, memorySnapshot, mirrorSession, mirrorState, recordIncident, sealMirror } from './hermes-cli.mjs';
+import { hermesSessionKey } from './ir.mjs';
+import { surfaceKeyString } from './ir.mjs';
+import { BREAKER_FAILURES, BREAKER_MINUTES, MAX_ATTEMPTS, historyRetention, jobGate } from './cron.mjs';
+import { startWebhookListener } from './webhook.mjs';
+import { startBridge } from './mcp/bridge.mjs';
+import { socketPathFor } from './mcp/server.mjs';
+import { mountOrchestratorMcp } from './mcp/mount.mjs';
+import { performRemoveProfileDir } from './operator.mjs';
+import { harnessHomes } from './mcp/verbs.mjs';
+import { checkMonitor, runJobScript } from './gates.mjs';
+import { startBoard } from './board.mjs';
+
+/**
+ * Where a worker keeps its transcripts inside its config home (`<profile>/<harness>`), as discovery and
+ * materialization take them (`HarnessHomes`): the worker sessions the Hermes mirror reads and writes.
+ */
+export const WORKER_STORE = Object.freeze({
+  codex: (home) => ({ codex: join(home, 'sessions') }),
+  'claude-code': (home) => ({ claude_code: join(home, 'projects') }),
+});
+
+/** The tick the loop drives itself on when no clock was injected (§4.3: "every 60 s"). */
+export const TICK_MS = 60_000;
+const ADAPTER_RETRY_MS = 30_000;
+
+export class Orchestrator {
+  /**
+   * @param {object} o
+   * @param {import('./index.d.ts').OrchestratorState} o.state
+   * @param {Map<string,string>} o.vault
+   * @param {import('@volter/supercode-harness-sdk').SupercodeHarnessClient} o.client
+   * @param {Record<string, object>} o.adapters  platform -> adapter
+   * @param {() => string} [o.clock]             RFC 3339 now; injected for tests (which then drive `tick` themselves)
+   * @param {(profile, worker, env) => object|undefined} [o.launchFor]  launch override per worker (tests)
+   * @param {(level, message) => void} [o.log]
+   */
+  constructor({ state, vault = new Map(), client, adapters = {}, clock = null, launchFor = null, executeJob = null, log = () => {} }) {
+    this.state = state;
+    this.executeJob = executeJob;
+    this.hostedTasks = new Set();
+    state.runtime ??= {};
+    state.runtime.hostedJobs = !!executeJob;
+    state.runtime.hostedFires = {};
+    this.vault = vault;
+    this.client = client;
+    this.adapters = adapters;
+    this.clock = clock ?? (() => new Date().toISOString());
+    // an injected clock owns the tick: the test dispatches `events.tick` itself
+    this.autoTick = !clock;
+    this.timer = null;
+    this.webhooks = null;
+    this.bridge = null; // §7: the model-facing MCP door's loop side
+    this.launchFor = launchFor;
+    this.retired = new Map(); // runtimes a newer start displaced, by id, until their close names them
+    this.log = log;
+    this.runtimes = new Map(); // leaseId -> ManagedRuntime
+    this.queue = Promise.resolve();
+    this.effectLog = [];
+    this.support = null; // memoized `supportReport()`: the registry does not move under a run
+  }
+
+  async start() {
+    retainWorld();
+    for (const [platform, adapter] of Object.entries(this.adapters)) await this.connectAdapter(platform, adapter);
+    this.webhooks = await startWebhookListener({
+      state: this.state, vault: this.vault, port: webhookPort(this.state),
+      dispatch: (event) => this.dispatchLogged(event), clock: () => this.clock(), log: this.log,
+    });
+    this.bridge = await startBridge({ orch: this, socketPath: socketPathFor(this.state.root), log: this.log });
+    // the queue already logs a failed event; a voided dispatch must not also
+    // reject unhandled, which Node treats as fatal and which stopped the daemon
+    if (this.autoTick) { this.timer = setInterval(() => { this.tick().catch(() => undefined); }, TICK_MS); this.timer.unref?.(); }
+    // the home's board, dispatched as a Hermes gateway dispatches it (docs/plans/hermes-compat.md row 14)
+    if (this.autoTick) this.board = await startBoard({ root: this.state.root, config: this.state.profiles.default?.residue?.config ?? {}, log: this.log });
+  }
+
+  /**
+   * One adapter's connect. A platform that cannot connect (its service down, a refused token) is that
+   * adapter's state, not the daemon's: it is reported `down` with the cause, the other adapters and the
+   * daemon's own doors keep serving, and the connect is tried again until it holds or the daemon stops.
+   */
+  async connectAdapter(platform, adapter) {
+    let status;
+    try {
+      status = await adapter.connect((msg) => this.dispatchLogged(events.inbound({ ...msg, at: msg.at ?? this.clock() })));
+      if (status?.state === 'down' && status.configured === false) {
+        // not set up (a missing package or credential): no retry can fix it
+        this.log('error', `${platform}: not configured, not retried: ${status.error}`);
+        await this.dispatchLogged(events.adapterStatus({ platform, state: 'down', error: status.error, configured: false, at: this.clock() }));
+        return;
+      }
+    } catch (error) {
+      this.log('error', `${platform}: connect failed, retrying in ${ADAPTER_RETRY_MS / 1000}s: ${error instanceof Error ? error.message : String(error)}`);
+      await this.dispatchLogged(events.adapterStatus({ platform, state: 'down', error: error instanceof Error ? error.message : String(error), at: this.clock() }));
+      this.adapterRetries ??= new Map();
+      const timer = setTimeout(() => { this.adapterRetries?.delete(platform); void this.connectAdapter(platform, adapter); }, ADAPTER_RETRY_MS);
+      timer.unref?.();
+      this.adapterRetries.set(platform, timer);
+      return;
+    }
+    // connected: recording that is the queue's (a failed save is logged there),
+    // never a reason to connect the same adapter again
+    await this.dispatchLogged(events.adapterStatus({ platform, state: status?.state ?? 'up', at: this.clock() }));
+  }
+
+  /** The port the webhook listener bound (0 in config means "any free port"). */
+  get webhookPort() {
+    return this.webhooks?.port ?? null;
+  }
+
+  /** One clock tick: expiry, due cron jobs, obligation retry, breaker windows (§4.3). */
+  tick(at = this.clock()) {
+    return this.dispatch(events.tick(at, cronInactivitySeconds(), cronMaxParallel())).then(
+      (result) => { this.tickerHeartbeat(true); return result; },
+      (error) => { this.tickerHeartbeat(false); throw error; },
+    );
+  }
+
+  /**
+   * Hermes's ticker liveness (`cron/jobs.py` `record_ticker_heartbeat`), in each profile's cron store: the
+   * epoch of every tick in `ticker_heartbeat`, and of every tick that did not fail in `ticker_last_success`.
+   * `hermes cron status` reads both, so a scheduler alive but failing every tick is told from one firing jobs.
+   * Written whole and renamed into place, as Hermes writes them; a failed write never stops the tick.
+   */
+  tickerHeartbeat(success) {
+    const epoch = String(Date.now() / 1000);
+    for (const profile of Object.values(this.state.profiles ?? {})) {
+      if (!profile?.dir) continue;
+      for (const name of success ? ['ticker_heartbeat', 'ticker_last_success'] : ['ticker_heartbeat']) {
+        try {
+          const dir = join(profile.dir, 'cron');
+          mkdirSync(dir, { recursive: true });
+          const tmp = join(dir, `.hb_${process.pid}_${name}`);
+          writeFileSync(tmp, epoch);
+          renameSync(tmp, join(dir, name));
+        } catch (error) {
+          this.log('warn', `profile ${profile.name}: ${name} not written: ${error.message}`);
+        }
+      }
+    }
+  }
+
+  async stop() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+    this.board?.stop(); this.board = null;
+    // Before any runtime closes: each binding records the runtime to resume (§4.7), while adapters can still deliver.
+    await this.dispatch(events.stopping(this.clock())).catch((error) => this.log('error', `stopping: ${error.message}`));
+    for (const timer of this.adapterRetries?.values() ?? []) clearTimeout(timer);
+    this.adapterRetries?.clear();
+    if (this.webhooks) { await this.webhooks.close(); this.webhooks = null; }
+    if (this.bridge) { await this.bridge.close(); this.bridge = null; }
+    this.gateAbort?.abort();
+    await this.drainHosted();
+    for (const rt of this.runtimes.values()) { try { await rt.close(); } catch { /* already gone */ } }
+    this.runtimes.clear();
+    for (const adapter of Object.values(this.adapters)) await adapter.close?.();
+    releaseWorld();
+  }
+
+  /** Events are applied one at a time, in arrival order; effects run before the next event. */
+  dispatch(event) {
+    const run = this.queue.then(() => this.apply(event));
+    this.queue = run.catch((error) => this.log('error', `dispatch: ${error.message}`));
+    return run;
+  }
+
+  /**
+   * Queue a follow-up event from inside an effect handler WITHOUT awaiting it.
+   * An effect runs on the queue; awaiting `dispatch` there would wait on the
+   * event currently being applied, i.e. on itself.
+   */
+  enqueue(event) {
+    void this.dispatchLogged(event);
+  }
+
+  /**
+   * `dispatch` for a caller that drops the promise (a timer, an adapter's
+   * inbound callback, the webhook listener). The queue already logged the
+   * failure; an unhandled rejection is fatal to Node and stopped the daemon.
+   */
+  dispatchLogged(event) {
+    return this.dispatch(event).catch(() => undefined);
+  }
+
+  async apply(event) {
+    const effects = step(this.state, event);
+    for (const effect of effects) {
+      this.effectLog.push(effect);
+      await this.perform(effect);
+    }
+    return effects;
+  }
+
+  async perform(effect) {
+    switch (effect.type) {
+      case 'execute_job': return this.executeHostedJob(effect);
+      case 'run_gate': return this.runGate(effect);
+      case 'runtime_start': return this.startRuntime(effect);
+      case 'runtime_reattach': return this.reattachRuntime(effect);
+      case 'send_input': return this.sendInput(effect);
+      case 'steer_input': return this.steerInput(effect);
+      case 'respond': return this.respond(effect);
+      case 'runtime_close': return this.closeRuntime(effect);
+      case 'deliver': return this.deliver(effect);
+      case 'write_local': return this.writeLocal(effect);
+      // ORC-13 §4.6: `profiles.delete` moves the folder aside; it never
+      // unlinks one. `performRemoveProfileDir` is shared with the cold path.
+      case 'remove_profile_dir': {
+        const moved = performRemoveProfileDir(this.state.root, effect, this.clock());
+        this.log('info', moved ? `profile ${effect.profile}: folder moved to ${moved}` : `profile ${effect.profile}: no folder to move`);
+        return;
+      }
+      case 'record_incident': {
+        const dir = this.state.profiles[effect.profile]?.dir;
+        const got = dir ? recordIncident(dir, effect) : { id: null, why: 'no such profile' };
+        if (!got.id) this.log('warn', `incident for ${effect.job_id} not recorded: ${got.why}`);
+        return;
+      }
+      case 'pairing_issue': {
+        let got;
+        try { got = hermesAccess(this.state.profiles[effect.profile].dir, 'issue', effect); } catch (error) { this.log('warn', `pairing: ${error.message}`); return; }
+        if (got?.silent) return;
+        await this.dispatch({ type: 'pairing_issued', profile: effect.profile, key: effect.key, code: got?.code ?? null, at: this.clock() });
+        return;
+      }
+      case 'access_write': {
+        const dir = this.state.profiles[effect.profile]?.dir;
+        try {
+          const got = hermesAccess(dir, effect.op, effect);
+          if (effect.op === 'approve') {
+            if (got) await this.dispatch({ type: 'operator', verb: 'access_granted', profile: effect.profile, args: { platform: got.platform, user_id: got.user_id }, at: this.clock() });
+            else this.log('warn', `pairing code ${effect.code}: not pending in Hermes's pairing store (wrong, expired, or locked out)`);
+          }
+        } catch (error) {
+          this.log('warn', `access ${effect.op}: ${error.message}`);
+        }
+        return;
+      }
+      case 'save': await save(this.state, this.state.root); return;
+      case 'log': this.log(effect.level, effect.message); return;
+      default: this.log('warn', `unknown effect ${effect.type}`);
+    }
+  }
+
+  executeHostedJob({ profile: name, job_id, fire_id }) {
+    const profile = this.state.profiles[name];
+    const job = structuredClone(profile.jobs[job_id]);
+    const fire = structuredClone(profile.fires.find((f) => f.id === fire_id));
+    // Host work never blocks the state queue; completion returns as an event.
+    const task = Promise.resolve().then(() => this.executeJob({ profile: name, job, fire }))
+      .then((receipt) => {
+        if (!receipt || typeof receipt.output !== 'string' || receipt.accepted !== true)
+          throw new Error('The host did not confirm this scheduled task');
+        return this.dispatch({ type: 'hosted_result', profile: name, fire_id, receipt, at: this.clock() });
+      }).catch((error) => this.dispatch({ type: 'hosted_result', profile: name, fire_id, error: error.message, at: this.clock() }))
+      .catch((error) => this.log('error', `Hosted completion could not be saved: ${error.message}`))
+      .finally(() => this.hostedTasks.delete(task));
+    this.hostedTasks.add(task);
+  }
+
+  /**
+   * A fire's gate, off the queue (a script may run for Hermes's hour): the
+   * monitor source first, then the pre-run script unless the monitor already
+   * decided the run (Hermes's order in `run_job`). The answer returns as
+   * `gate_result`.
+   */
+  runGate({ profile: name, job_id, fire_id }) {
+    const profile = this.state.profiles[name];
+    const job = profile?.jobs[job_id] ? structuredClone(profile.jobs[job_id]) : null;
+    const gate = jobGate(job);
+    // stop() aborts a running gate's script rather than wait out its hour
+    if (!this.gateAbort || this.gateAbort.signal.aborted) this.gateAbort = new AbortController();
+    const signal = this.gateAbort.signal;
+    const secrets = [...this.vault.values()];
+    const task = (async () => {
+      if (!gate) return { script: { ok: false, output: 'the job no longer has a gate' } };
+      const workdir = job.workdir ? activationCwd(profile, job.workdir) : null;
+      let monitor = null;
+      if (gate.monitor_script || gate.monitor_url) {
+        monitor = await checkMonitor(profile, job, gate, { workdir, signal, secrets });
+        if (!monitor.ok || !monitor.changed) return { monitor };
+      }
+      // Hermes runs a no_agent script in the job's workdir, and an agent job's
+      // pre-run script from the scripts folder
+      const script = gate.script ? await runJobScript(profile, gate.script, gate.no_agent ? workdir : null, { signal, secrets }) : null;
+      return { monitor, script };
+    })()
+      .catch((error) => ({ script: { ok: false, output: `Script execution failed: ${error.message}` } }))
+      .then((answer) => (signal.aborted ? undefined : this.dispatchLogged(events.gateResult({ profile: name, fire_id, at: this.clock(), ...answer }))))
+      .finally(() => this.hostedTasks.delete(task));
+    this.hostedTasks.add(task);
+  }
+
+  /** Wait for admitted host tasks; useful for deterministic tests and graceful shutdown. */
+  async drainHosted() { await Promise.allSettled([...this.hostedTasks]); }
+
+  async startRuntime({ profile: profileName, keyString, worker, resume_runtime_id = null }) {
+    const profile = this.state.profiles[profileName];
+    const lid = leaseId(profileName, keyString);
+    const cwd = activationCwd(profile, worker.cwd);
+    materializePersona(profile);
+    materializeSkills(profile);
+    let launch;
+    try {
+      // the home's own `model:` is the worker's model and route (docs/plans/hermes-compat.md row 6)
+      const route = workerRoute(profile, worker, this.vault);
+      // a worker of any harness but Hermes gets Hermes's CLI against its profile's home (row 7)
+      const tools = worker.harness === 'hermes' ? {} : hermesToolEnv(profile.dir);
+      const env = { ...tools, ...activationEnv({ root: this.state.root, profile, surfaceKey: keyString, vault: this.vault }), ...route.env };
+      // the home's memory, as Hermes's agent carries it into a session (row 13)
+      const memory = INSTRUCTION_ARGUMENTS[worker.harness] ? await memorySnapshot(profile.dir).catch((error) => { this.log('warn', `memory ${keyString}: ${error.message}`); return ''; }) : '';
+      const instructions = memory ? INSTRUCTION_ARGUMENTS[worker.harness](memory) : [];
+      const naming = NAME_ARGUMENTS[worker.harness]?.(basename(this.state.root)) ?? [];
+      launch = await this.resolveLaunch(profile, { ...worker, model: route.model }, env, [...route.args, ...instructions, ...naming]);
+    } catch (error) {
+      this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: null, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
+      return;
+    }
+    // §7: the model-facing door. One MCP server per worker session, bound to
+    // this conversation, mounted through whatever door this harness publishes.
+    const mount = mountOrchestratorMcp({
+      root: this.state.root, profile, harness: worker.harness, surfaceKey: keyString, launch,
+      socketPath: this.bridge?.path ?? socketPathFor(this.state.root), vault: this.vault,
+    });
+    this.log('info', `mcp mount (${worker.harness}, ${mount.door}): ${mount.ran}`);
+    if (resume_runtime_id) resume_runtime_id = await this.continueFromHermes(profile, keyString, worker, resume_runtime_id, cwd);
+    // read before the runtime exists: a runtime emits from the moment it is made
+    const steer = Boolean((await this.descriptorFor(worker.harness).catch(() => null))?.runtime?.capabilities?.steer);
+    let runtime;
+    try {
+      const policy = approvalPolicy(profile, worker.harness);
+      const params = { harness: worker.harness, cwd, launch: mount.launch, ...(mount.mcp_servers ? { mcp_servers: mount.mcp_servers } : {}), ...(policy ? { approval_policy: policy } : {}) };
+      if (resume_runtime_id && (await this.descriptorFor(worker.harness).catch(() => null))?.runtime?.capabilities?.resume_session) {
+        try {
+          runtime = await this.client.resumeManagedRuntime({ ...params, runtime_id: resume_runtime_id });
+          this.log('info', `resume ${keyString}: reopened ${resume_runtime_id}`);
+        } catch (error) {
+          this.log('warn', `resume ${keyString}: ${resume_runtime_id} did not reopen (${error.message}); starting fresh`);
+        }
+      }
+      runtime ??= await this.client.startManagedRuntime(params);
+    } catch (error) {
+      this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: null, ev: { kind: 'error', message: `start failed: ${error.message}` }, at: this.clock() }));
+      return;
+    }
+    // `started` is queued before the runtime can be heard (steer was read
+    // before the start), so none of its events arrives ahead of its lease
+    const previous = this.runtimes.get(lid);
+    if (previous && previous !== runtime) this.retired.set(previous.handle.runtime_id, previous);
+    this.runtimes.set(lid, runtime);
+    this.enqueue(events.worker({
+      profile: profileName, keyString, runtime_id: runtime.handle.runtime_id,
+      ev: { kind: 'started', runtime_id: runtime.handle.runtime_id, session_id: runtime.handle.runtime_id, connection: runtime.connection, harness: worker.harness, steer },
+      at: this.clock(),
+    }));
+    this.watch(profileName, keyString, runtime);
+  }
+
+  /**
+   * §4.7's first half, one binding at a time: the daemon came back and this
+   * surface held a lease when it went away. Where the worker's own door can
+   * adopt a process that is still running (`attach_existing_process`) the
+   * conversation is taken over as it stands; where it cannot — every harness
+   * whose runtime dies with its parent — the binding's last turn is marked
+   * interrupted and the surface is told once (`binding_interrupted`).
+   */
+  async reattachRuntime({ profile: profileName, keyString, runtime_id, harness }) {
+    const interrupted = (why) => {
+      this.log('info', `reattach ${keyString}: ${why}`);
+      this.enqueue(events.operator({ verb: 'binding_interrupted', profile: profileName, args: { keyString, runtime_id }, at: this.clock() }));
+    };
+    if (!runtime_id || !harness) return interrupted('no runtime recorded on the binding');
+    let capable = false;
+    try {
+      capable = Boolean((await this.descriptorFor(harness))?.runtime?.capabilities?.attach_existing_process);
+    } catch (error) {
+      return interrupted(`capabilities unavailable: ${error.message}`);
+    }
+    if (!capable) return interrupted(`${harness} cannot attach to an existing process`);
+    let runtime;
+    try {
+      runtime = await this.client.attachManagedRuntime({ harness, runtime_id });
+    } catch (error) {
+      return interrupted(`attach_existing failed: ${error.message}`);
+    }
+    this.runtimes.set(leaseId(profileName, keyString), runtime);
+    this.watch(profileName, keyString, runtime);
+    const held = this.state.profiles[profileName]?.bindings?.[keyString];
+    this.enqueue(events.worker({
+      profile: profileName, keyString, runtime_id: runtime.handle.runtime_id,
+      ev: { kind: 'started', runtime_id: runtime.handle.runtime_id, session_id: held?.worker?.session_id || runtime.handle.runtime_id, connection: runtime.connection, harness, reattach_of: runtime_id },
+      at: this.clock(),
+    }));
+    this.log('info', `reattach ${keyString}: attached to ${runtime.handle.runtime_id}`);
+  }
+
+  /** Every runtime the loop holds reports through the same three channels. */
+  watch(profileName, keyString, runtime) {
+    runtime.on('event', (ev) => this.onWorkerEvent(profileName, keyString, runtime, ev));
+    runtime.on('closed', (ev) => this.onWorkerEvent(profileName, keyString, runtime, ev));
+    runtime.on('runtimeError', (ev) => this.onWorkerEvent(profileName, keyString, runtime, ev));
+  }
+
+  /** The registry's row for one harness; the report is fetched at most once. */
+  async descriptorFor(harness) {
+    if (!this.support) {
+      this.support = this.client.supportReport().catch((error) => { this.support = null; throw error; });
+    }
+    const report = await this.support;
+    return report.harnesses.find((h) => h.id === harness) ?? null;
+  }
+
+  /** The registry's default launch with the activation env merged in, unless a test overrides it. */
+  async resolveLaunch(profile, worker, env, routeArgs = []) {
+    if (this.launchFor) {
+      const override = this.launchFor(profile, worker, env);
+      if (override) return { ...override, arguments: [...(override.arguments ?? []), ...modelArguments(worker), ...routeArgs, ...sandboxArguments(profile, worker.harness), ...limitArguments(profile, worker, this.log)] };
+    }
+    const base = (await this.descriptorFor(worker.harness))?.runtime?.default_launch;
+    if (!base) {
+      // the backend's own launch takes no env and no flags: a model set here could not reach it
+      if (worker.model) throw new Error(`${worker.harness} publishes no launch to carry model ${worker.model}`);
+      return undefined;
+    }
+    return { program: base.program, arguments: [...(base.arguments ?? []), ...modelArguments(worker), ...routeArgs, ...sandboxArguments(profile, worker.harness), ...limitArguments(profile, worker, this.log)], env: { ...(base.env ?? {}), ...env } };
+  }
+
+  /**
+   * Hermes's `agent.max_turns` for a worker that takes no turn cap at launch (Claude Code takes `--max-turns`,
+   * activation.mjs `TURN_ARGUMENTS`): the orchestrator counts the turn's model round trips, Hermes's own unit,
+   * by the event the worker reports for each (activation.mjs `ROUND_TRIP_EVENTS`), and interrupts the turn past
+   * the cap. A turn that runs away (a denial it retries, a loop) ends here instead of on the spend limit, and
+   * fails: its final names the cap (activation.mjs `turnCounter`).
+   */
+  holdTurnLimit(profileName, keyString, runtime, ev) {
+    const id = runtime.handle?.runtime_id ?? keyString;
+    this.turnCounters ??= new Map();
+    // a turn's start reads the profile's cap afresh; a worker that reports no start is counted from its first call
+    if (ev.type === 'turn_started' || !this.turnCounters.has(id)) {
+      const profile = this.state.profiles[profileName];
+      this.turnCounters.set(id, turnCounter(profile, profile?.bindings?.[keyString]?.worker?.harness ?? profile?.worker?.harness));
+      if (ev.type === 'turn_started') return;
+    }
+    const counter = this.turnCounters.get(id);
+    if (!counter?.count(ev)) return;
+    this.log('warn', `${keyString}: ${counter.cap + 1} model calls in one turn passes agent.max_turns ${counter.cap}; the turn is interrupted`);
+    void Promise.resolve(runtime.interrupt?.()).catch((error) => this.log('warn', `${keyString}: interrupt failed: ${error.message}`));
+  }
+
+  onWorkerEvent(profileName, keyString, runtime, ev) {
+    const at = this.clock();
+    // every event the runtime reports is the worker being alive, including the
+    // tool calls, reasoning and turn starts the reducer does not otherwise read
+    let w = normalizeWorkerEvent(ev) ?? { kind: 'activity' };
+    this.holdTurnLimit(profileName, keyString, runtime, ev);
+    if (w.kind === 'final') w = this.turnCounters?.get(runtime.handle?.runtime_id ?? keyString)?.settle(w) ?? w;
+    if (w.kind === 'ended' || w.kind === 'error') this.turnCounters?.delete(runtime.handle?.runtime_id ?? keyString);
+    if (w.kind === 'request') {
+      // Hermes's approval rule decides first (hermes-cli.mjs `hermesApproval`); the reducer applies its verdict
+      const profile = this.state.profiles[profileName];
+      const b = profile?.bindings?.[keyString];
+      const context = b?.recurrence || b?.residue?.webhook ? 'cron' : 'conversation';
+      // a tool of one of the profile's untrusted MCP servers is gated as Hermes's trust gate gates it
+      const gated = untrustedServerVerdict(profile, w.tool, context, { mcp: w.mcp && !String(w.tool ?? '').startsWith('mcp__orchestrator__') });
+      if (gated) { this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: runtime.handle.runtime_id, ev: { ...w, hermes: gated }, at })); return; }
+      void hermesApproval(profile.dir, { command: w.command ?? null, context })
+        .catch((error) => { this.log('warn', `approval ${keyString}: ${error.message}`); return null; })
+        .then((hermes) => this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: runtime.handle.runtime_id, ev: { ...w, hermes }, at })));
+      return;
+    }
+    this.enqueue(events.worker({ profile: profileName, keyString, runtime_id: runtime.handle.runtime_id, ev: w, at }));
+    if (w.kind === 'final') this.mirrorTurn(profileName, keyString, w);
+  }
+
+  /**
+   * After a worker's turn, its transcript into the home's Hermes session store (docs/plans/hermes-compat.md
+   * row 11), under the routing entry's session id, so the conversation opens under Hermes. A binding whose
+   * worker has not reported its session yet is mirrored on a later turn. A session Hermes wrote to since
+   * the last mirror is never rewritten: its turns carry over at the worker's next start.
+   */
+  mirrorTurn(profileName, keyString, final = null) {
+    const profile = this.state.profiles[profileName];
+    const b = profile?.bindings?.[keyString];
+    const w = b?.worker;
+    if (!w?.session_id || !WORKER_STORE[w.harness]) return;
+    const run = (this.mirrors ??= new Map());
+    const previous = run.get(keyString) ?? Promise.resolve();
+    const next = previous.then(async () => {
+      const locator = await this.workerLocator(profile, keyString, w);
+      if (!locator) { this.log('warn', `mirror ${keyString}: ${w.harness} session ${w.session_id} is not in ${join(profile.dir, w.harness)}`); return; }
+      const loaded = await this.client.loadWindow(locator, { message_limit: 1_000_000 });
+      // a fire's session ends with its run, as Hermes's scheduler ends it (`cron_complete`, or
+      // `cron_incomplete_no_output` for a run that said nothing)
+      const said = (loaded.session.messages ?? []).some((m) => m.role === 'assistant' && (typeof m.content === 'string' ? m.content.trim() : (m.content ?? []).length));
+      const end = b.recurrence && final ? (said ? 'cron_complete' : 'cron_incomplete_no_output') : null;
+      const got = await mirrorSession(profile.dir, {
+        id: w.session_id, sessionKey: hermesSessionKey(profileName, b.key), binding: b, session: loaded.session,
+        locator: locator.storage?.path ?? null, parent: this.continued?.get(keyString) ?? null, end,
+      });
+      if (got.diverged != null) this.log('warn', `mirror ${keyString}: Hermes continued ${w.session_id} while its worker was live; its turns carry over at the worker's next start, and this worker's turns since stay in its own store`);
+      else if (got.mirrored === null) this.log('warn', `mirror ${keyString}: ${got.why}`);
+    }).catch((error) => this.log('warn', `mirror ${keyString}: ${error.message}`));
+    run.set(keyString, next);
+  }
+
+  /** The worker's own session, found by its id in the profile's worker home. */
+  async workerLocator(profile, keyString, w) {
+    const cached = this.locators?.get(keyString);
+    if (cached?.session_id === w.session_id) return cached;
+    const { sessions } = await this.client.discover({
+      harnesses: [w.harness], homes: WORKER_STORE[w.harness](join(profile.dir, w.harness)),
+      include_child_sessions: true, root_session_id: w.session_id, limit: 8,
+    });
+    const found = sessions.find((d) => d.locator.session_id === w.session_id)?.locator ?? null;
+    if (found) (this.locators ??= new Map()).set(keyString, found);
+    return found;
+  }
+
+  /**
+   * The session a worker resumes (docs/plans/hermes-compat.md row 11, Hermes to worker). Where Hermes
+   * carried the conversation past the worker (a mirror resumed under Hermes, or a conversation Hermes
+   * held when this home was its), its transcript is handed to the worker's harness and materialized in
+   * the worker's home, the old mirror sealed, and that new session resumed; otherwise `sessionId`.
+   */
+  async continueFromHermes(profile, keyString, worker, sessionId, cwd) {
+    const store = WORKER_STORE[worker.harness];
+    if (!store) return sessionId;
+    const state = await mirrorState(profile.dir, sessionId);
+    if (!state?.ahead) return sessionId;
+    try {
+      const hermes = { harness: 'hermes', session_id: sessionId, storage: { kind: 'file', path: join(profile.dir, 'state.db') } };
+      const { artifact } = await this.client.handoffSession({ locator: hermes, target_harness: worker.harness, cwd });
+      const { locator } = await this.client.materializeSession({ artifact, cwd, homes: store(join(profile.dir, worker.harness)) });
+      await sealMirror(profile.dir, sessionId, locator.session_id);
+      (this.locators ??= new Map()).set(keyString, locator);
+      (this.continued ??= new Map()).set(keyString, sessionId);
+      this.log('info', `resume ${keyString}: Hermes carried ${sessionId} on (${state.messages} messages); it goes on as ${worker.harness} ${locator.session_id}`);
+      return locator.session_id;
+    } catch (error) {
+      this.log('warn', `resume ${keyString}: Hermes carried ${sessionId} on, and its turns could not be handed to ${worker.harness} (${error.message}); resuming the worker's own session without them`);
+      return sessionId;
+    }
+  }
+
+  /** A line for a turn in flight, through the harness's own `steer` door; refused, it waits for the turn's end. */
+  async steerInput({ profile, keyString, text }) {
+    const runtime = this.runtimes.get(leaseId(profile, keyString));
+    const requeue = (why) => {
+      this.log('info', `steer ${keyString}: ${why}; the line waits for the turn's end`);
+      this.enqueue(events.worker({ profile, keyString, runtime_id: runtime?.handle?.runtime_id ?? null, ev: { kind: 'steer_refused', text }, at: this.clock() }));
+    };
+    if (!runtime) return requeue('no runtime');
+    try { await runtime.steer(text); } catch (error) { requeue(error.message); }
+  }
+
+  async sendInput({ profile, keyString, text, context_from = null, skills = [], job_id = null }) {
+    const runtime = this.runtimes.get(leaseId(profile, keyString));
+    if (!runtime) { this.log('warn', `send_input with no runtime for ${keyString}`); return; }
+    const owner = this.state.profiles[profile];
+    const dir = owner?.dir;
+    let input = context_from && dir ? contextFromPrefix(dir, job_id, context_from) + text : text;
+    if (skills?.length && owner) input = await this.skillsPrefix(owner, skills, owner.jobs?.[job_id]?.workdir ?? null, input) ?? input;
+    try {
+      await runtime.sendInput(input);
+    } catch (error) {
+      this.enqueue(events.worker({ profile, keyString, runtime_id: runtime.handle.runtime_id, ev: { kind: 'error', message: `send failed: ${error.message}` }, at: this.clock() }));
+    }
+  }
+
+  /**
+   * Hermes `cron/scheduler.py:4733-4812`, transcribed: a job's `skills` are
+   * invoked, not merely available. Each named skill is found through the
+   * worker harness's own loader (`harness.v1.skills.list`, the roots that
+   * harness reads) and its `SKILL.md` is loaded ahead of the prompt with
+   * Hermes's framing; a skill that is not there is named in a notice the
+   * model is told to open with, never dropped silently.
+   */
+  async skillsPrefix(profile, list, workdir, input) {
+    const names = (Array.isArray(list) ? list : [list]).map((n) => String(n ?? '').trim()).filter(Boolean);
+    if (!names.length) return null;
+    let rows = [];
+    try {
+      rows = await this.client.listSkills({ harness: profile.worker.harness, cwd: activationCwd(profile, workdir), homes: harnessHomes(profile) }) ?? [];
+    } catch (error) {
+      this.log('warn', `skills for ${profile.name}: ${error.message}`);
+    }
+    const parts = [];
+    const skipped = [];
+    for (const name of names) {
+      const row = rows.find((r) => r.name === name && r.enabled !== false);
+      const file = row && join(row.location, 'SKILL.md');
+      // Hermes's template variable for the skill's own folder, so its
+      // scripts/ and references/ resolve (`agent/skill_preprocessing.py`)
+      const content = file && existsSync(file) ? readFileSync(file, 'utf8').replaceAll('${HERMES_SKILL_DIR}', row.location).trim() : '';
+      if (!content) { skipped.push(name); continue; }
+      if (parts.length) parts.push('');
+      parts.push(`[IMPORTANT: The user has invoked the "${name}" skill, indicating they want you to follow its instructions. The full skill content is loaded below.]`, '', content);
+    }
+    if (skipped.length) {
+      parts.unshift(`[IMPORTANT: The following skill(s) were listed for this job but could not be found and were skipped: ${skipped.join(', ')}. Start your response with a brief notice so the user is aware, e.g.: '⚠️ Skill(s) not found and skipped: ${skipped.join(', ')}']`);
+      this.log('warn', `skills for ${profile.name}: not found: ${skipped.join(', ')}`);
+    }
+    // Hermes ends the scaffold with its instruction marker (`append_user_instruction`)
+    parts.push('');
+    return `${parts.join('\n')}\nThe user has provided the following instruction alongside the skill invocation: ${input}`;
+  }
+
+  async respond({ profile, keyString, request_id, response }) {
+    const runtime = this.runtimes.get(leaseId(profile, keyString));
+    if (!runtime) return;
+    try { await runtime.respond(JSON.parse(request_id), response); }
+    catch { try { await runtime.respond(request_id, response); } catch (error) { this.log('warn', `respond failed: ${error.message}`); } }
+  }
+
+  async closeRuntime({ profile, keyString, runtime_id = null }) {
+    const lid = leaseId(profile, keyString);
+    // a close naming a runtime closes only that one, never a newer one on the same surface
+    if (runtime_id && this.retired.has(runtime_id)) {
+      const old = this.retired.get(runtime_id);
+      this.retired.delete(runtime_id);
+      this.turnCounters?.delete(runtime_id);
+      try { await old.close(); } catch { /* already gone */ }
+      return;
+    }
+    const runtime = this.runtimes.get(lid);
+    if (runtime_id && runtime && runtime.handle.runtime_id !== runtime_id) return;
+    this.runtimes.delete(lid);
+    if (runtime) this.turnCounters?.delete(runtime.handle.runtime_id);
+    if (runtime) { try { await runtime.close(); } catch { /* already gone */ } }
+  }
+
+  /**
+   * One send attempt, through the per-adapter breaker (§2.8). An open breaker
+   * leaves the obligation `pending` and its `attempts` untouched — the tick
+   * re-emits it once `until` passes. Three consecutive failures on one adapter
+   * open it; any success closes it.
+   */
+  async deliver({ profile: profileName, obligation_id }) {
+    const profile = this.state.profiles[profileName];
+    const o = profile.obligations.find((x) => x.id === obligation_id);
+    if (!o || o.state !== 'pending') return;
+    const now = this.clock();
+    const rt = this.state.runtime;
+    rt.adapters ??= {};
+    const adapter = this.adapters[o.target.platform];
+    // a platform no adapter serves gets no entry: the entries are what the
+    // delivery preflight reads as connected
+    if (!adapter) {
+      o.attempts += 1;
+      o.updated_at = String(Date.parse(now) / 1000);
+      o.state = 'failed';
+      o.last_error = `no adapter for ${o.target.platform}`;
+      this.recordDelivery(profile, o, o.last_error);
+      await save(this.state, this.state.root);
+      return;
+    }
+    const entry = (rt.adapters[o.target.platform] ??= { state: 'up', breaker: { failures: 0 } });
+    entry.breaker ??= { failures: 0 };
+    if (entry.breaker.until && Date.parse(now) < Date.parse(entry.breaker.until)) {
+      this.log('warn', `deliver ${o.id}: ${o.target.platform} breaker open until ${entry.breaker.until}`);
+      return;
+    }
+    o.attempts += 1;
+    o.updated_at = String(Date.parse(now) / 1000);
+    try {
+      // the whole OutboundContent (§2.1): reply_to and attachments reach the adapter, not only text
+      const receipt = await adapter.send(o.target, { ...o.content, text: o.content.text, at: now });
+      if (receipt?.message_id) o.posted = { message_id: String(receipt.message_id) }; // §2.6 `posted`: the platform's handle for what was sent (ORC-1 F4)
+      o.state = 'sent';
+      o.delivered_at = o.updated_at;
+      o.last_error = null;
+      entry.breaker = { failures: 0 };
+      this.recordDelivery(profile, o, null);
+    } catch (error) {
+      o.last_error = error.message;
+      entry.breaker.failures += 1;
+      if (entry.breaker.failures >= BREAKER_FAILURES) {
+        entry.breaker.until = new Date(Date.parse(now) + BREAKER_MINUTES * 60_000).toISOString();
+        this.log('warn', `${o.target.platform}: ${entry.breaker.failures} consecutive send failures, breaker open until ${entry.breaker.until}`);
+      }
+      if (o.attempts >= MAX_ATTEMPTS) { o.state = 'failed'; this.recordDelivery(profile, o, error.message); }
+    }
+    await save(this.state, this.state.root);
+  }
+
+  /**
+   * Hermes's `last_delivery_error` on the job (`cron/scheduler.py`,
+   * `mark_job_run`): the reason a fire's answer never arrived. Each run
+   * resets it (`finishFire`); a failed delivery writes it and is logged.
+   */
+  recordDelivery(profile, o, error) {
+    const fire = o.source?.kind === 'fire' ? profile.fires.find((f) => f.id === o.source.fire_id) : null;
+    const job = fire ? profile.jobs[fire.job_id] : null;
+    if (job) (job.residue ??= {}).last_delivery_error = error;
+    if (!error) return;
+    const what = job ? `Cron job ${job.id}` : o.source?.kind === 'webhook' ? `Webhook ${o.source.name}` : 'A reply';
+    this.log('warn', `${what}: its answer could not be delivered to ${o.target.platform} after ${o.attempts} attempt(s): ${error}`);
+  }
+
+  /** `deliver: local` — the fire's answer as a file under the profile folder (§4.3). */
+  writeLocal({ profile: profileName, path, text }) {
+    const profile = this.state.profiles[profileName];
+    if (!profile) { this.log('warn', `write_local for unknown profile ${profileName}`); return; }
+    const full = join(profile.dir, path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text.endsWith('\n') ? text : `${text}\n`);
+    // Hermes `_prune_job_output`: a job keeps its newest `cron.output_retention`
+    // run files (50), never the whole history; zero or less keeps everything
+    if (/^cron\/output\/[^/]+\/[^/]+\.md$/.test(path)) {
+      const keep = historyRetention(profile).outputs;
+      if (keep > 0) {
+        const dir = dirname(full);
+        try {
+          for (const stale of readdirSync(dir).filter((f) => f.endsWith('.md')).sort().reverse().slice(keep)) {
+            try { unlinkSync(join(dir, stale)); } catch { /* pruning never breaks saving */ }
+          }
+        } catch { /* as in Hermes: pruning failures are swallowed */ }
+      }
+    }
+  }
+}
+
+/**
+ * Hermes `cron/scheduler.py:4823-4895`, transcribed: for each job id in
+ * `context_from` ("self" is this job), the newest `cron/output/<id>/*.md` is
+ * prepended, capped at 8,000 characters, with Hermes's own framing. A job with
+ * no output yet is skipped silently, as there.
+ */
+export function contextFromPrefix(profileDir, jobId, refs) {
+  let prefix = '';
+  for (const ref of refs ?? []) {
+    const isSelf = String(ref).trim().toLowerCase() === 'self' || ref === jobId;
+    const id = isSelf ? jobId : String(ref).trim();
+    if (!id || /[\/\\]/.test(id) || id === '.' || id === '..') continue;
+    const dir = join(profileDir, 'cron', 'output', id);
+    if (!existsSync(dir)) continue;
+    const files = readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+    if (!files.length) continue;
+    let latest = readFileSync(join(dir, files[files.length - 1]), 'utf8').trim();
+    if (!latest) continue;
+    if (latest.length > 8000) latest = `${latest.slice(0, 8000)}\n\n[... output truncated ...]`;
+    prefix += isSelf
+      ? `## Your previous run's output\nThe following is this job's most recent output from its previous run. Use it for continuity: avoid repeating what was already reported, and continue where the last run left off.\n\n\`\`\`\n${latest}\n\`\`\`\n\n`
+      : `## Output from job '${id}'\nThe following is the most recent output from a preceding cron job. Use it as context for your analysis.\n\n\`\`\`\n${latest}\n\`\`\`\n\n`;
+  }
+  return prefix;
+}
+
+/**
+ * Hermes's `HERMES_CRON_MAX_PARALLEL` (the daemon's environment), which wins
+ * over each profile's `cron.max_parallel_jobs`: a positive cap, or null.
+ */
+export function cronMaxParallel(raw = process.env.HERMES_CRON_MAX_PARALLEL) {
+  const text = String(raw ?? '').trim();
+  if (!text || !/^[+-]?\d+$/.test(text)) return null;
+  const n = Number(text);
+  return n > 0 ? n : null;
+}
+
+/**
+ * Hermes `cron/scheduler.py` `_cron_inactivity_seconds`, transcribed: the
+ * daemon's `HERMES_CRON_TIMEOUT` in seconds; unset or unreadable is 600, 0 is
+ * no limit.
+ */
+export function cronInactivitySeconds(raw = process.env.HERMES_CRON_TIMEOUT) {
+  const text = String(raw ?? '').trim();
+  if (!text) return 600;
+  // Python's float(): digit underscores, nan and inf are numbers; hex is not
+  if (!/^[+-]?(((\d(_?\d)*)?\.?\d(_?\d)*|\d(_?\d)*\.)([eE][+-]?\d+)?|nan|inf(inity)?)$/i.test(text)) return 600;
+  const n = Number(text.replace(/_/g, '').replace(/^([+-]?)inf(inity)?$/i, '$1Infinity'));
+  // Hermes uses the limit only when it is > 0; anything else is no limit
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/** `gateway.webhook_port` out of config.yaml's Hermes residue; 0 (any free port) when unset. */
+export function webhookPort(state) {
+  for (const profile of Object.values(state.profiles)) {
+    const port = profile.residue?.config?.gateway?.webhook_port;
+    if (Number.isInteger(port)) return port;
+  }
+  return 0;
+}
+
+/**
+ * Claude Code's `can_use_tool` reaches the runtime as a native control request, not a normalized
+ * `request`; unrelayed, the turn sits blocked until the runtime's own timeout denies it. Its id is the
+ * CLI's `request_id` (a string, which is what the runtime's respond door takes) and its answers are
+ * the two the CLI accepts.
+ */
+function claudePermissionRequest(payload) {
+  const request = payload?.request;
+  if (request?.subtype !== 'can_use_tool' || typeof payload.request_id !== 'string') return null;
+  const input = request.input ?? {};
+  const detail = typeof input.command === 'string' ? input.command
+    : typeof input.file_path === 'string' ? input.file_path
+      : JSON.stringify(input).slice(0, 200);
+  return {
+    kind: 'request',
+    id: JSON.stringify(payload.request_id),
+    command: typeof input.command === 'string' ? input.command : null,
+    tool: typeof request.tool_name === 'string' ? request.tool_name : null,
+    subject: `${request.display_name ?? request.tool_name ?? 'a tool'}: ${detail}`,
+    options: [
+      { name: 'Allow', kind: 'allow_once', response: { behavior: 'allow', updatedInput: input } },
+      { name: 'Deny', kind: 'reject_once', response: { behavior: 'deny', message: 'denied in the channel' } },
+    ],
+  };
+}
+
+/** The shell command a worker asks to run (Codex's `params.command`, a string or an argv), for Hermes's rule. */
+function requestCommand(payload) {
+  const raw = payload?.params?.command ?? payload?.command ?? payload?.params?.input?.command ?? null;
+  if (Array.isArray(raw)) return raw.map(String).join(' ');
+  return typeof raw === 'string' ? raw : null;
+}
+
+/** An MCP tool a worker asks to call, in Claude Code's `mcp__<server>__<tool>` form, and whether the ask is an MCP one. */
+function requestTool(ev) {
+  const params = ev.payload?.params ?? ev.payload ?? {};
+  const server = params.serverName ?? params.server_name ?? params.server ?? null;
+  const tool = params.toolName ?? params.tool_name ?? params.tool ?? null;
+  const mcp = /mcp|elicitation/i.test(String(ev.requestKind ?? ev.kind ?? '')) || Boolean(server);
+  return { ...(server && tool ? { tool: `mcp__${server}__${tool}` } : {}), ...(mcp ? { mcp: true } : {}) };
+}
+
+/** SDK normalized runtime event → the reducer's worker-event vocabulary (§3). */
+export function normalizeWorkerEvent(ev) {
+  // A helper the session started speaks inside its own tool call (Claude Code marks each of its
+  // frames with the parent_tool_use_id that started it): its words are the session working, not
+  // the session talking, and reach the conversation only through what the session itself says.
+  if ((ev.type === 'output_delta' || ev.type === 'message') && ev.payload?.parent_tool_use_id) return null;
+  switch (ev.type) {
+    // A streamed chunk names the message it belongs to where the worker says (Codex: `item/agentMessage/delta`'s
+    // `itemId`, measured), so the turn's text can start a new paragraph where a new message starts.
+    case 'output_delta': return ev.text ? { kind: 'text', delta: ev.text, item: ev.payload?.params?.itemId ?? null } : null;
+    // A whole assistant message (not a streamed chunk): the turn's text keeps it as its own paragraph.
+    case 'message': return ev.role === 'assistant' && ev.text ? { kind: 'text', delta: ev.text, block: true } : null;
+    case 'turn_completed': return { kind: 'final', text: null, outcome: ev.outcome ?? 'completed', message: ev.message ?? null };
+    case 'native':
+      if (ev.kind === 'supercode/acp_request_completed') return { kind: 'final', text: null };
+      if (ev.kind === 'control_request') return claudePermissionRequest(ev.payload);
+      return null;
+    case 'request': return { kind: 'request', id: JSON.stringify(ev.requestId), command: requestCommand(ev.payload), ...requestTool(ev), subject: ev.requestKind ?? ev.kind, options: ev.options ?? [] };
+    case 'error': return ev.terminal ? { kind: 'error', message: ev.message } : null;
+    case 'closed': return { kind: 'ended', reason: ev.message ?? ev.kind };
+    default: return null;
+  }
+}
+
+export { surfaceKeyString };