@halofy/agent-connect 0.12.1 → 0.13.0

package/src/hermes-config.mjs

@@ -0,0 +1,283 @@
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, rename, rm, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMap, isScalar, isSeq, parseDocument, visit } from "yaml";
+import { defaultRuntimeDirectory, safeDirectory, writeHostConfigFile } from "./storage.mjs";
+
+export const HERMES_REVIEWED_VERSION = "0.21.3";
+export const HERMES_HOOK_EVENTS = Object.freeze([
+  "on_session_start", "pre_llm_call", "post_llm_call", "post_tool_call",
+  "on_session_end", "on_session_finalize",
+]);
+const PLUGIN = "halofy-lifecycle";
+export const HERMES_PLUGIN_KEYS = Object.freeze([`${PLUGIN}/capture`, `${PLUGIN}/memory`]);
+const MARKER = ".halofy-managed.json";
+const FILES = ["capture/plugin.yaml", "capture/__init__.py", "capture/connection.json", "memory/plugin.json", "memory/mcp.json"];
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+// Pinned Hermes _portable_skill_namespace: the discovery key, not the manifest name.
+const MCP_SERVER_NAME = `agent-plugin-halofy-lifecycle-memory-${sha256(HERMES_PLUGIN_KEYS[1]).slice(0, 8)}__halofy`;
+
+/** Probe the executable, not an installation directory or a guessed host version. */
+export function detectHermes({ command = "hermes", execute = spawnSync, env = process.env } = {}) {
+  const result = execute(command, ["--version"], {
+    encoding: "utf8", timeout: 15_000, maxBuffer: 32_768, shell: false, env,
+  });
+  if (result.error || result.status !== 0) throw new Error("Hermes executable version probe failed");
+  const match = String(result.stdout || "").match(/^Hermes Agent v(\d+\.\d+\.\d+) \(2026\.9\.14\)\r?$/m);
+  if (match?.[1] !== HERMES_REVIEWED_VERSION) {
+    throw new Error(`Hermes lifecycle requires reviewed host ${HERMES_REVIEWED_VERSION} (2026.9.14)`);
+  }
+  return match[1];
+}
+
+function absolutePath(value, label) {
+  if (typeof value !== "string" || !value || /[\0\r\n]/.test(value) || !isAbsolute(value)) {
+    throw new Error(`${label} must be an absolute local path`);
+  }
+  return resolve(value);
+}
+
+async function fileSnapshot(path) {
+  await safeDirectory(dirname(path));
+  let stat;
+  try { stat = await lstat(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > 4_194_304) {
+    throw new Error("unsafe Hermes configuration file");
+  }
+  return { bytes: await readFile(path), mode: stat.mode & 0o777 };
+}
+
+function parseConfig(source) {
+  const doc = parseDocument(source, { uniqueKeys: true, strict: true });
+  if (doc.errors.length || doc.warnings.length) throw new Error("Hermes config.yaml is malformed or unsupported");
+  visit(doc, {
+    Alias() { throw new Error("Hermes configuration aliases are not supported for safe installation"); },
+    Node(_key, node) {
+      if (node.anchor || (node.tag && !node.tag.startsWith("tag:yaml.org,2002:"))) {
+        throw new Error("Hermes configuration anchors or custom tags are not supported");
+      }
+    },
+    Pair(_key, pair) {
+      if (!isScalar(pair.key) || typeof pair.key.value !== "string" || pair.key.value === "<<") {
+        throw new Error("Hermes configuration requires unique string mapping keys");
+      }
+    },
+  });
+  if (!doc.contents && !source.trim().replace(/^#.*$/gm, "").trim()) doc.contents = doc.createNode({});
+  if (!isMap(doc.contents)) throw new Error("Hermes configuration must be a mapping");
+  for (const key of ["plugins", "mcp_servers"]) {
+    if (doc.has(key) && !isMap(doc.get(key, true))) throw new Error(`Hermes ${key} must be a mapping`);
+  }
+  for (const key of ["enabled", "disabled"]) {
+    const list = doc.getIn(["plugins", key], true);
+    if (list !== undefined && (!isSeq(list) || list.items.some((item) => !isScalar(item) || typeof item.value !== "string"))) {
+      throw new Error(`Hermes plugins.${key} must be a string list`);
+    }
+  }
+  return doc;
+}
+
+function legacyMcp(entry, serverUrl) {
+  if (!serverUrl || !entry || typeof entry !== "object" || entry.command || !entry.url) return false;
+  try {
+    const base = new URL(serverUrl);
+    const target = new URL(entry.url);
+    if (!["http:", "https:"].includes(base.protocol) || target.username || target.password || target.search || target.hash) return false;
+    const expectedPath = `${base.pathname.replace(/\/$/, "")}/mcp`;
+    const bearer = Object.entries(entry.headers || {}).some(([key, value]) =>
+      key.toLowerCase() === "authorization" && typeof value === "string" && /^Bearer\s+\S+$/i.test(value));
+    return target.origin === base.origin && target.pathname === expectedPath && bearer;
+  } catch { return false; }
+}
+
+async function ownedPlugin(pluginPath) {
+  let exists;
+  try { exists = await lstat(pluginPath); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (!exists.isDirectory() || exists.isSymbolicLink()) throw new Error("unsafe Hermes plugin directory");
+  const markerFile = await fileSnapshot(join(pluginPath, MARKER));
+  let marker;
+  try { marker = JSON.parse(markerFile?.bytes.toString() || "null"); } catch { /* report without file contents */ }
+  if (marker?.owner !== "halofy-agent-runtime" || marker.schemaVersion !== 2 || !marker.files || !marker.mcp) {
+    throw new Error("unmanaged Hermes plugin directory; preserve it and resolve the conflict first");
+  }
+  for (const name of FILES) {
+    const file = await fileSnapshot(join(pluginPath, name));
+    if (!file || sha256(file.bytes) !== marker.files[name]) throw new Error("managed Hermes plugin file was edited; refusing overwrite");
+  }
+  async function inspectDirectory(relative = "") {
+    const directory = join(pluginPath, relative);
+    await safeDirectory(directory);
+    for (const name of await readdir(directory)) {
+      const entry = relative ? `${relative}/${name}` : name;
+      if ([MARKER, ...FILES].includes(entry)) continue;
+      if (entry === "capture" || entry === "memory") { await inspectDirectory(entry); continue; }
+      if (entry !== "capture/__pycache__") throw new Error("unmanaged file in Hermes plugin directory");
+      await safeDirectory(join(pluginPath, entry));
+      for (const cached of await readdir(join(pluginPath, entry))) {
+        if (!/^__init__\.cpython-\d+(?:\.opt-\d+)?\.pyc$/.test(cached)) throw new Error("unmanaged Hermes plugin cache");
+        await fileSnapshot(join(pluginPath, entry, cached));
+      }
+    }
+  }
+  await inspectDirectory();
+  return marker;
+}
+
+/** Inspect every existing ancestor without creating a fresh host installation. */
+async function existingDirectory(path) {
+  try { await safeDirectory(path); return true; }
+  catch (error) { if (error.code === "directory_missing") return false; throw error; }
+}
+
+/** Validate conflicts before the installer consumes an enrollment claim. No files are written. */
+export async function preflightHermes(options) {
+  return configureHermesInternal({ ...options, installationId: options.installationId ?? "preflight" }, true);
+}
+
+/** Install only in the selected Hermes home, preserving user YAML and refusing ambiguous ownership. */
+export async function configureHermes(options) {
+  return configureHermesInternal(options, false);
+}
+
+async function configureHermesInternal({
+  installationId, runtimePath, root = defaultRuntimeDirectory(), nodePath = process.execPath,
+  home = homedir(), env = process.env, serverUrl,
+  pluginSourcePath = fileURLToPath(new URL("./hermes-plugin.py", import.meta.url)),
+}, dryRun) {
+  if (typeof installationId !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(installationId)) throw new Error("invalid installation id");
+  const hermesHome = absolutePath(env.HERMES_HOME || join(absolutePath(home, "home"), ".hermes"), "Hermes home");
+  const connection = {
+    nodePath: absolutePath(nodePath, "nodePath"), runtimePath: absolutePath(runtimePath, "runtimePath"),
+    installationId, root: absolutePath(root, "runtime root"), hermesHome,
+  };
+  let homeExists = true;
+  if (dryRun) homeExists = await existingDirectory(hermesHome);
+  else await safeDirectory(hermesHome, true);
+  const configPath = join(hermesHome, "config.yaml");
+  const pluginsPath = join(hermesHome, "plugins");
+  if (dryRun) await existingDirectory(pluginsPath);
+  else await safeDirectory(pluginsPath, true);
+  const pluginPath = join(pluginsPath, PLUGIN);
+  const lockPath = join(pluginsPath, ".halofy-lifecycle.install.lock");
+  let lock;
+  if (dryRun) {
+    let lockExists = false;
+    try { await lstat(lockPath); lockExists = true; } catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (lockExists) throw new Error("Hermes installation is busy; inspect its installation lock before retrying");
+  } else {
+    try { lock = await open(lockPath, "wx", 0o600); } catch (error) {
+      if (error.code === "EEXIST") throw new Error("Hermes installation is busy; inspect its installation lock before retrying");
+      throw error;
+    }
+  }
+  const nonce = `${process.pid}.${randomBytes(8).toString("hex")}`;
+  const stage = join(pluginsPath, `.halofy-stage-${nonce}`);
+  const backup = join(pluginsPath, `.halofy-backup-${nonce}`);
+  let backedUp = false;
+  let installed = false;
+  let committed = false;
+  try {
+    const original = homeExists ? await fileSnapshot(configPath) : null;
+    const doc = parseConfig(original?.bytes.toString("utf8") || "");
+    const old = await ownedPlugin(pluginPath);
+    const enabled = doc.getIn(["plugins", "enabled"])?.toJSON() || [];
+    const disabled = doc.getIn(["plugins", "disabled"])?.toJSON() || [];
+    if ([PLUGIN, ...HERMES_PLUGIN_KEYS, "halofy-capture", "halofy-memory"].some((name) => disabled.includes(name))) {
+      throw new Error("Hermes lifecycle plugin was explicitly disabled; refusing to re-enable it");
+    }
+    const mcp = {
+      type: "stdio",
+      command: basename(connection.nodePath),
+      args: [connection.runtimePath, "hermes-mcp", "--hermes-home", hermesHome, "--connection", installationId],
+      // Portable plugins only interpolate reserved plugin variables; ${PATH}
+      // would remain literal. Capture the installer environment for the host
+      // version probe and prepend the reviewed Node executable's directory.
+      env: { HALOFY_AGENT_HOME: connection.root,
+        PATH: [dirname(connection.nodePath), env.PATH ?? process.env.PATH].filter(Boolean).join(delimiter) },
+    };
+    let replacedLegacyMcpEntries = 0;
+    const servers = doc.get("mcp_servers")?.toJSON() || {};
+    if (Object.hasOwn(servers, MCP_SERVER_NAME)) {
+      throw new Error("Hermes namespaced Halofy MCP entry conflicts with the portable memory plugin");
+    }
+    for (const [name, entry] of Object.entries(servers)) {
+      if (!["halofy", "halomem"].includes(name.toLowerCase())) continue;
+      const owned = name === "halofy" && old && sha256(JSON.stringify(entry)) === sha256(JSON.stringify(old.mcp));
+      if (!owned && !legacyMcp(entry, serverUrl)) {
+        throw new Error("unmanaged or edited Hermes Halofy MCP entry; refusing overwrite");
+      }
+      doc.deleteIn(["mcp_servers", name]);
+      replacedLegacyMcpEntries += 1;
+    }
+    for (const key of HERMES_PLUGIN_KEYS) {
+      if (!enabled.includes(key)) {
+        if (doc.hasIn(["plugins", "enabled"])) doc.addIn(["plugins", "enabled"], key);
+        else doc.setIn(["plugins", "enabled"], [key]);
+      }
+    }
+    const pluginSource = await readFile(pluginSourcePath);
+    if (!pluginSource.length) throw new Error("Hermes lifecycle plugin source is empty");
+    if (dryRun) return { ready: true, configPath, pluginPath, replacedLegacyMcpEntries };
+    const contents = {
+      "capture/plugin.yaml": `name: halofy-capture\nversion: "1.0.0"\ndescription: Halofy signed lifecycle capture\nrequires_hermes: "==${HERMES_REVIEWED_VERSION}"\ncapabilities: []\nhooks:\n${HERMES_HOOK_EVENTS.map((event) => `  - ${event}`).join("\n")}\n`,
+      "capture/__init__.py": pluginSource,
+      "capture/connection.json": `${JSON.stringify(connection, null, 2)}\n`,
+      "memory/plugin.json": `${JSON.stringify({
+        $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+        name: "halofy-memory", version: "1.0.0", description: "Halofy agent-invoked memory tools",
+      }, null, 2)}\n`,
+      "memory/mcp.json": `${JSON.stringify({
+        $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", mcpServers: { halofy: mcp },
+      }, null, 2)}\n`,
+    };
+    const files = Object.fromEntries(Object.entries(contents).map(([name, bytes]) => [name, sha256(bytes)]));
+    const marker = { owner: "halofy-agent-runtime", schemaVersion: 2, files, mcp };
+    await mkdir(stage, { mode: 0o700 });
+    await mkdir(join(stage, "capture"), { mode: 0o700 });
+    await mkdir(join(stage, "memory"), { mode: 0o700 });
+    for (const [name, bytes] of Object.entries({ ...contents, [MARKER]: `${JSON.stringify(marker, null, 2)}\n` })) {
+      const handle = await open(join(stage, name), "wx", 0o600);
+      try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+    }
+    // Do not clobber an edit made while staging the managed plugin.
+    const current = await fileSnapshot(configPath);
+    if (!!original !== !!current || (original && (!original.bytes.equals(current.bytes) || original.mode !== current.mode))) {
+      throw new Error("Hermes configuration changed during installation; retry after reviewing the change");
+    }
+    await safeDirectory(pluginsPath);
+    if (old) {
+      await ownedPlugin(pluginPath);
+      await rename(pluginPath, backup);
+      backedUp = true;
+    } else {
+      try { await lstat(pluginPath); throw new Error("Hermes plugin appeared during installation"); }
+      catch (error) { if (error.code !== "ENOENT") throw error; }
+    }
+    await rename(stage, pluginPath);
+    installed = true;
+    const beforeWrite = await fileSnapshot(configPath);
+    if (!!original !== !!beforeWrite || (original && (!original.bytes.equals(beforeWrite.bytes) || original.mode !== beforeWrite.mode))) {
+      throw new Error("Hermes configuration changed during installation; retry after reviewing the change");
+    }
+    await writeHostConfigFile(configPath, doc.toString());
+    committed = true;
+    return {
+      configuredPaths: [configPath, ...FILES.map((name) => join(pluginPath, name))],
+      hookEvents: [...HERMES_HOOK_EVENTS], replacedLegacyMcpEntries,
+      hermes: { configPath, pluginPath, files, mcp, hostVersion: HERMES_REVIEWED_VERSION,
+        pluginKeys: [...HERMES_PLUGIN_KEYS], mcpServerName: MCP_SERVER_NAME },
+    };
+  } finally {
+    if (!committed && installed) await rm(pluginPath, { recursive: true, force: true });
+    if (!committed && backedUp) await rename(backup, pluginPath);
+    if (committed && backedUp) await rm(backup, { recursive: true, force: true });
+    if (!dryRun) {
+      await rm(stage, { recursive: true, force: true });
+      await lock.close();
+      await unlink(lockPath);
+    }
+  }
+}

package/src/hermes-health.mjs

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { parseDocument } from "yaml";
+import { safeDirectory } from "./storage.mjs";
+
+async function regularFile(path) {
+  await safeDirectory(dirname(path));
+  const entry = await lstat(path);
+  if (!entry.isFile() || entry.isSymbolicLink() || entry.nlink !== 1 || entry.size > 4 * 1024 * 1024) {
+    throw new Error("unsafe Hermes configuration");
+  }
+  return readFile(path);
+}
+
+/** Local inspection is configuration evidence only, never proof of captured turns. */
+export async function inspectHermesCaptureHealth(metadata) {
+  try {
+    if (!metadata?.configPath || !metadata?.pluginPath || !metadata?.files || !metadata?.mcp ||
+        !metadata?.mcpServerName || !Array.isArray(metadata.pluginKeys) || metadata.pluginKeys.length !== 2) {
+      return { captureState: "unknown" };
+    }
+    const document = parseDocument((await regularFile(metadata.configPath)).toString("utf8"), { uniqueKeys: true });
+    if (document.errors.length || document.warnings.length) return { captureState: "hooks_missing" };
+    const config = document.toJS({ maxAliasCount: 0 });
+    if (!Array.isArray(config?.plugins?.enabled) ||
+        !metadata.pluginKeys.every((key) => config.plugins.enabled.includes(key)) ||
+        ["halofy-lifecycle", "halofy-capture", "halofy-memory", ...metadata.pluginKeys]
+          .some((key) => config.plugins.disabled?.includes(key)) ||
+        Object.keys(config.mcp_servers || {}).some((key) =>
+          ["halofy", "halomem", metadata.mcpServerName.toLowerCase()].includes(key.toLowerCase()))) {
+      return { captureState: "hooks_missing" };
+    }
+    for (const name of ["capture/plugin.yaml", "capture/__init__.py", "capture/connection.json", "memory/plugin.json", "memory/mcp.json"]) {
+      const actual = createHash("sha256").update(await regularFile(join(metadata.pluginPath, name))).digest("hex");
+      if (actual !== metadata.files[name]) return { captureState: "hooks_missing" };
+    }
+    const portable = JSON.parse((await regularFile(join(metadata.pluginPath, "memory/mcp.json"))).toString("utf8"));
+    if (!isDeepStrictEqual(portable.mcpServers?.halofy, metadata.mcp)) return { captureState: "hooks_missing" };
+    return { captureState: "active" };
+  } catch {
+    return { captureState: "hooks_missing" };
+  }
+}

package/src/hermes-hook.mjs

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { isActiveInstallation } from "./active.mjs";
+import { readHookInput } from "./claude-hook.mjs";
+import { captureStateSnapshot } from "./health.mjs";
+import { LifecycleRuntime } from "./runtime.mjs";
+import { normalizedEvent, normalizeClaudeHookEvent, normalizeHostMessageEvent } from "./session.mjs";
+import { defaultRuntimeDirectory } from "./storage.mjs";
+
+export const HERMES_HOOK_EVENTS = Object.freeze(new Set([
+  "on_session_start", "pre_llm_call", "post_llm_call", "post_tool_call",
+  "on_session_end", "on_session_finalize",
+]));
+
+function identity(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 512 &&
+    !/[\u0000-\u001f\u007f]/.test(value) ? value : null;
+}
+
+/** Only native observer callbacks from the reviewed Hermes release reach this seam. */
+export async function runHermesLifecycleHook(connection, eventName, {
+  input, inputStream = process.stdin, root = defaultRuntimeDirectory(), stderr = process.stderr,
+  runtimeFactory = (active, options) => new LifecycleRuntime(active, options),
+} = {}) {
+  try {
+    if (connection.clientKind !== "hermes-agents" || !HERMES_HOOK_EVENTS.has(eventName)) {
+      throw new Error("unsupported Hermes hook");
+    }
+    if (!await isActiveInstallation(connection, root)) return { handled: true, inactive: true };
+    // Bind admission to callback entry, before potentially delayed stdin. A
+    // pause/resume while input arrives cannot relabel prior content as new.
+    const capture = await captureStateSnapshot(root, connection.installationId);
+    if (capture.paused) return { handled: true, paused: true };
+    const body = input ?? await readHookInput(inputStream, 4 * 1024 * 1024);
+    if (!await isActiveInstallation(connection, root)) return { handled: true, inactive: true };
+    const session = identity(body.session_id);
+    if (!session) return { handled: true, unavailable: "missing_host_session" };
+    const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
+    const nativeId = eventName === "post_tool_call" ? identity(body.tool_call_id) : identity(body.turn_id);
+    const evidenceId = createHash("sha256").update(`${session}\0${eventName}\0${nativeId || "boundary"}`).digest("hex");
+    async function gap(reason) {
+      await runtime.enqueueSequencedEvents(session, ({ nextSequence }) => [{
+        ...normalizedEvent({ eventKey: `hermes:gap:${evidenceId}`, type: "checkpoint",
+          occurredAt: new Date().toISOString(), payload: { captureStatus: "unavailable",
+            captureReasonCode: reason, contentFormat: "json", boundary: eventName } }),
+        sequence: nextSequence,
+      }]);
+      return { handled: true, unavailable: reason };
+    }
+    if (body.capture_gap) return await gap("hermes_hook_payload_too_large");
+    if (eventName === "on_session_start") {
+      await runtime.replay();
+      await runtime.resolveSession(session);
+      await runtime.heartbeat(connection.capabilities || {});
+    } else if (eventName === "pre_llm_call" || eventName === "post_llm_call") {
+      const role = eventName === "pre_llm_call" ? "user" : "assistant";
+      const text = role === "user" ? body.user_message : body.assistant_response;
+      if (!nativeId || typeof text !== "string") return await gap("missing_message_evidence");
+      await runtime.enqueueSequencedEvents(session, ({ nextSequence }) => [normalizeHostMessageEvent({
+        clientKind: "hermes-agents", role, text, eventId: evidenceId,
+      }, { sequence: nextSequence })]);
+    } else if (eventName === "post_tool_call") {
+      if (!nativeId || !identity(body.tool_name)) return await gap("missing_tool_evidence");
+      const common = { event_id: `hermes:${evidenceId}`, tool_name: body.tool_name,
+        tool_use_id: evidenceId, tool_input: body.args, tool_response: body.result,
+        tool_error: ["error", "blocked", "cancelled", "timeout"].includes(body.status) };
+      await runtime.enqueueSequencedEvents(session, ({ sessionHash, nextSequence }) => [
+        normalizeClaudeHookEvent("tool_call", common, { sessionHash, sequence: nextSequence }),
+        normalizeClaudeHookEvent("tool_result", common, { sessionHash, sequence: nextSequence + 1 }),
+      ]);
+    } else if (eventName === "on_session_end") {
+      // Hermes fires this after each turn. It is NOT a conversation close.
+      if (body.interrupted === true || body.failed === true) {
+        await gap(body.interrupted === true ? "hermes_turn_interrupted" : "hermes_turn_failed");
+      }
+      await runtime.replay();
+      await runtime.commit(session, "checkpoint");
+      await runtime.heartbeat(connection.capabilities || {});
+    } else {
+      await runtime.close(session, "session_end");
+    }
+    return { handled: true };
+  } catch {
+    stderr.write("[halofy] Hermes lifecycle hook degraded: runtime_unavailable\n");
+    return { handled: true, degraded: true };
+  }
+}

package/src/hermes-plugin.py

@@ -0,0 +1,67 @@
+"""Halofy observer for Hermes 0.21.3 (v2026.9.14).
+
+The plugin has no provider/storage credentials and never changes a hook result.
+It forwards only reviewed event fields to the installed signed Node runtime.
+"""
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+EVENTS = (
+    "on_session_start", "pre_llm_call", "post_llm_call", "post_tool_call",
+    "on_session_end", "on_session_finalize",
+)
+FIELDS = (
+    "session_id", "turn_id", "tool_call_id", "user_message",
+    "assistant_response", "tool_name", "args", "result", "status",
+    "completed", "failed", "interrupted", "turn_exit_reason",
+)
+MAX_INPUT_BYTES = 4 * 1024 * 1024
+
+
+def _forward(event, **kwargs):
+    try:
+        config_path = Path(__file__).with_name("connection.json")
+        if config_path.is_symlink():
+            raise ValueError("unsafe configuration")
+        config = json.loads(config_path.read_text(encoding="utf-8"))
+        from hermes_cli.config import get_hermes_home
+        enrolled_home = Path(config["hermesHome"]).resolve(strict=True)
+        if (get_hermes_home().resolve() != enrolled_home or
+                Path(__file__).resolve().parent != enrolled_home / "plugins" / "halofy-lifecycle" / "capture"):
+            raise ValueError("profile is not enrolled")
+        payload = {key: kwargs[key] for key in FIELDS if key in kwargs}
+        encoded = json.dumps(payload, ensure_ascii=False, allow_nan=False).encode("utf-8")
+        if len(encoded) > MAX_INPUT_BYTES:
+            # Retain an explicit gap, never a truncated conversation body.
+            encoded = json.dumps({"session_id": kwargs.get("session_id"),
+                                  "turn_id": kwargs.get("turn_id"),
+                                  "tool_call_id": kwargs.get("tool_call_id"),
+                                  "capture_gap": "hermes_hook_payload_too_large"}).encode("utf-8")
+        environment = dict(os.environ, HALOFY_AGENT_HOME=config["root"])
+        completed = subprocess.run(
+            [config["nodePath"], config["runtimePath"], "hermes-hook", event,
+             "--connection", config["installationId"]],
+            input=encoded, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            env=environment, timeout=20, check=False,
+        )
+        if completed.returncode:
+            raise RuntimeError("runtime unavailable")
+    except Exception:
+        # Host operation continues; neither event contents nor credentials reach logs.
+        print("[halofy] Hermes capture unavailable; inspect connection diagnostics.", file=sys.stderr)
+    return None
+
+
+def register(ctx):
+    # Hermes's manifest constraint parser is permissive for unknown/prerelease
+    # versions; enforce the exact reviewed native ABI before registering hooks.
+    from hermes_cli import __version__, __release_date__
+    if __version__ != "0.21.3" or str(__release_date__) != "2026.9.14":
+        raise RuntimeError("Halofy lifecycle requires reviewed Hermes 0.21.3 (2026.9.14)")
+    for event in EVENTS:
+        def observer(_event=event, **kwargs):
+            return _forward(_event, **kwargs)
+        ctx.register_hook(event, observer)

package/src/install.mjs

@@ -9,6 +9,7 @@ import { SignedRuntimeTransport } from "./transport.mjs";
 import { inspectCaptureHealth } from "./health.mjs";
 import { INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
 import { CLIENT_KINDS, CLIENT_REGISTRY, lifecycleClient } from "./client-registry.mjs";
+import { initializeSkillGuard } from "./skill-guard.mjs";
 import { syncManagedSkills } from "./skills-sync.mjs";
 import { syncManagedDelivery } from "./delivery-sync.mjs";
 import { retirePredecessorContent } from "./predecessor-sync.mjs";
@@ -207,6 +208,10 @@ export async function installLocalConnection({
     ...(typeof consumed.namespace === "string" ? { namespace: consumed.namespace } : {}),
     ...(instructionProfile ? { instructionProfile } : {}),
   };
+  if (clientKind === "claude-code") {
+    await initializeSkillGuard(root);
+    connection.skillGuardVersion = 1;
+  }
   await store.save(connection);
   await writePrivateFile(join(root, `active-${clientKind}.json`), `${JSON.stringify({
     version: 1,
@@ -256,6 +261,9 @@ export async function installRuntimeBundle({
   await ensurePrivateDirectory(staging);
   await cp(join(sourceRoot, "src"), join(staging, "src"), { recursive: true, force: false });
   await cp(join(sourceRoot, "bin"), join(staging, "bin"), { recursive: true, force: false });
+  // yaml is exact-pinned and bundled in the reviewed tarball, including its ISC
+  // license. The durable copy must remain usable after npx's cache is removed.
+  await cp(join(sourceRoot, "node_modules", "yaml"), join(staging, "node_modules", "yaml"), { recursive: true, force: false });
   await rm(runtimeRoot, { recursive: true, force: true });
   await rename(staging, runtimeRoot);
   if (process.platform !== "win32") {

package/src/installer-cli.mjs

@@ -15,11 +15,12 @@ import {
   syncInstalledDelivery,
 } from "./install.mjs";
 import { configureClaudeProject } from "./claude-config.mjs";
+import { configureHermes, detectHermes, preflightHermes } from "./hermes-config.mjs";
 import { configureCline, configureCodex, configureCursor, configureGemini, configureKimi, configureVscode } from "./host-config.mjs";
 import { CLIENT_KINDS, lifecycleClient } from "./client-registry.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { instructionProfile } from "./instructions.mjs";
-import { DISCLOSURE_VERSION, INSTALLER_VERSION } from "./version.mjs";
+import { DISCLOSURE_VERSION, INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
 import { managedSkillsDirectory } from "./skills-sync.mjs";
 
 const CLAIM_PATTERN = /^hsc_[A-Za-z0-9_-]{43}$/;
@@ -118,6 +119,7 @@ export function detectCline(home = homedir()) {
 
 export function detectClient(clientKind) {
   const client = lifecycleClient(clientKind);
+  if (clientKind === "hermes-agents") return detectHermes();
   if (clientKind === "cline") return detectCline();
   if (!client.command) throw new Error(`${client.label} does not have a packaged detector`);
   const result = spawnSync(client.command, ["--version"], {
@@ -188,9 +190,12 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
     "- encrypted local retry queue and governed retained conversations,",
     "- canonical learning when the selected badge permits writes, and",
     skillsRoot
-      ? `- approved company and team skills written to ${skillsRoot}/<skill>/SKILL.md and kept current at each session start; withdrawn skills are moved aside, never deleted.`
+      ? `- approved company and team skills written to ${skillsRoot}/<skill>/SKILL.md and refreshed at supported session starts; withdrawn skills are moved aside, never deleted.`
       : "- no managed skills folder for this host (skills stay available through skill_invoke).",
     skillsRoot ? "- authorized company and team policy/knowledge references copied locally; failed refreshes remove managed context from discovery." : "",
+    clientKind === "codex" ? "Codex exec/headless hooks are not verified. Automatic startup sync and capture must not be assumed; use the exact syncCommand executable and arguments printed after installation before headless work. Explicit sync does not enable capture." : "",
+    clientKind === "claude-code" ? "Claude receives a Read allow rule only for this installation's policy/knowledge context folder. Existing ask/deny rules and project trust still apply; assigned skills and MCP tools may require separate host permission." : "",
+    clientKind === "hermes-agents" ? "Hermes 0.21.3 only: installs an observer plugin and signed MCP in the selected HERMES_HOME profile. Captures text prompts, final uninterrupted replies, tool calls/results and finalization. Intermediate or interrupted replies, compaction, subagents, tokens, managed skills and organization instructions are unavailable. No tool-override permission or automatic recall injection is enabled." : "",
     "",
     `Supported capture categories: ${supported.length > 0 ? supported.join(", ") : "none"}.`,
     `Unsupported capture categories: ${unsupported.length > 0 ? unsupported.join(", ") : "none"}.`,
@@ -231,6 +236,7 @@ export function allDisclosureText({ serverUrl, projectRoot, organization = null,
     lines.push(
       "",
       `--- ${client.label} (${host.clientVersion}) ---`,
+      host.clientKind === "hermes-agents" ? "Hermes 0.21.3 only: selected profile observer and signed MCP; final uninterrupted text only. Interrupted/intermediate replies, compaction, subagents, token usage, managed instructions and skills are unavailable. No automatic recall injection or tool-override grant." : "",
       `Supported capture categories: ${supported.length > 0 ? supported.join(", ") : "none"}.`,
       `Unsupported capture categories: ${unsupported.length > 0 ? unsupported.join(", ") : "none"}.`,
       client.coverage === "complete"
@@ -238,7 +244,7 @@ export function allDisclosureText({ serverUrl, projectRoot, organization = null,
         : `This host has partial coverage (${client.reason}); missing categories remain explicit.`,
       managedSkillsDirectory(host.clientKind)
         ? `Approved company and team skills are written to ${managedSkillsDirectory(host.clientKind)}/<skill>/SKILL.md ` +
-          "and kept current at each session start; withdrawn skills are moved aside, never deleted. " +
+          "and refreshed at supported session starts; withdrawn skills are moved aside, never deleted. " +
           "Authorized company and team policy/knowledge references are copied locally; failed refreshes remove managed context from discovery."
         : "No managed skills folder for this host; skills stay available through skill_invoke.",
     );
@@ -252,6 +258,7 @@ export function allDisclosureText({ serverUrl, projectRoot, organization = null,
   }
   lines.push(
     "",
+    "Codex exec/headless hooks are not verified: use the exact syncCommand executable and arguments printed after installation before work; this does not enable capture. Claude Read grants cover only the installation's policy/knowledge context, preserve ask/deny, and require project trust; skills and MCP tools may need separate permission.",
     "Authorized organization managers may review retained conversations and summaries.",
     "This reads and writes its managed skill folders and instruction sections; it does not scan historical files, other applications, clipboard, keystrokes, or other agents.",
     "Organization instructions: supported adapters manage an additive global rule file or marked section across projects in the selected local agent profile. Existing personal instructions are preserved. Updates sync at installation and supported session starts; restart the host to load changes.",
@@ -275,6 +282,7 @@ export async function confirmDisclosure({ input = process.stdin, output = proces
 }
 
 async function configureHost(clientKind, common, { claudeConfigPath } = {}) {
+  if (clientKind === "hermes-agents") return configureHermes(common);
   if (clientKind === "claude-code") {
     return configureClaudeProject({ ...common, ...(claudeConfigPath ? { claudeConfigPath } : {}) });
   }
@@ -351,6 +359,9 @@ async function runAllInstaller(input, {
   const results = [];
   for (const host of detected) {
     try {
+      if (host.clientKind === "hermes-agents") await preflightHermes({ root,
+        runtimePath: bundle.runtimePath, serverUrl: input.serverUrl,
+        ...(skillsHome ? { home: skillsHome } : {}) });
       const installed = await installLocalConnection({
         serverUrl: input.serverUrl,
         claim: host.claim,
@@ -361,10 +372,12 @@ async function runAllInstaller(input, {
         instructionProfile: instructionProfile(host.clientKind, skillsHome ? { home: skillsHome } : {}),
       });
       const configured = await configureHost(host.clientKind, {
+        root,
         projectRoot: input.projectRoot,
         installationId: installed.installationId,
         serverUrl: input.serverUrl,
         runtimePath: bundle.runtimePath,
+        ...(skillsHome ? { home: skillsHome } : {}),
       }, { claudeConfigPath });
       await recordHealthTargets({ root, installationId: installed.installationId, configured, runtimePath: bundle.runtimePath });
       let heartbeat = false;
@@ -390,6 +403,8 @@ async function runAllInstaller(input, {
           : null,
         proofStorage: installed.proofStorage,
         instructions: installed.instructions,
+        syncCommand: { command: process.execPath, args: [bundle.runtimePath, "sync", "--connection", installed.installationId], environment: { HALOFY_AGENT_HOME: root } },
+        skillGuard: configured.skillGuard,
         configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
         replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries || 0,
         nextStep: `Restart ${lifecycleClient(host.clientKind).label}, then check the connection in Halofy.`,
@@ -457,6 +472,9 @@ export async function runInstaller(argv, {
   })}\n`);
   await confirm();
 
+  if (input.clientKind === "hermes-agents") await preflightHermes({ root,
+    runtimePath: join(root, "runtime", RUNTIME_VERSION, "bin", "halofy-agent.mjs"), serverUrl: input.serverUrl,
+    ...(skillsHome ? { home: skillsHome } : {}) });
   const installed = await installLocalConnection({
     serverUrl: input.serverUrl,
     claim: input.claim,
@@ -468,10 +486,12 @@ export async function runInstaller(argv, {
   });
   const bundle = await installRuntimeBundle({ root, ...(sourceRoot ? { sourceRoot } : {}) });
   const common = {
+    root,
     projectRoot: input.projectRoot,
     installationId: installed.installationId,
     serverUrl: input.serverUrl,
     runtimePath: bundle.runtimePath,
+    ...(skillsHome ? { home: skillsHome } : {}),
   };
   const configured = await configureHost(input.clientKind, common, { claudeConfigPath });
   await recordHealthTargets({ root, installationId: installed.installationId, configured, runtimePath: bundle.runtimePath });
@@ -496,6 +516,8 @@ export async function runInstaller(argv, {
     publishedPackage: true,
     projectConfigured: true,
     instructions: installed.instructions,
+    syncCommand: { command: process.execPath, args: [bundle.runtimePath, "sync", "--connection", installed.installationId], environment: { HALOFY_AGENT_HOME: root } },
+    skillGuard: configured.skillGuard,
     configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
     replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries || 0,
     mcpConfiguration: localMcpSnippet({