@volter/supercode-orchestrator 0.4.4

package/hermes-home.mjs

@@ -0,0 +1,264 @@
+// A home is a Hermes home (docs/plans/hermes-compat.md): where the workers have a native form it is the
+// source and Hermes's form shadows it. This module brings a home's files into that shape before the
+// folder is loaded, so a Hermes home is adopted as it stands and a home the orchestrator ran opens
+// under Hermes.
+//
+//   profileDirs(root)     the root (the default profile) and each `profiles/<name>/`, dot folders skipped
+//   adoptPersona(dir)     `AGENTS.md` the persona, `SOUL.md` a link to it, `CLAUDE.md` `@AGENTS.md` (row 2)
+//   adoptSkills(dir)      `.agents/skills/<name>/` the source, Hermes reading it through its own
+//                         `skills.external_dirs`; the skills Hermes manages stay in `skills/` (row 3)
+//   skillSources(dir)     every skill a profile has, by name, and where it lives
+//   adoptMcp(dir)         `.mcp.json` the source, `config.yaml`'s `mcp_servers:` its shadow, an edit on
+//                         either side carried to the other against the last state written (row 4)
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { parseDocument } from 'yaml';
+
+/** Claude Code's bridge to `AGENTS.md`, its own documented form. */
+export const CLAUDE_BRIDGE = '@AGENTS.md\n';
+
+/** The root and each named profile's folder, as Hermes and the folder codec both lay them out. */
+export function profileDirs(root) {
+  const dirs = [resolve(root)];
+  const named = join(root, 'profiles');
+  if (existsSync(named)) {
+    for (const entry of readdirSync(named, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const dir = join(named, entry.name);
+      if (entry.isDirectory() || (entry.isSymbolicLink() && existsSync(dir))) dirs.push(dir);
+    }
+  }
+  return dirs;
+}
+
+const kind = (path) => { try { const s = lstatSync(path); return s.isSymbolicLink() ? 'link' : s.isFile() ? 'file' : 'other'; } catch { return 'none'; } };
+
+/** Make `path` a symlink to `target` (a name relative to its folder), replacing a file or a stale link. */
+export function linkTo(path, target) {
+  if (kind(path) === 'link' && readlinkSync(path) === target) return false;
+  rmSync(path, { force: true });
+  symlinkSync(target, path);
+  return true;
+}
+
+/**
+ * The persona's two forms in one folder. `AGENTS.md` is the source; `SOUL.md` is a link to it, so
+ * Hermes reads the same file (and never writes its default persona through a dangling link, since
+ * `AGENTS.md` exists before any Hermes call); `CLAUDE.md` is Claude Code's `@AGENTS.md`. A Hermes home
+ * adopted here keeps its persona: a `SOUL.md` with no `AGENTS.md` becomes `AGENTS.md`. Two different
+ * files are two personas, and the adoption refuses rather than choose.
+ */
+export function adoptPersona(dir) {
+  const agents = join(dir, 'AGENTS.md');
+  const soul = join(dir, 'SOUL.md');
+  const claude = join(dir, 'CLAUDE.md');
+  const changed = [];
+  const soulKind = kind(soul);
+  if (kind(agents) === 'none') {
+    if (soulKind === 'file') { renameSync(soul, agents); changed.push('SOUL.md -> AGENTS.md'); } else return changed;
+  } else if (soulKind === 'file' && readFileSync(soul, 'utf8') !== readFileSync(agents, 'utf8')) {
+    throw new Error(`${dir}: SOUL.md and AGENTS.md are two different personas; keep one (AGENTS.md is the source, SOUL.md its link)`);
+  }
+  if (linkTo(soul, 'AGENTS.md')) changed.push('SOUL.md -> link');
+  if (kind(claude) === 'none') { writeFileSync(claude, CLAUDE_BRIDGE); changed.push('CLAUDE.md'); }
+  return changed;
+}
+
+/** The workers' form of the skills, relative to a profile folder; Hermes reads it through `external_dirs`. */
+export const AGENTS_SKILLS = '.agents/skills';
+
+/**
+ * The skills Hermes manages, by name: its bundled skills (`skills/.bundled_manifest`, `name:hash` lines)
+ * and its hub installs (`skills/.hub/lock.json` `installed`). They have no worker-native origin, so they
+ * stay where Hermes keeps them and its own updates keep working.
+ */
+export function managedSkills(dir) {
+  const names = new Set();
+  try {
+    for (const line of readFileSync(join(dir, 'skills', '.bundled_manifest'), 'utf8').split('\n')) {
+      const name = line.split(':')[0].trim();
+      if (name) names.add(name);
+    }
+  } catch { /* none */ }
+  try {
+    for (const name of Object.keys(JSON.parse(readFileSync(join(dir, 'skills', '.hub', 'lock.json'), 'utf8')).installed ?? {})) names.add(name);
+  } catch { /* none */ }
+  return names;
+}
+
+/** The skill folders under Hermes's `skills/`, flat or in a category: `[{ name, path }]` (path relative to `skills/`). */
+function hermesSkillDirs(dir) {
+  const base = join(dir, 'skills');
+  const out = [];
+  if (!existsSync(base)) return out;
+  for (const top of readdirSync(base, { withFileTypes: true })) {
+    if (top.name.startsWith('.') || !top.isDirectory()) continue;
+    if (existsSync(join(base, top.name, 'SKILL.md'))) { out.push({ name: top.name, path: top.name }); continue; }
+    for (const inner of readdirSync(join(base, top.name), { withFileTypes: true })) {
+      if (!inner.name.startsWith('.') && inner.isDirectory() && existsSync(join(base, top.name, inner.name, 'SKILL.md'))) {
+        out.push({ name: inner.name, path: `${top.name}/${inner.name}` });
+      }
+    }
+  }
+  return out;
+}
+
+/** Two skill folders with the same files and bytes. */
+function sameTree(a, b) {
+  const list = (d) => readdirSync(d, { recursive: true, withFileTypes: true }).filter((e) => e.isFile()).map((e) => relative(d, join(e.parentPath ?? e.path, e.name))).sort();
+  const la = list(a);
+  const lb = list(b);
+  return la.length === lb.length && la.every((f, i) => f === lb[i] && readFileSync(join(a, f)).equals(readFileSync(join(b, f))));
+}
+
+/**
+ * The skills in both forms in one profile folder. Every skill Hermes does not manage lives in
+ * `.agents/skills/<name>/`: one an existing home keeps in `skills/` (a skill the agent wrote, a family the
+ * repository does not commit) is moved there, and one Hermes's agent writes later is moved on the next
+ * load. Hermes reads that folder through its own `skills.external_dirs`, added to the profile's
+ * `config.yaml`. A name two different skills share refuses by name, as does a name the workers' form
+ * shares with a skill Hermes manages, which Hermes itself could not resolve.
+ */
+export function adoptSkills(dir) {
+  const changed = [];
+  const managed = managedSkills(dir);
+  const target = join(dir, AGENTS_SKILLS);
+  for (const { name, path } of hermesSkillDirs(dir)) {
+    if (managed.has(name)) continue;
+    const from = join(dir, 'skills', path);
+    const to = join(target, name);
+    if (existsSync(to)) {
+      if (!sameTree(from, to)) throw new Error(`${dir}: two different skills are named ${name} (skills/${path} and ${AGENTS_SKILLS}/${name}); rename one`);
+      rmSync(from, { recursive: true, force: true });
+      changed.push(`skills/${path}: the same skill as ${AGENTS_SKILLS}/${name}, removed`);
+    } else {
+      mkdirSync(target, { recursive: true });
+      renameSync(from, to);
+      changed.push(`skills/${path} -> ${AGENTS_SKILLS}/${name}`);
+    }
+    if (path.includes('/')) {
+      // a category left with nothing but its description goes with it
+      const category = join(dir, 'skills', path.split('/')[0]);
+      const rest = readdirSync(category).filter((f) => f !== 'DESCRIPTION.md');
+      if (!rest.length) rmSync(category, { recursive: true, force: true });
+    }
+  }
+  if (existsSync(target)) {
+    for (const entry of readdirSync(target)) {
+      if (managed.has(entry)) throw new Error(`${dir}: ${AGENTS_SKILLS}/${entry} has the name of a skill Hermes manages; rename it`);
+    }
+    if (addExternalDir(dir)) changed.push(`config.yaml: skills.external_dirs += ${AGENTS_SKILLS}`);
+  }
+  return changed;
+}
+
+/** Add `.agents/skills` to the profile's `skills.external_dirs`, keeping the rest of `config.yaml` as it is. */
+function addExternalDir(dir) {
+  const file = join(dir, 'config.yaml');
+  const doc = parseDocument(existsSync(file) ? readFileSync(file, 'utf8') : '');
+  const current = doc.getIn(['skills', 'external_dirs'])?.toJSON?.() ?? doc.getIn(['skills', 'external_dirs']) ?? [];
+  const list = Array.isArray(current) ? current : [current];
+  if (list.includes(AGENTS_SKILLS)) return false;
+  doc.setIn(['skills', 'external_dirs'], [...list, AGENTS_SKILLS]);
+  writeFileSync(file, String(doc));
+  return true;
+}
+
+/** Every skill a profile has, by name: the workers' form first, then the skills Hermes manages. */
+export function skillSources(dir) {
+  const out = new Map();
+  const target = join(dir, AGENTS_SKILLS);
+  if (existsSync(target)) {
+    for (const entry of readdirSync(target)) if (existsSync(join(target, entry, 'SKILL.md'))) out.set(entry, join(target, entry));
+  }
+  const managed = managedSkills(dir);
+  for (const { name, path } of hermesSkillDirs(dir)) if (managed.has(name) && !out.has(name)) out.set(name, join(dir, 'skills', path));
+  return out;
+}
+
+/** A server's fields both forms carry: stdio `command`/`args`/`env`, or remote `url`/`headers`. */
+const MCP_FIELDS = ['command', 'args', 'env', 'url', 'headers'];
+
+/** One `.mcp.json` server from a Hermes `mcp_servers` entry (Hermes's other keys stay in `config.yaml`). */
+function nativeServer(entry) {
+  const out = {};
+  for (const field of MCP_FIELDS) if (entry?.[field] !== undefined && entry[field] !== null) out[field] = entry[field];
+  if (out.url) out.type = 'http';
+  return out;
+}
+
+const canon = (value) => JSON.stringify(value, (k, v) => (v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.keys(v).sort().map((key) => [key, v[key]])) : v));
+
+/** The applier-style base: what this home's two MCP forms held when last written, outside the home. */
+function baseFile(dir, env = process.env) {
+  const root = join(env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'supercode', 'hermes-home');
+  return join(root, `${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 16)}.json`);
+}
+
+/**
+ * MCP servers in both forms in one profile folder. The source is `.mcp.json` (`mcpServers`, the form
+ * Claude Code and the other workers read); the shadow is `config.yaml`'s `mcp_servers:`, where Hermes
+ * reads them, each entry keeping any key only Hermes has (a timeout, a sampling block). Hermes can edit
+ * its form while it runs the home (`hermes mcp add`), so both are compared with the last state written:
+ * an edit on one side is carried to the other, and two different edits refuse by name. The
+ * orchestrator's own server is never written to either form; it is mounted per session.
+ */
+export function adoptMcp(dir, env = process.env) {
+  const jsonFile = join(dir, '.mcp.json');
+  const yamlFile = join(dir, 'config.yaml');
+  const doc = parseDocument(existsSync(yamlFile) ? readFileSync(yamlFile, 'utf8') : '');
+  const hermes = doc.getIn(['mcp_servers'])?.toJSON?.() ?? {};
+  const native = existsSync(jsonFile) ? (JSON.parse(readFileSync(jsonFile, 'utf8')).mcpServers ?? {}) : {};
+  const shadow = Object.fromEntries(Object.entries(hermes).map(([name, entry]) => [name, nativeServer(entry)]));
+  const source = Object.fromEntries(Object.entries(native).map(([name, entry]) => [name, nativeServer(entry)]));
+  const file = baseFile(dir, env);
+  let base = null;
+  try { base = JSON.parse(readFileSync(file, 'utf8')).mcp ?? null; } catch { /* first sync */ }
+  const sourceChanged = base === null ? Object.keys(source).length > 0 : canon(source) !== canon(base);
+  const shadowChanged = base === null ? Object.keys(shadow).length > 0 : canon(shadow) !== canon(base);
+  let want = source;
+  if (sourceChanged && shadowChanged && canon(source) !== canon(shadow)) {
+    throw new Error(`${dir}: MCP servers were changed in both .mcp.json and config.yaml mcp_servers since they were last in step; make them agree`);
+  }
+  if (shadowChanged && !sourceChanged) want = shadow;
+  const changed = [];
+  if (canon(source) !== canon(want)) {
+    const out = existsSync(jsonFile) ? JSON.parse(readFileSync(jsonFile, 'utf8')) : {};
+    out.mcpServers = Object.fromEntries(Object.entries(want).map(([name, entry]) => [name, { ...(native[name] ?? {}), ...entry }]));
+    writeFileSync(jsonFile, `${JSON.stringify(out, null, 2)}\n`);
+    changed.push('.mcp.json: from config.yaml mcp_servers');
+  }
+  if (canon(shadow) !== canon(want)) {
+    const next = {};
+    for (const [name, entry] of Object.entries(want)) {
+      const kept = { ...(hermes[name] ?? {}) };
+      for (const field of MCP_FIELDS) delete kept[field];
+      const { type, ...fields } = entry;
+      next[name] = { ...kept, ...fields };
+    }
+    if (Object.keys(next).length) doc.setIn(['mcp_servers'], next); else doc.deleteIn(['mcp_servers']);
+    writeFileSync(yamlFile, String(doc));
+    changed.push('config.yaml: mcp_servers from .mcp.json');
+  }
+  if (base === null || canon(base) !== canon(want)) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ home: resolve(dir), mcp: want }));
+  }
+  return changed;
+}
+
+/** The profile's MCP servers in the workers' form (`.mcp.json` `mcpServers`), or `{}`. */
+export function mcpServers(dir) {
+  try { return JSON.parse(readFileSync(join(dir, '.mcp.json'), 'utf8')).mcpServers ?? {}; } catch { return {}; }
+}
+
+/** Bring every profile folder of a home into shape before it is loaded. */
+export function adoptHome(root) {
+  const report = [];
+  for (const dir of profileDirs(root)) {
+    for (const change of [...adoptPersona(dir), ...adoptSkills(dir), ...adoptMcp(dir)]) report.push(`${dir}: ${change}`);
+  }
+  return report;
+}

package/hermes-locks.mjs

@@ -0,0 +1,188 @@
+// Hermes's two runtime locks, held the way Hermes holds them, so one home is served by one runtime and
+// one bot token by one gateway (docs/plans/hermes-compat.md, row 1; pinned Hermes gateway/status.py).
+//
+//   the home's gateway lock   `<home>/gateway.lock`, an exclusive `flock` the live gateway holds, with its
+//                             pid record as the file's content; Hermes refuses to start while anyone holds it
+//   a token's scoped lock     `<lock dir>/<scope>-<sha256(identity)[:16]>.lock`, an O_EXCL file whose
+//                             record names the holder; Hermes's adapter refuses a token a live gateway holds
+//
+// Hermes calls a holder live when its pid exists and its command line is a gateway's (`hermes-gateway`,
+// `hermes gateway run`, `gateway/run.py`). The daemon runs as `hermes-gateway` (bin/orchestrator.mjs), so
+// Hermes reads the orchestrator's locks as a gateway's, which they are.
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+/** Hermes's gateway kind, the `kind` of every record it writes. */
+export const GATEWAY_KIND = 'hermes-gateway';
+
+/** The scope Hermes's adapter locks for each platform, and which credential it locks by. */
+export const TOKEN_SCOPES = Object.freeze({
+  discord: { scope: 'discord-bot-token', option: 'botToken' },
+  telegram: { scope: 'telegram-bot-token', option: 'botToken' },
+  slack: { scope: 'slack-app-token', option: 'appToken' },
+});
+
+/** Hermes's `_get_lock_dir`: `HERMES_GATEWAY_LOCK_DIR`, else `$XDG_STATE_HOME/hermes/gateway-locks`. */
+export function tokenLockDir(env = process.env) {
+  if (env.HERMES_GATEWAY_LOCK_DIR) return env.HERMES_GATEWAY_LOCK_DIR;
+  return join(env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'hermes', 'gateway-locks');
+}
+
+const scopeHash = (identity) => createHash('sha256').update(String(identity)).digest('hex').slice(0, 16);
+
+/** Hermes's `_gateway_command_subcommand(...) == "run"`: a command line that is a gateway's. */
+export function looksLikeGateway(command) {
+  if (!command) return false;
+  const tokens = command.split(/\s+/).map((t) => t.replace(/^["']|["']$/g, '').replaceAll('\\', '/').toLowerCase()).filter(Boolean);
+  for (const t of tokens) {
+    if (t === 'gateway/run.py' || t.endsWith('/gateway/run.py')) return true;
+    const base = t.split('/').pop();
+    if (base === 'hermes-gateway' || base === 'hermes-gateway.exe') return true;
+  }
+  const joined = tokens.join(' ');
+  if (!(joined.includes('hermes_cli.main') || joined.includes('hermes_cli/main.py') || tokens.some((t) => ['hermes', 'hermes.exe'].includes(t.split('/').pop())))) return false;
+  const filtered = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    if (tokens[i] === '--profile' || tokens[i] === '-p') { i += 1; continue; }
+    if (tokens[i].startsWith('--profile=') || tokens[i].startsWith('-p=')) continue;
+    filtered.push(tokens[i]);
+  }
+  const at = filtered.indexOf('gateway');
+  return at >= 0 && (at + 1 >= filtered.length || filtered[at + 1] === 'run');
+}
+
+function commandOf(pid) {
+  const run = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: 5000 });
+  return run.status === 0 ? run.stdout.trim() || null : null;
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; }
+}
+
+/** Linux's `/proc/<pid>/stat` field 22, as Hermes records it; null where there is no /proc. */
+function startTime(pid) {
+  try { return Number(readFileSync(`/proc/${pid}/stat`, 'utf8').split(' ')[21]); } catch { return null; }
+}
+
+/** The record Hermes's `_build_pid_record` writes, for this process serving `home`. */
+export function pidRecord(home) {
+  return { pid: process.pid, kind: GATEWAY_KIND, argv: [process.argv0, ...process.argv.slice(1)], start_time: startTime(process.pid), hermes_home: resolve(home) };
+}
+
+/** Hermes's stale test for a record another process wrote. */
+function holderLive(record) {
+  const pid = Number(record?.pid);
+  if (!pidAlive(pid)) return false;
+  const now = startTime(pid);
+  if (record.start_time != null && now != null && now !== record.start_time) return false;
+  const command = commandOf(pid);
+  return command === null || looksLikeGateway(command);
+}
+
+/**
+ * Take a token's scoped lock (Hermes's `acquire_scoped_lock`). Answers `{ ok: true }`, or
+ * `{ ok: false, holder }` naming the live gateway that holds it.
+ */
+export function acquireTokenLock({ scope, identity, home, platform, env = process.env }) {
+  const dir = tokenLockDir(env);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${scope}-${scopeHash(identity)}.lock`);
+  const record = { ...pidRecord(home), scope, identity_hash: scopeHash(identity), metadata: { platform }, updated_at: new Date().toISOString() };
+  let existing = null;
+  try { existing = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') existing = {}; }
+  if (existing) {
+    if (Number(existing.pid) === process.pid) { writeRecord(file, record, 'w'); return { ok: true }; }
+    if (holderLive(existing)) return { ok: false, holder: existing };
+    // stale: claimed by an atomic rename, as Hermes does, so of two racing starters one wins
+    try { renameSync(file, `${file}.stale`); rmSync(`${file}.stale`, { force: true }); } catch { /* another racer took it */ }
+  }
+  try { writeRecord(file, record, 'wx'); } catch (error) {
+    if (error.code === 'EEXIST') { let holder = null; try { holder = JSON.parse(readFileSync(file, 'utf8')); } catch { /* unreadable */ } return { ok: false, holder }; }
+    throw error;
+  }
+  return { ok: true };
+}
+
+function writeRecord(file, record, flag) {
+  const fd = openSync(file, flag, 0o644);
+  try { writeSync(fd, JSON.stringify(record)); } finally { closeSync(fd); }
+}
+
+/** Release a token's scoped lock this process holds (Hermes's `release_scoped_lock`). */
+export function releaseTokenLock({ scope, identity, env = process.env }) {
+  const file = join(tokenLockDir(env), `${scope}-${scopeHash(identity)}.lock`);
+  try { if (Number(JSON.parse(readFileSync(file, 'utf8')).pid) === process.pid) unlinkSync(file); } catch { /* gone */ }
+}
+
+// The flock itself: Node has none, so a small Python child takes it, writes Hermes's record naming
+// this process, and holds it until its stdin closes, which is this process exiting by any path.
+const HOLDER = `
+import fcntl, json, os, sys
+path, record = sys.argv[1], json.loads(sys.argv[2])
+handle = open(path, "a+", encoding="utf-8")
+try:
+    fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+except OSError:
+    handle.seek(0)
+    sys.stdout.write("held " + handle.read().strip().replace("\\n", " ") + "\\n"); sys.stdout.flush(); sys.exit(3)
+handle.seek(0); handle.truncate(); json.dump(record, handle); handle.flush(); os.fsync(handle.fileno())
+sys.stdout.write("ok\\n"); sys.stdout.flush()
+sys.stdin.read()
+`;
+
+/**
+ * Hold `<home>/gateway.lock` for this process. Resolves `{ release }`; rejects, naming the holder,
+ * when a Hermes gateway (or another orchestrator) already serves the home.
+ */
+export function holdGatewayLock(home, { python = 'python3' } = {}) {
+  return holdFileLock(join(resolve(home), 'gateway.lock'), home, { python, what: `${resolve(home)} is served by`, tail: 'one runtime serves a home at a time' });
+}
+
+/**
+ * Hold the board's one dispatcher lock, `<root>/kanban/.dispatcher.lock` (Hermes's
+ * `_acquire_singleton_lock`, which every Hermes gateway takes before it dispatches). Resolves
+ * `{ release }`; rejects, naming the holder, when another dispatcher holds it.
+ */
+export function holdDispatcherLock(root, { python = 'python3' } = {}) {
+  const path = join(resolve(root), 'kanban', '.dispatcher.lock');
+  mkdirSync(join(resolve(root), 'kanban'), { recursive: true });
+  return holdFileLock(path, root, { python, what: `the board at ${resolve(root)} is dispatched by`, tail: 'one dispatcher serves a board' });
+}
+
+function holdFileLock(path, home, { python, what, tail }) {
+  return new Promise((done, fail) => {
+    let child;
+    try {
+      child = spawn(python, ['-c', HOLDER, path, JSON.stringify(pidRecord(home))], { stdio: ['pipe', 'pipe', 'inherit'] });
+    } catch (error) { fail(new Error(`cannot hold ${path}: ${error.message}`)); return; }
+    let out = '';
+    child.on('error', (error) => fail(new Error(`cannot hold ${path} (${python}: ${error.message}); a home is served by one runtime, and this one could not claim it`)));
+    child.stdout.on('data', (chunk) => {
+      out += chunk;
+      if (!out.includes('\n')) return;
+      const line = out.split('\n')[0];
+      if (line === 'ok') {
+        done({ release: () => { try { child.stdin.end(); } catch { /* gone */ } } });
+      } else {
+        let holder = null;
+        try { holder = JSON.parse(line.slice('held '.length)); } catch { /* unreadable record */ }
+        fail(new Error(`${what} ${holder?.pid ? `pid ${holder.pid} (${(holder.argv ?? []).join(' ') || holder.kind || 'a gateway'})` : 'another runtime'}; ${tail}`));
+      }
+    });
+    child.on('exit', (code) => { if (!out.includes('\n')) fail(new Error(`the lock holder for ${path} exited ${code} before answering`)); });
+  });
+}
+
+/** Whether a Hermes gateway (or anything) holds `<home>/gateway.lock` now, without taking it. */
+export function gatewayLockHeld(home, { python = 'python3' } = {}) {
+  const path = join(resolve(home), 'gateway.lock');
+  if (!existsSync(path)) return false;
+  const probe = spawnSync(python, ['-c', 'import fcntl,sys\nh=open(sys.argv[1],"a+")\ntry:\n    fcntl.flock(h.fileno(), fcntl.LOCK_EX|fcntl.LOCK_NB)\nexcept OSError:\n    sys.exit(3)\n', path], { timeout: 5000 });
+  return probe.status === 3;
+}
+

package/hosted.mjs

@@ -0,0 +1,81 @@
+// Host integration: the orchestrator owns time and durable fires; a trusted
+// application executes each task through its existing conversation/action door.
+import { connect } from 'node:net';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { socketPathFor } from './mcp/server.mjs';
+import { leaseIsHere } from './lease.mjs';
+
+export function callOperator({ root, profile = 'default', op, args = {}, timeoutMs = 30_000 }) {
+  return new Promise((resolve, reject) => {
+    const socket = connect(socketPathFor(root));
+    let buffer = '', settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true; socket.destroy();
+      error ? reject(error) : resolve(value);
+    };
+    socket.setTimeout(timeoutMs, () => finish(new Error('Orchestrator request timed out')));
+    socket.setEncoding('utf8');
+    socket.on('error', (e) => finish(e));
+    socket.on('connect', () => socket.write(JSON.stringify({ op, profile, args }) + '\n'));
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      if (buffer.length > 4 * 1024 * 1024) return finish(new Error('Orchestrator response too large'));
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) return;
+      try {
+        const reply = JSON.parse(buffer.slice(0, newline));
+        if (reply.ok !== true) throw new Error(reply.error || 'Orchestrator refused the request');
+        finish(null, reply.result);
+      } catch (error) { finish(error); }
+    });
+    socket.on('close', () => finish(new Error('Orchestrator closed before confirming the request')));
+  });
+}
+
+export function httpJobExecutor({ url, tokenFile, root, timeoutMs = 30_000 }) {
+  const endpoint = new URL(url);
+  if (endpoint.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(endpoint.hostname) || endpoint.username || endpoint.password)
+    throw new Error('A hosted executor must use a loopback HTTP endpoint');
+  if (!tokenFile) throw new Error('A hosted executor token file is required');
+  const token = readFileSync(tokenFile, 'utf8').trim();
+  if (token.length < 32) throw new Error('The hosted executor token is invalid');
+  return async ({ profile, job, fire }) => {
+    const response = await fetch(endpoint, {
+      method: 'POST', redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ root, profile, job, fire }),
+    });
+    if (!response.ok) {
+      const refusal = await response.json().catch(() => null);
+      throw new Error(typeof refusal?.error === 'string' ? refusal.error.slice(0, 2000) : `Hosted task was not confirmed (HTTP ${response.status})`);
+    }
+    const receipt = await response.json();
+    if (receipt.fire_id !== fire.id || receipt.profile !== profile || receipt.accepted !== true)
+      throw new Error('Hosted task receipt did not match this fire');
+    return receipt;
+  };
+}
+
+/** Stop this package's hosted daemon through its native signal handler. The
+ * daemon retains its own lease until shutdown completes; this never clears it
+ * early or escalates to SIGKILL. A foreign/unhosted owner is refused. */
+export async function stopHostedDaemon({ root, executorUrl, timeoutMs = 30_000 }) {
+  root = resolve(root);
+  let lease;
+  try { lease = JSON.parse(readFileSync(join(root, 'orchestrator.lock'), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return { stopped: true, wasRunning: false }; throw error; }
+  if (!Number.isInteger(lease.pid) || lease.pid <= 0 || resolve(lease.root ?? '') !== root || typeof lease.executor_url !== 'string' || (executorUrl && lease.executor_url !== executorUrl)) throw new Error('Another executor owns this orchestrator home.');
+  // A lease another machine or an earlier boot wrote names no process here: nothing is signalled on its word.
+  if (!leaseIsHere(lease)) return { stopped: true, wasRunning: false };
+  const alive = () => { try { process.kill(lease.pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; throw error; } };
+  if (!alive()) return { stopped: true, wasRunning: false };
+  process.kill(lease.pid, 'SIGTERM');
+  const deadline = Date.now() + timeoutMs;
+  while (alive()) {
+    if (Date.now() >= deadline) throw new Error('The orchestrator has not finished stopping. Its lease and data were preserved.');
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+  return { stopped: true, wasRunning: true };
+}