@volter/supercode-orchestrator 0.4.4

package/operator.mjs

@@ -0,0 +1,426 @@
+// The orchestrator's OPERATOR door: one implementation of every §4.6 verb,
+// shared by the daemon socket (`mcp/bridge.mjs`) and the cold-path CLI
+// (`bin/orchestrator.mjs`).
+//
+//   applyOperator(state, op, args, profile, now, dispatch)
+//     -> {ok: true, result: {ran, …}} | {ok: false, error: "…"}
+//
+// The ops, exactly [`OPERATOR_OPS`]:
+//
+//   jobs.create | jobs.update | jobs.pause | jobs.resume | jobs.run | jobs.delete
+//   profiles.create | profiles.delete
+//   sessions.new | sessions.reset
+//   access.pair_approve
+//
+// `dispatch(event)` applies ONE reducer event and performs its effects; the
+// loop passes `orch.dispatch` (so an operator verb is ordered against inbound
+// messages and ticks like anything else) and the CLI passes a `step` + a save.
+// Nothing here performs I/O of its own: the folder is only ever written by
+// `save()`, through a `save` effect the reducer emits.
+//
+// Two rules this door inherits from the controlled tier it serves:
+//
+// 1. **The reducer is the only thing that changes state.** Every op below
+//    validates its arguments, builds ONE `events.operator(...)`, and reads the
+//    affected record back out of `state` afterwards. It never mutates state.
+// 2. **A refusal names its reason.** The reducer refuses by pushing a
+//    `{type:'log', level:'warn'}` effect and no `save`; that message becomes
+//    `{ok: false, error}` verbatim, so a verb the reducer rejected can never
+//    look like a silent no-op.
+
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { keyFromString, parseSchedule } from './mcp/verbs.mjs';
+import { emptyProfile, parseTarget, renderTarget, surfaceKeyString, decodeContextFrom } from './ir.mjs';
+import { liveBinding } from './reducer.mjs';
+import { compactStamp, gateFields, homeZone, nextRunAt, payloadError } from './cron.mjs';
+import * as events from './events.mjs';
+import { modelError } from './activation.mjs';
+
+/** Every op the operator door answers, in §4.6 order. */
+export const OPERATOR_OPS = Object.freeze([
+  'jobs.create', 'jobs.update', 'jobs.pause', 'jobs.resume', 'jobs.run', 'jobs.delete',
+  'profiles.create', 'profiles.delete',
+  'sessions.new', 'sessions.reset',
+  'access.pair_approve',
+]);
+
+/** Where a deleted profile folder is renamed to, relative to the root. */
+export const TRASH_DIR = 'profiles/.trash';
+
+class Refused extends Error {}
+
+/**
+ * Perform the reducer's `remove_profile_dir` effect (the ONLY effect this door
+ * adds, §5). The folder is never unlinked: it is renamed into
+ * `profiles/.trash/<name>-<stamp>/`, which `load` skips because a profile
+ * folder's name may not start with a dot. One implementation, called by the
+ * loop and by the cold path alike.
+ *
+ * @returns {string|null} where the folder went, or `null` when there was none
+ */
+export function performRemoveProfileDir(root, { profile, dir }, now) {
+  if (!dir || !existsSync(dir)) return null;
+  const trash = join(root, TRASH_DIR);
+  mkdirSync(trash, { recursive: true });
+  const stamp = String(now).replace(/[^0-9]/g, '').slice(0, 14);
+  let dest = join(trash, `${profile}-${stamp}`);
+  for (let n = 2; existsSync(dest); n += 1) dest = join(trash, `${profile}-${stamp}-${n}`);
+  renameSync(dir, dest);
+  return dest;
+}
+
+/** A job id that is free in this profile — the same stem the MCP door uses. */
+function jobId(profile, now) {
+  const stem = `job_${compactStamp(now)}`;
+  if (!profile.jobs[stem]) return stem;
+  for (let n = 2; ; n++) if (!profile.jobs[`${stem}_${n}`]) return `${stem}_${n}`;
+}
+
+/**
+ * Hermes's cron-tool words as the job's own (tools/cronjob_tools.py): `monitor` is a URL source when it
+ * starts with http(s)://, else a script, and setting one clears the other (`_split_monitor_arg`);
+ * `continuity` adds or removes `self` in `context_from` (`_apply_continuity`).
+ */
+export function hermesJobArgs(args, job = null) {
+  const out = { ...args };
+  if (typeof args.monitor === 'string') {
+    const value = args.monitor.trim();
+    const url = /^https?:\/\//i.test(value);
+    out.monitor_script = url ? '' : value;
+    out.monitor_url = url ? value : '';
+    delete out.monitor;
+  }
+  if (typeof args.continuity === 'boolean') {
+    const refs = (decodeContextFrom('cronjob', 'context_from', args.context_from !== undefined ? args.context_from : job?.context_from) ?? []);
+    const self = refs.some((r) => r.toLowerCase() === 'self');
+    out.context_from = args.continuity && !self ? [...refs, 'self'] : !args.continuity && self ? refs.filter((r) => r.toLowerCase() !== 'self') : refs;
+    delete out.continuity;
+  }
+  return out;
+}
+
+/**
+ * A complete §2.6 Job record from operator arguments. The caller's words are
+ * the orchestrator's own (`prompt`, `schedule`, `deliver`, `name`, …); a field
+ * the model has no home for is refused by name rather than dropped.
+ */
+export function buildJob(profile, args, now, { origin = null } = {}) {
+  const gate = gateFields(args);
+  const empty = payloadError(args, gate);
+  if (empty) throw new Error(empty);
+  if (args.metadata !== undefined && (!args.metadata || typeof args.metadata !== 'object' || Array.isArray(args.metadata) || JSON.stringify(args.metadata).length > 16384)) throw new Error('metadata must be an object of at most 16 KiB');
+  const schedule = parseSchedule(args.schedule, now, profile.dir);
+  const unusable = modelError(profile.worker?.harness, args.model ? String(args.model) : null);
+  if (unusable) throw new Error(unusable);
+  const id = args.id ? String(args.id) : jobId(profile, now);
+  return {
+    id,
+    schedule,
+    prompt: typeof args.prompt === 'string' ? args.prompt : '',
+    workdir: args.workdir ? String(args.workdir) : null,
+    model: args.model ? String(args.model) : null,
+    skills: Array.isArray(args.skills) ? args.skills.map(String) : [],
+    context_from: decodeContextFrom('jobs.create', 'context_from', args.context_from),
+    deliver: parseTarget('operator/jobs.create', 'deliver', args.deliver) ?? { kind: 'origin' },
+    failure_deliver: parseTarget('operator/jobs.create', 'failure_deliver', args.failure_deliver),
+    origin,
+    attach_to_session: typeof args.attach_to_session === 'boolean' ? args.attach_to_session : null,
+    repeat: Number.isInteger(args.repeat) && args.repeat > 0 ? { times: args.repeat, completed: 0 } : null,
+    enabled: args.enabled !== false,
+    next_run_at: args.enabled === false ? null : nextRunAt(schedule, now, homeZone(profile)),
+    last_run_at: null,
+    last_status: null,
+    created_at: now,
+    // Hermes's `name` has no IR field; it rides the residue channel (§1 rule 6).
+    residue: { ...(args.metadata ? { host: structuredClone(args.metadata) } : {}), ...(args.name ? { name: String(args.name) } : {}), ...toolsets(args.enabled_toolsets), ...gate },
+  };
+}
+
+/**
+ * The operator's patch for `jobs.update`, in the job's own field names.
+ * `job` is the record being patched: the reducer `Object.assign`s, so any
+ * field it replaces wholesale (`residue`) is merged HERE rather than dropping
+ * the keys the operator did not name (§1 rule 6).
+ */
+/** Hermes's `enabled_toolsets` (its agent's own setting, carried in the job for when Hermes runs it). */
+function toolsets(value) {
+  if (!Array.isArray(value)) return {};
+  const names = value.map((x) => String(x).trim()).filter(Boolean);
+  return names.length ? { enabled_toolsets: names } : {};
+}
+
+function buildPatch(args, now, job, zone, home) {
+  const patch = {};
+  if (args.prompt !== undefined) {
+    if (typeof args.prompt !== 'string' || !args.prompt.trim()) throw new Error('prompt must be a non-empty string');
+    patch.prompt = args.prompt;
+  }
+  if (args.schedule !== undefined) {
+    patch.schedule = parseSchedule(args.schedule, now, home);
+    // A schedule that changed re-arms the job; `next_run_at` is derived, never
+    // carried over from the schedule it no longer describes (§4.3).
+    patch.next_run_at = nextRunAt(patch.schedule, now, zone);
+  }
+  if (args.deliver !== undefined) patch.deliver = parseTarget('operator/jobs.update', 'deliver', args.deliver) ?? { kind: 'origin' };
+  if (args.failure_deliver !== undefined) patch.failure_deliver = parseTarget('operator/jobs.update', 'failure_deliver', args.failure_deliver);
+  if (args.workdir !== undefined) patch.workdir = args.workdir ? String(args.workdir) : null;
+  if (args.model !== undefined) patch.model = args.model ? String(args.model) : null;
+  if (args.enabled !== undefined) patch.enabled = Boolean(args.enabled);
+  if (args.name !== undefined) patch.residue = { ...(patch.residue ?? job?.residue ?? {}), name: String(args.name) };
+  // Hermes's update words: an empty list clears (update_job)
+  if (args.skills !== undefined) patch.skills = Array.isArray(args.skills) ? args.skills.map(String).filter((x) => x.trim()) : [];
+  if (args.context_from !== undefined) patch.context_from = decodeContextFrom('jobs.update', 'context_from', args.context_from);
+  if (args.attach_to_session !== undefined) patch.attach_to_session = typeof args.attach_to_session === 'boolean' ? args.attach_to_session : null;
+  if (args.repeat !== undefined) patch.repeat = Number.isInteger(args.repeat) && args.repeat > 0 ? { times: args.repeat, completed: 0 } : null;
+  if (args.enabled_toolsets !== undefined) {
+    const { enabled_toolsets: _, ...rest } = patch.residue ?? job?.residue ?? {};
+    patch.residue = { ...rest, ...toolsets(args.enabled_toolsets) };
+  }
+  // the gate fields, in Hermes's names; an empty value clears one, as update_job does
+  const GATE_KEYS = ['script', 'no_agent', 'monitor_script', 'monitor_url'];
+  if (GATE_KEYS.some((k) => args[k] !== undefined)) {
+    const residue = { ...(patch.residue ?? job?.residue ?? {}) };
+    const next = Object.fromEntries(GATE_KEYS.map((k) => [k, args[k] !== undefined ? args[k] : residue[k]]));
+    for (const k of GATE_KEYS) delete residue[k];
+    patch.residue = { ...residue, ...gateFields(next) }; // validated; an empty value is gone
+  }
+  // Hermes's update_job refuses an edit that leaves nothing to run (EMPTY_PAYLOAD_ERROR)
+  if (patch.prompt !== undefined || GATE_KEYS.some((k) => args[k] !== undefined)) {
+    const merged = { prompt: patch.prompt ?? job?.prompt, skills: patch.skills ?? job?.skills };
+    const empty = payloadError(merged, { script: (patch.residue ?? job?.residue ?? {}).script ?? null });
+    if (empty) throw new Error(empty);
+  }
+  if (!Object.keys(patch).length) throw new Error('jobs.update changes nothing; name at least one of prompt, schedule, deliver, failure_deliver, workdir, model, enabled, name, skills, context_from, repeat, attach_to_session, enabled_toolsets, script, no_agent, monitor_script, monitor_url');
+  return patch;
+}
+
+function describeSchedule(s) {
+  if (s.kind === 'once') return `once at ${s.run_at}`;
+  if (s.kind === 'interval') return `every ${s.minutes} min`;
+  return `cron ${s.expr}${s.tz ? ` ${s.tz}` : ''}`;
+}
+
+/** The public view of one job. */
+function jobView(job) {
+  return job ? { ...job } : null;
+}
+
+/** The public view of one profile folder record. */
+function profileView(profile) {
+  return {
+    name: profile.name,
+    dir: profile.dir,
+    worker: profile.worker ? { ...profile.worker } : null,
+    jobs: Object.keys(profile.jobs).length,
+    bindings: Object.keys(profile.bindings).length,
+  };
+}
+
+function bindingView(binding, keyString) {
+  return {
+    surface: keyString,
+    session_id: binding.worker?.session_id || null,
+    harness: binding.worker?.harness ?? null,
+    started_at: binding.started_at,
+    ended_at: binding.ended_at ?? null,
+    end_reason: binding.end_reason ?? null,
+  };
+}
+
+/** The ended binding for `keyString` with the newest `started_at`. */
+function endedBinding(profile, keyString) {
+  let best = null;
+  for (const [slot, b] of Object.entries(profile.bindings)) {
+    if (!slot.startsWith(`${keyString}#`) || !b.ended_at) continue;
+    if (!best || b.started_at > best.started_at) best = b;
+  }
+  return best;
+}
+
+/**
+ * The reducer's own refusal, when it refused: a `log` effect and no `save`
+ * means the state did not change and the message says why.
+ */
+function refusalIn(effects) {
+  if (effects.some((e) => e.type === 'save')) return null;
+  const warn = effects.find((e) => e.type === 'log' && e.level === 'warn');
+  return warn ? warn.message : null;
+}
+
+/**
+ * Apply one operator verb.
+ *
+ * @param {object} state                 the orchestrator's single state value
+ * @param {string} op                    one of [`OPERATOR_OPS`]
+ * @param {object} args                  the verb's own arguments
+ * @param {string} profileName           profile the verb acts in
+ * @param {string} now                   RFC 3339 instant (the caller's clock)
+ * @param {(event: object) => Promise<object[]>|object[]} dispatch
+ *        applies one reducer event and performs its effects, returning them
+ * @returns {Promise<{ok: true, result: object} | {ok: false, error: string}>}
+ */
+export async function applyOperator(state, op, args = {}, profileName = 'default', now = new Date().toISOString(), dispatch) {
+  if (typeof dispatch !== 'function') throw new TypeError('applyOperator needs a dispatch(event) that applies one reducer event');
+  if (!OPERATOR_OPS.includes(op)) {
+    return { ok: false, error: `unknown operator op ${JSON.stringify(op)}; the orchestrator answers: ${OPERATOR_OPS.join(', ')}` };
+  }
+  const profile = state.profiles[profileName];
+  if (!profile) {
+    return { ok: false, error: `unknown profile ${JSON.stringify(profileName)}; this home holds: ${Object.keys(state.profiles).sort().join(', ')}` };
+  }
+  const send = async (verb, verbArgs, target = profileName) => {
+    const effects = (await dispatch(events.operator({ verb, profile: target, args: verbArgs, at: now }))) ?? [];
+    const refusal = refusalIn(effects);
+    if (refusal) throw new Refused(refusal);
+    return effects;
+  };
+  try {
+    return { ok: true, result: await run(state, profile, op, args ?? {}, now, send) };
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+async function run(state, profile, op, args, now, send) {
+  switch (op) {
+    case 'jobs.create': {
+      const origin = args.surface ? keyOrigin(args.surface) : null;
+      const job = buildJob(profile, args, now, { origin });
+      await send('jobs_create', { job });
+      return {
+        ran: `created cron job ${job.id} (${describeSchedule(job.schedule)}) in profile ${profile.name}, delivering to ${renderTarget(job.deliver)}`,
+        job_id: job.id,
+        job: jobView(profile.jobs[job.id]),
+      };
+    }
+
+    case 'jobs.update': {
+      const id = requireId(args, 'jobs.update');
+      const patch = buildPatch(args, now, profile.jobs[id], homeZone(profile), profile.dir);
+      const unusable = modelError(profile.worker?.harness, patch.model);
+      if (unusable) throw new Error(unusable);
+      await send('jobs_update', { id, patch });
+      return {
+        ran: `updated cron job ${id} in profile ${profile.name} (${Object.keys(patch).sort().join(', ')})`,
+        job_id: id,
+        job: jobView(profile.jobs[id]),
+      };
+    }
+
+    case 'jobs.pause':
+    case 'jobs.resume': {
+      const id = requireId(args, op);
+      await send(op === 'jobs.pause' ? 'jobs_pause' : 'jobs_resume', { id });
+      return {
+        ran: `${op === 'jobs.pause' ? 'paused' : 'resumed'} cron job ${id} in profile ${profile.name}`,
+        job_id: id,
+        job: jobView(profile.jobs[id]),
+      };
+    }
+
+    case 'jobs.run': {
+      const id = requireId(args, 'jobs.run');
+      await send('jobs_run', { id });
+      return {
+        ran: `cron job ${id} in profile ${profile.name} is due now; the next tick claims it`,
+        job_id: id,
+        job: jobView(profile.jobs[id]),
+      };
+    }
+
+    case 'jobs.delete': {
+      const id = requireId(args, 'jobs.delete');
+      await send('jobs_delete', { id });
+      return { ran: `removed cron job ${id} from profile ${profile.name}`, job_id: id, job: null, deleted: true };
+    }
+
+    case 'profiles.create': {
+      const name = String(args.name ?? '').trim();
+      if (!name) throw new Error('name is required');
+      if (name === 'default') throw new Error('the root folder IS the `default` profile; it exists as soon as the home does');
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.startsWith('.')) {
+        throw new Error(`profile name ${JSON.stringify(name)} is not a folder name: use letters, digits, '.', '_' and '-', starting with a letter or digit`);
+      }
+      const dir = args.dir ? String(args.dir) : `${state.root}/profiles/${name}`;
+      const record = emptyProfile(name, dir);
+      if (args.worker !== undefined && args.worker !== null) record.worker = buildWorker(args.worker);
+      // `profiles.create` is dispatched against a profile that EXISTS (the
+      // caller's context), because the reducer resolves `ev.profile` first.
+      await send('profiles_create', { profile: record }, profile.name);
+      const made = state.profiles[name];
+      if (!made) throw new Error(`profiles.create: profile ${name} was not added`);
+      return { ran: `created profile ${name} at ${dir}`, name, profile: profileView(made) };
+    }
+
+    case 'profiles.delete': {
+      const name = String(args.name ?? '').trim();
+      if (!name) throw new Error('name is required');
+      await send('profiles_delete', { name }, profile.name);
+      if (state.profiles[name]) throw new Error(`profiles.delete: profile ${name} is still in state`);
+      return { ran: `removed profile ${name}; its folder was moved into ${TRASH_DIR}/`, name, profile: null, deleted: true };
+    }
+
+    case 'sessions.new':
+    case 'sessions.reset': {
+      const surface = String(args.surface ?? '').trim();
+      if (!surface) throw new Error(`${op} needs the surface to act on (platform|kind|chat_id|thread_id|participant_id)`);
+      const key = keyFromString(surface);
+      if (!key) throw new Error(`surface ${JSON.stringify(surface)} is not a surface key: write it as platform|kind|chat_id|thread_id|participant_id`);
+      const keyString = surfaceKeyString(key);
+      const live = liveBinding(profile, keyString);
+      if (!live) {
+        throw new Error(`no live conversation on ${keyString} in profile ${profile.name}; \`${op}\` ends a binding that exists — \`supercode sessions list --harness orchestrator\` shows what does`);
+      }
+      const verb = op === 'sessions.new' ? 'sessions_new' : 'sessions_reset';
+      await send(verb, { keyString });
+      const ended = endedBinding(profile, keyString);
+      if (!ended) throw new Error(`${op}: the binding on ${keyString} did not end`);
+      return {
+        ran: `ended the conversation on ${keyString} in profile ${profile.name} (${ended.end_reason})`,
+        surface: keyString,
+        binding: bindingView(ended, keyString),
+      };
+    }
+
+    case 'access.pair_approve': {
+      const code = String(args.code ?? '').trim();
+      if (!code) throw new Error('code is required');
+      // Hermes's pairing store holds the code; the daemon asks it, and a grant reaches the allowlist
+      await send('pair_approve', { code });
+      return { ran: `asked Hermes's pairing store to approve ${code} for profile ${profile.name}`, code };
+    }
+
+    default:
+      throw new Error(`unknown operator op ${op}`);
+  }
+}
+
+function requireId(args, op) {
+  const id = String(args.id ?? args.job_id ?? '').trim();
+  if (!id) throw new Error(`${op} needs the job id to act on`);
+  return id;
+}
+
+/** A job's `origin`, from a surface key the operator named. */
+function keyOrigin(surface) {
+  const key = keyFromString(String(surface));
+  if (!key) throw new Error(`surface ${JSON.stringify(surface)} is not a surface key`);
+  return { platform: key.platform, chat_type: key.kind ?? null, chat_id: key.chat_id ?? null, thread_id: key.thread_id ?? null };
+}
+
+/** The §2.2 worker block from operator arguments. */
+function buildWorker(raw) {
+  if (typeof raw === 'string') return buildWorker({ harness: raw });
+  if (typeof raw !== 'object') throw new Error('worker must be a harness id or a {harness, model?, cwd?} object');
+  const harness = String(raw.harness ?? '').trim();
+  if (!harness) throw new Error('worker.harness is required');
+  return {
+    harness,
+    model: raw.model ? String(raw.model) : null,
+    preset: raw.preset ? String(raw.preset) : null,
+    cwd: raw.cwd ? String(raw.cwd) : '.',
+    env: {},
+    permission: { timeout_seconds: 300, default: 'deny' },
+  };
+}

package/orchestration.mjs

@@ -0,0 +1,166 @@
+// The folder, through the harness's orchestration doors.
+//
+// ONT-7: this package reads and writes its home through `harness.v1.orchestration.*`
+// (`crates/harness/src/orchestration_doors.rs`), never with a codec of its own. The
+// ontology's one codec is the Rust one; this module is its client side:
+//
+//   - `load(root)` asks `orchestration.load` for the orchestration value and adds the runtime
+//     half (`OrchestratorState` = orchestration + runtime, docs/ORCHESTRATOR-IR.md §2.1).
+//     The vault is read out of the home's own `.env` files here: a secret
+//     VALUE never crosses the wire, `orchestration.load` answers key names only.
+//   - `save(state, root)` hands the persisted view to `orchestration.save`. It sends
+//     no secret: the loop never mints one, and `.env` is the home's own file.
+//   - `compile`, `importFrom`, `exportTo` are the migration doors. A migration
+//     moves credentials, so `import` and `export` are composed inside the
+//     harness process (see the orchestration_doors module doc).
+//
+// One door per process: the first verb spawns `supercode harness serve`
+// (the binary that spawned us, else this checkout's build) and every verb
+// after it reuses it. The door is held open while a loop runs
+// (`retainWorld` / `releaseWorld`, the loop's `start` / `stop`) or a verb is
+// in flight; otherwise it closes itself after a short idle, so a process
+// that only loaded or saved (a test, a one-shot migration) exits on its own.
+// `closeWorld()` closes it now.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+import { emptyRuntime, persistedView } from './ir.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The binary the doors are opened with: `SUPERCODE_BIN` (set by `supercode
+ * orchestrator start` to the very binary that spawned the daemon), else this
+ * checkout's debug build, else `supercode` on PATH.
+ */
+export function supercodeCommand() {
+  if (process.env.SUPERCODE_BIN) return process.env.SUPERCODE_BIN;
+  const built = resolve(here, '../../target/debug/supercode');
+  return existsSync(built) ? built : 'supercode';
+}
+
+const IDLE_MS = 250;
+let shared = null;
+let holders = 0;
+let inFlight = 0;
+let idle = null;
+
+function door() {
+  if (!shared) shared = new SupercodeHarnessClient({ command: supercodeCommand(), args: ['harness', 'serve'] });
+  return shared;
+}
+
+/** Close the shared door. The next verb opens it again. */
+export async function closeWorld() {
+  if (idle) { clearTimeout(idle); idle = null; }
+  const client = shared;
+  shared = null;
+  if (client) await client.close();
+}
+
+function settle() {
+  if (idle) { clearTimeout(idle); idle = null; }
+  if (holders > 0 || inFlight > 0 || !shared) return;
+  idle = setTimeout(() => { idle = null; if (holders === 0 && inFlight === 0) void closeWorld(); }, IDLE_MS);
+  idle.unref?.();
+}
+
+/** Hold the door open (a running loop). Balanced by `releaseWorld`. */
+export function retainWorld() {
+  holders += 1;
+  if (idle) { clearTimeout(idle); idle = null; }
+}
+
+/** Let go of the door; it closes itself once nothing holds it and nothing is in flight. */
+export function releaseWorld() {
+  holders = Math.max(0, holders - 1);
+  settle();
+}
+
+async function through(verb) {
+  inFlight += 1;
+  if (idle) { clearTimeout(idle); idle = null; }
+  try {
+    return await verb(door());
+  } finally {
+    inFlight -= 1;
+    settle();
+  }
+}
+
+/** `KEY=value` lines; quotes stripped; `#` lines and blanks ignored. */
+export function parseDotenv(text) {
+  const out = new Map();
+  for (const line of text.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith('#')) continue;
+    const eq = t.indexOf('=');
+    if (eq < 0) continue;
+    let v = t.slice(eq + 1).trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    out.set(t.slice(0, eq).trim(), v);
+  }
+  return out;
+}
+
+/** Every profile folder's `.env`, merged; the root's first, a named profile's over it. */
+function readVault(orchestration) {
+  const vault = new Map();
+  for (const profile of Object.values(orchestration.profiles)) {
+    const file = join(profile.dir, '.env');
+    if (!existsSync(file)) continue;
+    for (const [k, v] of parseDotenv(readFileSync(file, 'utf8'))) vault.set(k, v);
+  }
+  return vault;
+}
+
+/** An orchestration value as the loop's state: the persisted half plus an empty runtime half. */
+export function stateOf(orchestration) {
+  return { ...orchestration, runtime: emptyRuntime() };
+}
+
+/**
+ * `load(root)` — our folder, strict: an unknown key, a bad value, or a missing
+ * secret ref refuses the load and names the file and key.
+ *
+ * A credential VALUE a person pasted into `config.yaml` or
+ * `webhook_subscriptions.json` is not refused: the codec has already moved it
+ * into its vault under a `${NAME}` reference, and one save writes that vault
+ * into `.env` and the file back with the ref (§1 rule 3 — the folder converges
+ * to its own invariant on first contact). The value never crosses the wire;
+ * it is read back out of `.env` like every other secret.
+ */
+export async function load(root) {
+  const { orchestration, vault_keys } = await through((d) => d.orchestrationLoad({ root }));
+  let vault = readVault(orchestration);
+  if (vault_keys.some((k) => !vault.has(k))) {
+    await through((d) => d.orchestrationSave({ root, orchestration }));
+    vault = readVault(orchestration);
+    const missing = vault_keys.filter((k) => !vault.has(k));
+    if (missing.length) throw new Error(`${root}: ${missing.join(', ')} referenced but not in .env after normalization`);
+  }
+  return { state: stateOf(orchestration), vault };
+}
+
+/** `save(state, root)` — our folder, canonical and byte-stable: an artifact whose record has not changed keeps its bytes. */
+export async function save(state, root = state.root) {
+  await through((d) => d.orchestrationSave({ root, orchestration: persistedView(state) }));
+}
+
+/** Another harness's home as a state value (no secret value; `vault_keys` names the `.env` keys it would need). */
+export async function compile(from, home) {
+  const { orchestration, vault_keys } = await through((d) => d.orchestrationCompile({ from, home }));
+  return { state: stateOf(orchestration), vault_keys };
+}
+
+/** Another harness's home becomes our folder at `into`, credentials along. */
+export function importFrom(from, home, into) {
+  return through((d) => d.orchestrationImport({ from, home, into }));
+}
+
+/** Our folder at `root` becomes another harness's home at `dest`, credentials along. */
+export function exportTo(to, root, dest) {
+  return through((d) => d.orchestrationExport({ to, root, dest }));
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volter/supercode-orchestrator",
+  "version": "0.4.4",
+  "type": "module",
+  "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs"
+    },
+    "./bin": "./bin/orchestrator.mjs",
+    "./apply": {
+      "types": "./apply/index.d.ts",
+      "import": "./apply/index.mjs"
+    },
+    "./apply/doors": {
+      "types": "./apply/doors.d.ts",
+      "import": "./apply/doors.mjs"
+    }
+  },
+  "types": "./index.d.ts",
+  "scripts": {
+    "generate-types": "node scripts/generate-types.mjs",
+    "check-types": "node scripts/generate-types.mjs --check",
+    "test": "npm run check-types && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "@volter/supercode-harness-sdk": "^0.3.41"
+  },
+  "devDependencies": {
+    "@chat-adapter/state-memory": "4.39.0",
+    "chat": "4.39.0"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "license": "MIT OR Apache-2.0",
+  "bin": {
+    "supercode-orchestrator": "./bin/orchestrator.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "*.d.ts",
+    "bin",
+    "mcp",
+    "adapters",
+    "apply",
+    "README.md"
+  ]
+}