@halofy/agent-connect 0.12.0 → 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/host-hook.mjs

@@ -9,7 +9,7 @@ import {
   rankedRecallBlocks,
 } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
-import { readHookInput, syncSkillsAtSessionStart } from "./claude-hook.mjs";
+import { readHookInput, syncConfigurationAtSessionStart } from "./claude-hook.mjs";
 import { syncManagedDelivery } from "./delivery-sync.mjs";
 import { transcriptDriverFor } from "./transcript-drivers/index.mjs";
 
@@ -161,9 +161,8 @@ export async function runHostLifecycleHook(connection, eventName, {
     const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
     if (capture.paused) {
       if (START_EVENTS.has(eventName)) {
-        await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-        // Capture pause does not suspend governed instruction delivery.
-        await runtime.syncInstructions?.().catch(() => {});
+        // Capture pause does not suspend instruction or reference delivery.
+        await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
         await runtime.heartbeat(connection.capabilities || {});
       } else if (USER_EVENTS.has(eventName)) {
         const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
@@ -175,9 +174,7 @@ export async function runHostLifecycleHook(connection, eventName, {
 
     if (START_EVENTS.has(eventName)) {
       // Refresh/withdraw local context even when replay or heartbeat fails.
-      await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-      // Instructions have their own brownout boundary, independent of recall.
-      await runtime.syncInstructions?.().catch(() => {});
+      await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
       if (RECALL_INJECTION_ENABLED) {

package/src/install.mjs

@@ -4,11 +4,12 @@ import { chmod, cp, rename, rm, unlink } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { generateInstallationKeyPair } from "./crypto.mjs";
 import { ConnectionStore, defaultRuntimeDirectory, ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
-import { syncAgentInstructions } from "./instructions.mjs";
+import { INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS, syncAgentInstructions } from "./instructions.mjs";
 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,
@@ -232,7 +237,7 @@ export async function installLocalConnection({
     }
   }
   const instructions = instructionProfile
-    ? await syncAgentInstructions(connection, { root, transport: new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 2_000 }) })
+    ? await syncAgentInstructions(connection, { root, fetchImpl, timeoutMs: INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS })
     : undefined;
   return {
     installationId,
@@ -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") {