@volter/supercode-orchestrator 0.4.4

package/hermes-cli.mjs

@@ -0,0 +1,440 @@
+// Hermes's own tools beside a worker (docs/plans/hermes-compat.md row 7). A home is a Hermes home, and the
+// skills it carries call Hermes's CLI (`hermes kanban …`, `hermes cron notepad …`, `hermes cron doctor`)
+// against it, so a worker of any harness runs with `HERMES_HOME` set to its profile's folder and the
+// pinned `hermes` on its `PATH`; and what Hermes's scheduler records about a failed run (its incidents,
+// in `cron/executions.db`) the orchestrator records through Hermes's own function.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseDotenv } from './orchestration.mjs';
+import { locateHermes } from './apply/doors.mjs';
+
+/** Hermes's interpreter over `code`, `payload` on stdin, without blocking the daemon: `{ status, stdout, stderr }`. */
+function python(install, code, payload, env, timeout) {
+  return new Promise((done) => {
+    const child = spawn(install.python, ['-c', code], { cwd: install.source, env, stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '';
+    const timer = setTimeout(() => child.kill('SIGKILL'), timeout);
+    child.stdout.setEncoding('utf8').on('data', (c) => { stdout += c; });
+    child.stderr.setEncoding('utf8').on('data', (c) => { stderr = (stderr + c).slice(-4000); });
+    child.on('error', (error) => { clearTimeout(timer); done({ status: null, stdout, stderr: error.message }); });
+    child.on('close', (status) => { clearTimeout(timer); done({ status, stdout, stderr }); });
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+let located;
+/** The pinned Hermes on this daemon's `PATH`: `{ bin, python, source }`, or null when there is none. */
+export function hermesInstall() {
+  if (located !== undefined) return located;
+  try {
+    const which = spawnSync('sh', ['-c', 'command -v hermes'], { encoding: 'utf8' }).stdout.trim();
+    located = which ? { bin: dirname(which), ...locateHermes() } : null;
+  } catch {
+    located = null;
+  }
+  return located;
+}
+
+/** The environment a non-Hermes worker adds for Hermes's CLI: its profile's home, and `hermes` on `PATH`. */
+export function hermesToolEnv(profileDir) {
+  const install = hermesInstall();
+  const env = { HERMES_HOME: profileDir };
+  if (install?.bin) env.PATH = `${install.bin}:${process.env.PATH ?? ''}`;
+  return env;
+}
+
+/**
+ * Record a failed run as Hermes's scheduler does: `cron.incidents.upsert_incident`, one incident per job
+ * and error signature, in the profile's `cron/executions.db`. Answers the incident id, or null (and why)
+ * when Hermes is not installed or refused.
+ */
+export function recordIncident(profileDir, { job_id, job_name = null, error }) {
+  const install = hermesInstall();
+  if (!install?.python) return { id: null, why: 'no Hermes install on PATH' };
+  const code = 'import json,sys\nfrom cron.incidents import upsert_incident\na=json.loads(sys.stdin.read())\nprint(json.dumps(upsert_incident(a["job_id"], a["error"], job_name=a.get("job_name"))))';
+  const run = spawnSync(install.python, ['-c', code], {
+    input: JSON.stringify({ job_id, job_name, error: String(error ?? 'failed') }),
+    encoding: 'utf8', timeout: 30_000, cwd: install.source,
+    env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '', HERMES_HOME: profileDir, PYTHONPATH: install.source },
+  });
+  if (run.status !== 0) return { id: null, why: (run.stderr || run.error?.message || '').trim().slice(-300) };
+  const [id] = JSON.parse(run.stdout.trim().split('\n').pop());
+  return { id };
+}
+
+// Access through Hermes's own pairing store and writers (docs/plans/hermes-compat.md row 8): a code is
+// issued and approved by `gateway.pairing.PairingStore` (salted hashes, its expiry, rate limit and
+// lockout), an approval mirrored into the platform's allowlist as Hermes mirrors it; an allowlist entry is
+// `<PLATFORM>_ALLOWED_USERS` in the profile's `.env` (`hermes_cli.config.save_env_value`); an admin is the
+// platform's `extra.allow_admin_from` in `config.yaml` (`save_config`).
+const ACCESS_OPS = `
+import json, os, sys
+a = json.loads(sys.stdin.read()); op = a["op"]
+from gateway.pairing import PairingStore, _read_allowlist_env, _sync_allowlist_remove, _allowlist_env_for_platform
+store = PairingStore()
+def ids(v): return [x.strip() for x in (v or "").split(",") if x.strip()]
+out = None
+if op == "issue":
+    # Hermes's gateway: a rate-limited sender is answered with nothing; a refused code with the busy line,
+    # its rate limit recorded so the next messages are silent
+    if store._is_rate_limited(a["platform"], a["user_id"]):
+        out = {"silent": True}
+    else:
+        code = store.generate_code(a["platform"], a["user_id"], a.get("user_name") or "")
+        if not code:
+            store._record_rate_limit(a["platform"], a["user_id"])
+        out = {"code": code}
+elif op == "approve":
+    for p in a["platforms"]:
+        got = store.approve_code(p, a["code"])
+        if got:
+            out = {"platform": p, **got}
+            break
+elif op == "pending":
+    out = store.list_pending()
+elif op in ("allow", "revoke"):
+    var = _allowlist_env_for_platform(a["platform"]) or (a["platform"].upper() + "_ALLOWED_USERS")
+    current = ids(_read_allowlist_env(var))
+    if op == "allow":
+        if a["user_id"] not in current:
+            from hermes_cli.config import save_env_value
+            save_env_value(var, ",".join(current + [a["user_id"]]))
+    else:
+        store.revoke(a["platform"], a["user_id"])
+        _sync_allowlist_remove(a["platform"], a["user_id"])
+    out = True
+elif op in ("admin_add", "admin_remove"):
+    from hermes_cli.config import load_config, save_config
+    cfg = load_config()
+    extra = cfg.setdefault("platforms", {}).setdefault(a["platform"], {}).setdefault("extra", {})
+    admins = [str(x) for x in (extra.get("allow_admin_from") or [])]
+    if op == "admin_add" and a["user_id"] not in admins: admins.append(a["user_id"])
+    if op == "admin_remove": admins = [x for x in admins if x != a["user_id"]]
+    extra["allow_admin_from"] = admins
+    save_config(cfg)
+    out = True
+print("@@access@@" + json.dumps(out))
+`;
+
+/**
+ * One access operation through Hermes's own functions against a profile's home: `issue` (answers
+ * `{ code }`, `{ code: null }` when Hermes refuses one, or `{ silent: true }` for a rate-limited sender), `approve` (answers
+ * `{ platform, user_id, user_name }` or null), `pending`, `allow`, `revoke`, `admin_add`, `admin_remove`.
+ * Throws when Hermes is not installed: access lives in Hermes's stores.
+ */
+export function hermesAccess(profileDir, op, args = {}) {
+  const install = hermesInstall();
+  if (!install?.python) throw new Error(`access ${op} needs Hermes's pairing store and writers, and no Hermes is installed on PATH`);
+  const envFile = join(profileDir, '.env');
+  const dotenv = existsSync(envFile) ? Object.fromEntries(parseDotenv(readFileSync(envFile, 'utf8'))) : {};
+  const run = spawnSync(install.python, ['-c', ACCESS_OPS], {
+    input: JSON.stringify({ op, ...args }), encoding: 'utf8', timeout: 30_000, cwd: install.source,
+    env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '', ...dotenv, HERMES_HOME: profileDir, PYTHONPATH: install.source },
+  });
+  const line = (run.stdout ?? '').split('\n').find((l) => l.startsWith('@@access@@'));
+  if (!line) throw new Error(`Hermes answered nothing for access ${op}: ${(run.stderr || run.error?.message || '').trim().slice(-300)}`);
+  return JSON.parse(line.slice('@@access@@'.length));
+}
+
+// A worker's transcript mirrored into the home's Hermes session store (docs/plans/hermes-compat.md row 11),
+// through Hermes's own `SessionDB`: the session row (`ensure_session`, the entry's session id, its chat and
+// origin, `model_config._supercode_mirror` naming the worker's own session and how many rows the mirror
+// wrote) and its messages (`replace_messages`, one atomic rewrite under Hermes's turn lease), so
+// `hermes sessions` lists and resumes the conversation. A row Hermes has written to since the last mirror
+// (its message count past the mirror's) is Hermes continuing the conversation: the mirror never rewrites
+// it, and the worker's next start takes Hermes's turns over (the loop's `continueFromHermes`).
+const MIRROR = `
+import json, sys
+a = json.loads(sys.stdin.read()); op = a["op"]
+from hermes_state import SessionDB
+db = SessionDB()
+def mark(row):
+    try: return (json.loads(row.get("model_config") or "{}") or {}).get("_supercode_mirror")
+    except Exception: return None
+def config(row):
+    try: return json.loads(row.get("model_config") or "{}") or {}
+    except Exception: return {}
+row = db.get_session(a["id"])
+m = mark(row) if row is not None else None
+ahead = row is not None and (m is None or (m.get("messages") is not None and (row.get("message_count") or 0) > m["messages"]))
+out = None
+if op == "state":
+    out = {"exists": row is not None, "ahead": ahead, "messages": row.get("message_count") if row else None}
+elif op == "seal":
+    if row is not None:
+        cfg = config(row); cfg["_supercode_mirror"] = {**(m or {}), "messages": row.get("message_count") or 0, "continued_as": a["continued_as"]}
+        db.update_session_meta(a["id"], json.dumps(cfg))
+    out = True
+elif ahead:
+    out = {"diverged": row.get("message_count")}
+else:
+    db.ensure_session(a["id"], source=a["source"], model=a.get("model"), model_config=a["model_config"],
+        session_key=a.get("session_key"), chat_id=a.get("chat_id"), chat_type=a.get("chat_type"),
+        thread_id=a.get("thread_id"), user_id=a.get("user_id"), cwd=a.get("cwd"),
+        parent_session_id=a.get("parent"), origin_json=json.dumps(a.get("origin") or {}))
+    db.replace_messages(a["id"], a["messages"], reject_active_turn_lease=True)
+    row = db.get_session(a["id"])
+    cfg = config(row); cfg["_supercode_mirror"] = {**a["model_config"]["_supercode_mirror"], "messages": row.get("message_count") or 0}
+    db.update_session_meta(a["id"], json.dumps(cfg))
+    if a.get("end"): db.end_session(a["id"], a["end"])
+    out = {"mirrored": row.get("message_count") or 0}
+print("@@mirror@@" + json.dumps(out))
+`;
+
+async function runMirror(profileDir, payload) {
+  const install = hermesInstall();
+  if (!install?.python) return { error: 'no Hermes install on PATH' };
+  const run = await python(install, MIRROR, payload, { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '', HERMES_HOME: profileDir, PYTHONPATH: install.source }, 60_000);
+  const line = run.stdout.split('\n').find((l) => l.startsWith('@@mirror@@'));
+  if (!line) return { error: run.stderr.trim().slice(-300) };
+  return { out: JSON.parse(line.slice('@@mirror@@'.length)) };
+}
+
+/**
+ * Whether Hermes has carried a mirrored conversation past its mirror: `{ exists, ahead, messages }`, or
+ * null when Hermes is not installed or unreadable.
+ */
+export async function mirrorState(profileDir, id) {
+  return (await runMirror(profileDir, { op: 'state', id })).out ?? null;
+}
+
+/** A mirror Hermes continued, closed once its turns went on as `continuedAs`: listed no more, never rewritten. */
+export async function sealMirror(profileDir, id, continuedAs) {
+  return (await runMirror(profileDir, { op: 'seal', id, continued_as: continuedAs })).out === true;
+}
+
+/** One Supercode-normalized message (OpenAI chat shape) as a Hermes `messages` row. */
+function hermesMessage(m) {
+  const text = Array.isArray(m.content)
+    ? m.content.map((part) => (typeof part === 'string' ? part : part?.text ?? '')).filter(Boolean).join('\n')
+    : m.content ?? null;
+  const at = Date.parse(m.metadata?.timestamp ?? '');
+  return {
+    role: m.role, content: text,
+    ...(m.tool_calls?.length ? { tool_calls: m.tool_calls } : {}),
+    ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}),
+    ...(m.name ? { tool_name: m.name } : {}),
+    ...(Number.isFinite(at) ? { timestamp: at / 1000 } : {}),
+  };
+}
+
+/**
+ * Mirror a worker session into the profile's Hermes store under `id` (its routing entry's session id).
+ * `binding` supplies the chat; `session` is the worker's transcript as Supercode loaded it; `parent` the
+ * Hermes session it continues. Answers `{ mirrored }` (rows written), `{ diverged }` (Hermes's row is
+ * ahead: nothing written) or `{ mirrored: null, why }`.
+ */
+export async function mirrorSession(profileDir, { id, sessionKey, binding, session, locator = null, parent = null, end = null }) {
+  const key = binding.key ?? {};
+  const got = await runMirror(profileDir, {
+    op: 'mirror', id, parent, end, source: key.platform ?? 'orchestrator', model: session.model ?? null, cwd: session.cwd ?? null,
+    model_config: { _supercode_mirror: { harness: binding.worker?.harness ?? session.source, session_id: session.session_id ?? null, locator, ...(binding.recurrence ? { recurrence: { job_id: binding.recurrence.job_id, kind: binding.recurrence.kind ?? 'cron' } } : {}) } },
+    session_key: sessionKey, chat_id: key.chat_id ?? null, chat_type: key.kind ?? null, thread_id: key.thread_id ?? null, user_id: key.participant_id ?? null,
+    origin: { platform: key.platform ?? null, chat_id: key.chat_id ?? null, chat_type: key.kind ?? null, thread_id: key.thread_id ?? null },
+    messages: (session.messages ?? []).filter((m) => m.role !== 'system').map(hermesMessage),
+  });
+  return got.out ?? { mirrored: null, why: got.error };
+}
+
+// Hermes's own tools against a profile's home (docs/plans/hermes-compat.md row 13): `session_search`,
+// `memory`, `skills_list` and `skill_view` dispatched through Hermes's registry, their handlers given what
+// Hermes's agent gives them (the memory store built as `agent_init` builds it, the current session); the
+// memory snapshot Hermes's agent puts in its system prompt at session start
+// (`format_for_system_prompt`, each enabled store); and Hermes's schedule parser (`cron.jobs.parse_schedule`).
+const HERMES_TOOL = `
+import json, sys
+a = json.loads(sys.stdin.read()); op = a["op"]
+from hermes_cli.config import load_config
+cfg = load_config()
+def memory_store():
+    from tools.memory_tool import MemoryStore, get_builtin_memory_config, get_builtin_memory_store_flags
+    mc = get_builtin_memory_config(cfg); me, ue = get_builtin_memory_store_flags(cfg)
+    if not (me or ue): return None, me, ue
+    store = MemoryStore(memory_char_limit=mc.get("memory_char_limit", 2200), user_char_limit=mc.get("user_char_limit", 1375), memory_enabled=me, user_profile_enabled=ue)
+    store.load_from_disk()
+    return store, me, ue
+if op == "snapshot":
+    store, me, ue = memory_store()
+    blocks = []
+    if store and me: blocks.append(store.format_for_system_prompt("memory"))
+    if store and ue: blocks.append(store.format_for_system_prompt("user"))
+    out = "\\n\\n".join(b for b in blocks if b)
+elif op == "approval":
+    from tools.approval import detect_dangerous_command, _get_cron_approval_mode, _get_single_query_approval_mode, _get_approval_mode
+    danger = detect_dangerous_command(a["command"]) if a.get("command") else (False, None, None)
+    if not danger[0]:
+        out = {"verdict": "allow", "why": None}
+    else:
+        ctx = a.get("context")
+        mode = _get_cron_approval_mode() if ctx == "cron" else _get_single_query_approval_mode() if ctx == "single_query" else ("approve" if _get_approval_mode() == "off" else "ask")
+        out = {"verdict": "allow" if mode == "approve" else ("ask" if mode == "ask" else "deny"), "why": danger[2]}
+        # Hermes's own words to the model for a denial, so it finds another way (tools/approval.py)
+        if out["verdict"] == "deny" and ctx == "cron":
+            out["message"] = (f"BLOCKED: Command flagged as dangerous ({danger[2]}) but cron jobs run without a user present to approve it. "
+                "Find an alternative approach that avoids this command. To allow dangerous commands in cron jobs, set approvals.cron_mode: approve in config.yaml.")
+        elif out["verdict"] == "deny":
+            out["message"] = (f"BLOCKED: Command flagged as dangerous ({danger[2]}) but single-query mode (-q) runs without a user present to approve it. "
+                "Find an alternative approach that avoids this command. To allow dangerous commands in single-query mode, set approvals.single_query_mode: approve in config.yaml.")
+elif op == "kanban_prompt":
+    from agent.prompt_builder import KANBAN_GUIDANCE
+    from agent.skill_commands import build_preloaded_skills_prompt
+    skills = build_preloaded_skills_prompt(a.get("skills") or [], task_id=a.get("task"))[0] if a.get("skills") else ""
+    out = {"guidance": KANBAN_GUIDANCE, "skills": skills or ""}
+elif op == "schedule":
+    from cron.jobs import parse_schedule
+    try: out = parse_schedule(a["text"])
+    except ValueError as error: out = {"error": str(error)}
+else:
+    import tools.memory_tool, tools.session_search_tool, tools.skills_tool, tools.kanban_tools
+    from tools.registry import registry
+    kw = {}
+    if a["name"] == "memory": kw["store"] = memory_store()[0]
+    if a["name"] == "session_search": kw["current_session_id"] = a.get("session_id")
+    out = registry.dispatch(a["name"], a.get("args") or {}, **kw)
+print("@@hermes@@" + json.dumps(out))
+`;
+
+const hermesEnv = (install, profileDir) => ({ PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '', HERMES_HOME: profileDir, PYTHONPATH: install.source });
+
+function hermesAnswer(what, run) {
+  const line = run.stdout.split('\n').find((l) => l.startsWith('@@hermes@@'));
+  if (!line) throw new Error(`Hermes answered nothing for ${what}: ${run.stderr.trim().slice(-300)}`);
+  return JSON.parse(line.slice('@@hermes@@'.length));
+}
+
+async function runHermes(profileDir, payload, env = {}) {
+  const install = hermesInstall();
+  if (!install?.python) throw new Error(`${payload.name ?? payload.op} is Hermes's, and no Hermes is installed on PATH`);
+  return hermesAnswer(payload.name ?? payload.op, await python(install, HERMES_TOOL, payload, { ...hermesEnv(install, profileDir), ...env }, 60_000));
+}
+
+/**
+ * The environment Hermes's dispatcher gives the worker it spawns for a task (`kanban_db._default_spawn`):
+ * the task, its run and claim, the board's database, workspaces and slug, the author its comments carry.
+ */
+export const KANBAN_ENV = Object.freeze([
+  'HERMES_KANBAN_TASK', 'HERMES_KANBAN_WORKSPACE', 'HERMES_KANBAN_BRANCH', 'HERMES_KANBAN_RUN_ID',
+  'HERMES_KANBAN_CLAIM_LOCK', 'HERMES_KANBAN_DB', 'HERMES_KANBAN_WORKSPACES_ROOT', 'HERMES_KANBAN_BOARD',
+  'HERMES_KANBAN_GOAL_MODE', 'HERMES_KANBAN_GOAL_MAX_TURNS', 'HERMES_PROFILE', 'HERMES_TENANT', 'HERMES_SESSION_SOURCE',
+]);
+
+/**
+ * One of Hermes's tools, called as Hermes's agent calls it; answers the handler's own result (Hermes's
+ * text). `env` is a dispatched worker's task environment, for the board's tools.
+ */
+export function hermesTool(profileDir, name, args, { sessionId = null, env = null } = {}) {
+  return runHermes(profileDir, { op: 'tool', name, args, session_id: sessionId }, env ?? {});
+}
+
+/**
+ * Hermes's approval rule for a worker's request (tools/approval.py): a shell command Hermes's own
+ * `detect_dangerous_command` calls safe runs without asking, as it does under Hermes, and so does every
+ * other tool (Hermes's file tools are not gated); a dangerous one is asked in a conversation (unless
+ * `approvals.mode: off`), and answered by `approvals.cron_mode` in a fire and `approvals.single_query_mode`
+ * in a dispatched worker, each deny by default. Answers `{ verdict: allow|ask|deny, why }`, or null without
+ * Hermes (the worker's own prompt is then relayed as it stands).
+ */
+export async function hermesApproval(profileDir, { command = null, context = 'conversation' } = {}) {
+  if (!hermesInstall()?.python) return null;
+  return runHermes(profileDir, { op: 'approval', command, context });
+}
+
+/**
+ * What Hermes's agent adds to a dispatched worker's system prompt: `KANBAN_GUIDANCE` (the task protocol)
+ * and the task's force-loaded skills (`build_preloaded_skills_prompt`, as `hermes --skills` loads them).
+ */
+export function kanbanPrompt(profileDir, { skills = [], task = null, env = {} } = {}) {
+  return runHermes(profileDir, { op: 'kanban_prompt', skills, task }, env);
+}
+
+/** The memory Hermes's agent would carry into a session starting now, as its system prompt carries it; '' for none. */
+export async function memorySnapshot(profileDir) {
+  if (!hermesInstall()?.python) return '';
+  return runHermes(profileDir, { op: 'snapshot' });
+}
+
+/**
+ * A schedule string as Hermes parses it (`{ kind: once|interval|cron, … }`), or null when no Hermes is
+ * installed; throws Hermes's own refusal. Synchronous: schedules are parsed where a job is built.
+ */
+export function hermesSchedule(profileDir, text) {
+  const install = hermesInstall();
+  if (!install?.python) return null;
+  const run = spawnSync(install.python, ['-c', HERMES_TOOL], { input: JSON.stringify({ op: 'schedule', text }), encoding: 'utf8', timeout: 30_000, cwd: install.source, env: hermesEnv(install, profileDir) });
+  const out = hermesAnswer('schedule', { stdout: run.stdout ?? '', stderr: run.stderr || run.error?.message || '' });
+  if (out?.error) throw new Error(out.error);
+  return out;
+}
+
+// One tick of Hermes's board dispatcher, as a Hermes gateway runs it (gateway/kanban_watchers.py
+// `_kanban_dispatcher_watcher`): the home's `kanban:` settings read as the gateway reads them, then
+// `kanban_db.dispatch_once` on every board. Hermes claims, reclaims, promotes and spawns; its spawn runs
+// `HERMES_BIN`, which the caller sets to the orchestrator's worker command.
+const KANBAN_TICK = `
+import json, sys
+a = json.loads(sys.stdin.read())
+from hermes_cli.config import load_config
+from hermes_cli import kanban_db as kb
+cfg = ((load_config() or {}).get("kanban") or {})
+def pos_int(v):
+    try: v = int(v)
+    except (TypeError, ValueError): return None
+    return v if v >= 1 else None
+max_in_progress = kb.resolve_max_in_progress(pos_int(cfg.get("max_in_progress")))
+try: failure_limit = int(cfg.get("failure_limit", kb.DEFAULT_FAILURE_LIMIT))
+except (TypeError, ValueError): failure_limit = kb.DEFAULT_FAILURE_LIMIT
+if failure_limit < 1: failure_limit = kb.DEFAULT_FAILURE_LIMIT
+try: stale = int(cfg.get("dispatch_stale_timeout_seconds", 0) or 0)
+except (TypeError, ValueError): stale = 0
+default_assignee = (cfg.get("default_assignee") or "").strip() or None
+try: boards = kb.list_boards(include_archived=False)
+except Exception: boards = [kb.read_board_metadata(kb.DEFAULT_BOARD)]
+out = []
+for b in boards:
+    slug = b.get("slug") or kb.DEFAULT_BOARD
+    conn = None
+    try:
+        conn = kb.connect(board=slug)
+        r = kb.dispatch_once(conn, board=slug, max_spawn=cfg.get("max_spawn"), max_in_progress=max_in_progress,
+            failure_limit=failure_limit, stale_timeout_seconds=stale, default_assignee=default_assignee,
+            max_in_progress_per_profile=pos_int(cfg.get("max_in_progress_per_profile")),
+            reconcile_orphans=bool(cfg.get("reconcile_orphans", True)))
+        count = lambda sql: conn.execute(sql).fetchone()[0]
+        out.append({"board": slug, "spawned": [list(x) for x in r.spawned], "reclaimed": r.reclaimed, "crashed": r.crashed,
+            "timed_out": r.timed_out, "skipped_locked": bool(getattr(r, "skipped_locked", False)),
+            "subscriptions": count("SELECT COUNT(*) FROM kanban_notify_subs"), "triage": count("SELECT COUNT(*) FROM tasks WHERE status = 'triage'")})
+    except Exception as error:
+        out.append({"board": slug, "error": str(error)})
+    finally:
+        if conn is not None: conn.close()
+print("@@hermes@@" + json.dumps(out, default=str))
+`;
+
+/** One dispatcher tick over the board at `root` (Hermes's `kanban_home`), `env` adding `HERMES_BIN` and the like. */
+export async function kanbanTick(root, env = {}) {
+  const install = hermesInstall();
+  if (!install?.python) throw new Error('the board is Hermes\'s, and no Hermes is installed on PATH');
+  return hermesAnswer('kanban dispatch', await python(install, KANBAN_TICK, {}, { ...hermesEnv(install, root), ...env }, 120_000));
+}
+
+/**
+ * Hermes's MCP trust gate for a relayed tool call (tools/mcp_tool.py `_trust_gate_check`): a tool of one of the
+ * profile's servers configured anything but `trust: full` (unset is full) is asked in a conversation and denied
+ * with nobody present. Answers a verdict, or null when the call is not such a server's.
+ */
+export function untrustedServerVerdict(profile, tool, context, { mcp = false } = {}) {
+  const servers = profile?.residue?.config?.mcp_servers ?? {};
+  // the configured name the tool is prefixed with (a name may itself hold `__`: the longest match is its)
+  const server = Object.keys(servers).filter((name) => (tool ?? '').startsWith(`mcp__${name}__`)).sort((a, b) => b.length - a.length)[0]
+    ?? (/^mcp__(.+?)__/.exec(tool ?? '')?.[1] ?? null);
+  // an MCP approval that names no tool cannot be judged: it fails closed, as Hermes's unknown trust does
+  if (!server && mcp) {
+    const why = 'an MCP tool call that names no tool';
+    return context === 'conversation' ? { verdict: 'ask', why } : { verdict: 'deny', why, message: `BLOCKED: ${why} cannot be approved with nobody present. Find an alternative approach.` };
+  }
+  const trust = server ? servers[server]?.trust : undefined;
+  if (!server || trust === undefined || trust === null || String(trust).trim().toLowerCase() === 'full') return null;
+  const why = `server ${server} is configured 'trust: untrusted'`;
+  return context === 'conversation' ? { verdict: 'ask', why } : { verdict: 'deny', why, message: `BLOCKED: ${why}, and its tools need approval, but nobody is present to approve it. Find an alternative approach.` };
+}