@halofy/agent-connect 0.12.0 → 0.13.0

package/node_modules/yaml/dist/visit.js

@@ -0,0 +1,236 @@
+'use strict';
+
+var identity = require('./nodes/identity.js');
+
+const BREAK = Symbol('break visit');
+const SKIP = Symbol('skip children');
+const REMOVE = Symbol('remove node');
+/**
+ * Apply a visitor to an AST node or document.
+ *
+ * Walks through the tree (depth-first) starting from `node`, calling a
+ * `visitor` function with three arguments:
+ *   - `key`: For sequence values and map `Pair`, the node's index in the
+ *     collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
+ *     `null` for the root node.
+ *   - `node`: The current node.
+ *   - `path`: The ancestry of the current node.
+ *
+ * The return value of the visitor may be used to control the traversal:
+ *   - `undefined` (default): Do nothing and continue
+ *   - `visit.SKIP`: Do not visit the children of this node, continue with next
+ *     sibling
+ *   - `visit.BREAK`: Terminate traversal completely
+ *   - `visit.REMOVE`: Remove the current node, then continue with the next one
+ *   - `Node`: Replace the current node, then continue by visiting it
+ *   - `number`: While iterating the items of a sequence or map, set the index
+ *     of the next step. This is useful especially if the index of the current
+ *     node has changed.
+ *
+ * If `visitor` is a single function, it will be called with all values
+ * encountered in the tree, including e.g. `null` values. Alternatively,
+ * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
+ * `Alias` and `Scalar` node. To define the same visitor function for more than
+ * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
+ * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
+ * specific defined one will be used for each node.
+ */
+function visit(node, visitor) {
+    const visitor_ = initVisitor(visitor);
+    if (identity.isDocument(node)) {
+        const cd = visit_(null, node.contents, visitor_, Object.freeze([node]));
+        if (cd === REMOVE)
+            node.contents = null;
+    }
+    else
+        visit_(null, node, visitor_, Object.freeze([]));
+}
+// Without the `as symbol` casts, TS declares these in the `visit`
+// namespace using `var`, but then complains about that because
+// `unique symbol` must be `const`.
+/** Terminate visit traversal completely */
+visit.BREAK = BREAK;
+/** Do not visit the children of the current node */
+visit.SKIP = SKIP;
+/** Remove the current node */
+visit.REMOVE = REMOVE;
+function visit_(key, node, visitor, path) {
+    const ctrl = callVisitor(key, node, visitor, path);
+    if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
+        replaceNode(key, path, ctrl);
+        return visit_(key, ctrl, visitor, path);
+    }
+    if (typeof ctrl !== 'symbol') {
+        if (identity.isCollection(node)) {
+            path = Object.freeze(path.concat(node));
+            for (let i = 0; i < node.items.length; ++i) {
+                const ci = visit_(i, node.items[i], visitor, path);
+                if (typeof ci === 'number')
+                    i = ci - 1;
+                else if (ci === BREAK)
+                    return BREAK;
+                else if (ci === REMOVE) {
+                    node.items.splice(i, 1);
+                    i -= 1;
+                }
+            }
+        }
+        else if (identity.isPair(node)) {
+            path = Object.freeze(path.concat(node));
+            const ck = visit_('key', node.key, visitor, path);
+            if (ck === BREAK)
+                return BREAK;
+            else if (ck === REMOVE)
+                node.key = null;
+            const cv = visit_('value', node.value, visitor, path);
+            if (cv === BREAK)
+                return BREAK;
+            else if (cv === REMOVE)
+                node.value = null;
+        }
+    }
+    return ctrl;
+}
+/**
+ * Apply an async visitor to an AST node or document.
+ *
+ * Walks through the tree (depth-first) starting from `node`, calling a
+ * `visitor` function with three arguments:
+ *   - `key`: For sequence values and map `Pair`, the node's index in the
+ *     collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
+ *     `null` for the root node.
+ *   - `node`: The current node.
+ *   - `path`: The ancestry of the current node.
+ *
+ * The return value of the visitor may be used to control the traversal:
+ *   - `Promise`: Must resolve to one of the following values
+ *   - `undefined` (default): Do nothing and continue
+ *   - `visit.SKIP`: Do not visit the children of this node, continue with next
+ *     sibling
+ *   - `visit.BREAK`: Terminate traversal completely
+ *   - `visit.REMOVE`: Remove the current node, then continue with the next one
+ *   - `Node`: Replace the current node, then continue by visiting it
+ *   - `number`: While iterating the items of a sequence or map, set the index
+ *     of the next step. This is useful especially if the index of the current
+ *     node has changed.
+ *
+ * If `visitor` is a single function, it will be called with all values
+ * encountered in the tree, including e.g. `null` values. Alternatively,
+ * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
+ * `Alias` and `Scalar` node. To define the same visitor function for more than
+ * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
+ * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
+ * specific defined one will be used for each node.
+ */
+async function visitAsync(node, visitor) {
+    const visitor_ = initVisitor(visitor);
+    if (identity.isDocument(node)) {
+        const cd = await visitAsync_(null, node.contents, visitor_, Object.freeze([node]));
+        if (cd === REMOVE)
+            node.contents = null;
+    }
+    else
+        await visitAsync_(null, node, visitor_, Object.freeze([]));
+}
+// Without the `as symbol` casts, TS declares these in the `visit`
+// namespace using `var`, but then complains about that because
+// `unique symbol` must be `const`.
+/** Terminate visit traversal completely */
+visitAsync.BREAK = BREAK;
+/** Do not visit the children of the current node */
+visitAsync.SKIP = SKIP;
+/** Remove the current node */
+visitAsync.REMOVE = REMOVE;
+async function visitAsync_(key, node, visitor, path) {
+    const ctrl = await callVisitor(key, node, visitor, path);
+    if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
+        replaceNode(key, path, ctrl);
+        return visitAsync_(key, ctrl, visitor, path);
+    }
+    if (typeof ctrl !== 'symbol') {
+        if (identity.isCollection(node)) {
+            path = Object.freeze(path.concat(node));
+            for (let i = 0; i < node.items.length; ++i) {
+                const ci = await visitAsync_(i, node.items[i], visitor, path);
+                if (typeof ci === 'number')
+                    i = ci - 1;
+                else if (ci === BREAK)
+                    return BREAK;
+                else if (ci === REMOVE) {
+                    node.items.splice(i, 1);
+                    i -= 1;
+                }
+            }
+        }
+        else if (identity.isPair(node)) {
+            path = Object.freeze(path.concat(node));
+            const ck = await visitAsync_('key', node.key, visitor, path);
+            if (ck === BREAK)
+                return BREAK;
+            else if (ck === REMOVE)
+                node.key = null;
+            const cv = await visitAsync_('value', node.value, visitor, path);
+            if (cv === BREAK)
+                return BREAK;
+            else if (cv === REMOVE)
+                node.value = null;
+        }
+    }
+    return ctrl;
+}
+function initVisitor(visitor) {
+    if (typeof visitor === 'object' &&
+        (visitor.Collection || visitor.Node || visitor.Value)) {
+        return Object.assign({
+            Alias: visitor.Node,
+            Map: visitor.Node,
+            Scalar: visitor.Node,
+            Seq: visitor.Node
+        }, visitor.Value && {
+            Map: visitor.Value,
+            Scalar: visitor.Value,
+            Seq: visitor.Value
+        }, visitor.Collection && {
+            Map: visitor.Collection,
+            Seq: visitor.Collection
+        }, visitor);
+    }
+    return visitor;
+}
+function callVisitor(key, node, visitor, path) {
+    if (typeof visitor === 'function')
+        return visitor(key, node, path);
+    if (identity.isMap(node))
+        return visitor.Map?.(key, node, path);
+    if (identity.isSeq(node))
+        return visitor.Seq?.(key, node, path);
+    if (identity.isPair(node))
+        return visitor.Pair?.(key, node, path);
+    if (identity.isScalar(node))
+        return visitor.Scalar?.(key, node, path);
+    if (identity.isAlias(node))
+        return visitor.Alias?.(key, node, path);
+    return undefined;
+}
+function replaceNode(key, path, node) {
+    const parent = path[path.length - 1];
+    if (identity.isCollection(parent)) {
+        parent.items[key] = node;
+    }
+    else if (identity.isPair(parent)) {
+        if (key === 'key')
+            parent.key = node;
+        else
+            parent.value = node;
+    }
+    else if (identity.isDocument(parent)) {
+        parent.contents = node;
+    }
+    else {
+        const pt = identity.isAlias(parent) ? 'alias' : 'scalar';
+        throw new Error(`Cannot replace node with ${pt} parent`);
+    }
+}
+
+exports.visit = visit;
+exports.visitAsync = visitAsync;

package/node_modules/yaml/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "yaml",
+  "version": "2.9.1",
+  "license": "ISC",
+  "author": "Eemeli Aro <eemeli@gmail.com>",
+  "funding": "https://github.com/sponsors/eemeli",
+  "repository": "github:eemeli/yaml",
+  "description": "JavaScript parser and stringifier for YAML",
+  "keywords": [
+    "YAML",
+    "parser",
+    "stringifier"
+  ],
+  "homepage": "https://eemeli.org/yaml/",
+  "files": [
+    "browser/",
+    "dist/",
+    "util.js"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "bin": "./bin.mjs",
+  "browser": {
+    "./dist/index.js": "./browser/index.js",
+    "./dist/util.js": "./browser/dist/util.js",
+    "./util.js": "./browser/dist/util.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "default": "./browser/index.js"
+    },
+    "./package.json": "./package.json",
+    "./util": {
+      "types": "./dist/util.d.ts",
+      "node": "./dist/util.js",
+      "default": "./browser/dist/util.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:node && npm run build:browser",
+    "build:browser": "rollup -c config/rollup.browser-config.mjs",
+    "build:node": "rollup -c config/rollup.node-config.mjs",
+    "clean": "git clean -fdxe node_modules",
+    "lint": "eslint config/ src/",
+    "prettier": "prettier --write .",
+    "prestart": "rollup --sourcemap -c config/rollup.node-config.mjs",
+    "start": "node --enable-source-maps -i -e 'YAML=require(\"./dist/index.js\");const{parse,parseDocument,parseAllDocuments}=YAML'",
+    "test": "jest --config config/jest.config.js",
+    "test:all": "npm test && npm run test:types && npm run test:dist && npm run test:dist:types",
+    "test:browsers": "cd playground && npm test",
+    "test:dist": "npm run build:node && jest --config config/jest.config.js",
+    "test:dist:types": "tsc --allowJs --moduleResolution node --noEmit --target es5 dist/index.js",
+    "test:types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
+    "docs:install": "cd docs-slate && bundle install",
+    "predocs:deploy": "node docs/prepare-docs.mjs",
+    "docs:deploy": "cd docs-slate && ./deploy.sh",
+    "predocs": "node docs/prepare-docs.mjs",
+    "docs": "cd docs-slate && bundle exec middleman server",
+    "preversion": "npm test && npm run build",
+    "prepublishOnly": "npm run clean && npm test && npm run build"
+  },
+  "browserslist": "defaults, not ie 11",
+  "prettier": {
+    "arrowParens": "avoid",
+    "semi": false,
+    "singleQuote": true,
+    "trailingComma": "none"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.12.10",
+    "@babel/plugin-transform-typescript": "^7.12.17",
+    "@babel/preset-env": "^7.12.11",
+    "@eslint/js": "^9.9.1",
+    "@rollup/plugin-babel": "^6.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-typescript": "^12.1.1",
+    "@types/jest": "^29.2.4",
+    "@types/node": "^20.11.20",
+    "babel-jest": "^29.0.1",
+    "eslint": "^9.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "fast-check": "^2.12.0",
+    "jest": "^29.0.1",
+    "jest-resolve": "^29.7.0",
+    "jest-ts-webcompat-resolver": "^1.0.0",
+    "prettier": "^3.0.2",
+    "rollup": "^4.12.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.4.0"
+  },
+  "engines": {
+    "node": ">= 14.6"
+  }
+}

package/node_modules/yaml/util.js

@@ -0,0 +1,2 @@
+// Re-exporter for Node.js < 12.16.0
+module.exports = require('./dist/util.js')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Halofy lifecycle installer and runtime for supported agents; runtime requests are signed with a per-installation Ed25519 key",
   "bin": {
@@ -29,5 +29,11 @@
   },
   "engines": {
     "node": ">=22"
-  }
+  },
+  "dependencies": {
+    "yaml": "2.9.1"
+  },
+  "bundleDependencies": [
+    "yaml"
+  ]
 }

package/src/claude-config.mjs

@@ -1,8 +1,11 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { readJson, writeHostConfigFile } from "./storage.mjs";
+import { managedContextName } from "./context-sync.mjs";
+import { managedSkillsDirectory } from "./skills-sync.mjs";
 
 const CLAUDE_HOOKS = Object.freeze({
+  PreToolUse: { matcher: "Skill", timeout: 8 },
   SessionStart: { matcher: "startup|resume|clear|compact", timeout: 15 },
   UserPromptSubmit: { timeout: 15 },
   Stop: { timeout: 20 },
@@ -45,6 +48,31 @@ function isManagedHalofyHook(hook) {
   return /(?:halofy-agent\.mjs\s+hook\s+|claude-code\/scripts\/(?:session-start|session-end|lifecycle-hook|mcp-router)\.mjs)/.test(command);
 }
 
+function mayHandleSkill(registration) {
+  if (!registration?.matcher || registration.matcher === "*") return true;
+  try { return new RegExp(registration.matcher).test("Skill"); }
+  catch { return true; }
+}
+
+/** Compatibility evidence only: command contents are not evaluated or removed. */
+async function skillGuardCompatibility(settingsPath, settings, root, home, env) {
+  const sources = [[settingsPath, settings]];
+  for (const path of new Set([join(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), "settings.json"), join(root, ".claude", "settings.local.json")])) {
+    if (path === settingsPath) continue;
+    sources.push([path, await readJson(path, {})]);
+  }
+  const overlappingHookSources = sources.filter(([, config]) => Array.isArray(config?.hooks?.PreToolUse)
+    && config.hooks.PreToolUse.some(registration => mayHandleSkill(registration)
+      && Array.isArray(registration.hooks) && registration.hooks.some(hook => !isManagedHalofyHook(hook))))
+    .map(([path]) => path);
+  return {
+    boundary: "Checks the exact Skill input presented to Halofy; requires trusted hook execution and no later trusted input rewrite.",
+    scanScope: "Project, project-local and user settings only; an empty overlap list does not verify plugin, managed or command-line hooks.",
+    overlappingHookSources,
+    ...(overlappingHookSources.length ? { warning: "Other configured hooks may handle Skill calls. Review compatibility: hooks that rewrite Skill input can bypass this check. Existing hooks were preserved; their presence does not prove input rewriting." } : {}),
+  };
+}
+
 function normalizedMcpUrl(entry) {
   const value = entry?.url || entry?.httpUrl || entry?.serverUrl;
   if (typeof value !== "string") return null;
@@ -86,6 +114,8 @@ export async function configureClaudeProject({
   nodePath = process.execPath,
   runtimePath,
   claudeConfigPath = join(homedir(), ".claude.json"),
+  home = homedir(),
+  env = process.env,
 }) {
   if (!/^[A-Za-z0-9_-]{1,160}$/.test(String(installationId))) throw new Error("invalid installation id");
   if (!runtimePath) throw new Error("installed runtime path is required");
@@ -103,11 +133,38 @@ export async function configureClaudeProject({
   };
 
   const settings = await readJson(settingsPath, {});
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+    throw new Error("invalid Claude settings; existing settings were preserved");
+  }
+  // Grant only this installation's delivered policy/knowledge references.
+  // Do not grant the entire skills tree, MCP tools, shell commands, or access
+  // to the runtime home (which holds credentials). Host ask/deny rules prevail.
+  const contextPath = resolve(managedSkillsDirectory("claude-code", { home, env }), managedContextName(installationId));
+  const normalizedPath = process.platform === "win32"
+    ? contextPath.replaceAll("\\", "/").replace(/^([A-Za-z]):/, (_, drive) => `/${drive.toLowerCase()}`)
+    : contextPath;
+  if (/[\u0000-\u001f\u007f*?\[\]{}()!\\]/.test(normalizedPath)) {
+    throw new Error("managed context path cannot be encoded as an exact Claude read permission");
+  }
+  if (settings.permissions !== undefined && (!settings.permissions || typeof settings.permissions !== "object" || Array.isArray(settings.permissions))) {
+    throw new Error("invalid Claude permissions; existing settings were preserved");
+  }
+  const permissions = settings.permissions ?? {};
+  if (permissions.allow !== undefined && (!Array.isArray(permissions.allow) || permissions.allow.some(rule => typeof rule !== "string"))) {
+    throw new Error("invalid Claude allow permissions; existing settings were preserved");
+  }
+  settings.permissions = { ...permissions, allow: [...new Set([
+    ...(permissions.allow ?? []), `Read(/${normalizedPath}/**)`,
+  ])] };
   settings.hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  const skillGuard = await skillGuardCompatibility(settingsPath, settings, root, home, env);
   for (const [eventName, definition] of Object.entries(CLAUDE_HOOKS)) {
     const current = Array.isArray(settings.hooks[eventName]) ? settings.hooks[eventName] : [];
-    const unrelated = current.filter((registration) =>
-      !Array.isArray(registration?.hooks) || !registration.hooks.some(isManagedHalofyHook));
+    const unrelated = current.flatMap((registration) => {
+      if (!Array.isArray(registration?.hooks)) return [registration];
+      const hooks = registration.hooks.filter(hook => !isManagedHalofyHook(hook));
+      return hooks.length ? [{ ...registration, hooks }] : [];
+    });
     settings.hooks[eventName] = [
       ...unrelated,
       managedHookRegistration(nodePath, runtimePath, eventName, installationId, definition),
@@ -134,6 +191,7 @@ export async function configureClaudeProject({
     mcpPath,
     settingsPath,
     hookEvents: Object.keys(CLAUDE_HOOKS),
+    skillGuard,
     replacedLegacyMcpEntries: replacedProjectMcpEntries + replacedClaudeMcpEntries,
   };
 }

package/src/claude-hook.mjs

@@ -1,3 +1,4 @@
+import { guardClaudeSkillInvocation, skillInvocationDenial } from "./skill-guard.mjs";
 import { captureStateSnapshot } from "./health.mjs";
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
@@ -12,6 +13,15 @@ export async function syncSkillsAtSessionStart(runtime, connection, root, stderr
   return result.skills;
 }
 
+/** Disjoint owned files and locks let instructions refresh without waiting for
+ * skill/reference downloads or their receipt. Both settle before capture work. */
+export async function syncConfigurationAtSessionStart(runtime, connection, root, stderr, syncOptions = {}) {
+  await Promise.allSettled([
+    Promise.resolve().then(() => runtime.syncInstructions?.()),
+    syncSkillsAtSessionStart(runtime, connection, root, stderr, syncOptions),
+  ]);
+}
+
 function id(value) {
   return createHash("sha256").update(String(value)).digest("hex");
 }
@@ -78,7 +88,7 @@ async function within(milliseconds, action) {
   }
 }
 
-/** Runs one reviewed Claude hook. Brownouts never block the host session. */
+/** Capture brownouts do not block sessions; managed Skill verification denies on missing evidence. */
 export async function runClaudeLifecycleHook(connection, eventName, {
   input,
   root = defaultRuntimeDirectory(),
@@ -90,15 +100,19 @@ export async function runClaudeLifecycleHook(connection, eventName, {
 } = {}) {
   try {
     const hookInput = input ?? await readHookInput();
+    if (eventName === "PreToolUse") {
+      const decision = await guardClaudeSkillInvocation({ connection, root, input: hookInput, home, env });
+      if (decision) stdout.write(JSON.stringify(decision));
+      return { handled: true, denied: Boolean(decision) };
+    }
     const session = hostSession(hookInput);
     if (!session) return { handled: true };
     const capture = await captureStateSnapshot(root, connection.installationId);
     const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
     if (capture.paused) {
       if (eventName === "SessionStart") {
-        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 (eventName === "UserPromptSubmit") {
         const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
@@ -110,9 +124,7 @@ export async function runClaudeLifecycleHook(connection, eventName, {
 
     if (eventName === "SessionStart") {
       // 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) {
@@ -190,6 +202,7 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     }
     return { handled: true };
   } catch (error) {
+    if (eventName === "PreToolUse") stdout.write(JSON.stringify(skillInvocationDenial()));
     const code = error && typeof error === "object" && typeof error.code === "string"
       ? error.code : "runtime_unavailable";
     stderr.write(`[halofy] lifecycle hook degraded: ${code}\n`);

package/src/client-registry.mjs

@@ -6,6 +6,7 @@ export const CLIENT_KINDS = Object.freeze([
   "cline",
   "gemini-cli",
   "kimi-cli",
+  "hermes-agents",
 ]);
 
 const BASE_CAPABILITIES = Object.freeze({
@@ -44,6 +45,18 @@ function capabilities(overrides) {
 }
 
 export const CLIENT_REGISTRY = Object.freeze({
+  "hermes-agents": Object.freeze({
+    clientKind: "hermes-agents",
+    label: "Hermes Agents",
+    command: "hermes",
+    coverage: "partial",
+    reason: "reviewed_hooks_only_interrupted_output_and_compaction_unavailable",
+    capabilities: capabilities({
+      sessionStart: true, userPromptSubmit: true, stop: true, sessionEnd: true,
+      postToolUse: true, postToolUseFailure: true, userMessages: true,
+      assistantMessages: true, toolInputs: true, toolOutputs: true, toolFailures: true,
+    }),
+  }),
   "claude-code": Object.freeze({
     clientKind: "claude-code",
     label: "Claude Code",

package/src/delivery-sync.mjs

@@ -7,6 +7,20 @@ import { retirePredecessorContent } from "./predecessor-sync.mjs";
 import { writePrivateFile } from "./storage.mjs";
 
 export const DELIVERY_NOTICE = "Halofy managed policies, skills, or knowledge references changed during this conversation. Start a new session to load the current references; previously loaded content may be outdated. File delivery does not confirm policy compliance.";
+
+/** Explicit file refresh for hosts/modes without observed lifecycle hooks.
+ * Never fabricate a host session or enqueue/capture conversation events. */
+export async function refreshManagedConfiguration(runtime, connection, root, { stderr = process.stderr, ...options } = {}) {
+  const [instructions, delivery] = await Promise.allSettled([
+    Promise.resolve().then(() => runtime.syncInstructions()),
+    syncManagedDelivery({ ...options, connection, transport: runtime.transport, root, stderr, phase: "start" }),
+  ]);
+  const instructionStatus = instructions.status === "fulfilled" ? instructions.value?.status ?? "unavailable" : "unavailable";
+  const deliveryOutcome = delivery.status === "fulfilled" ? delivery.value.outcome : "failed";
+  const acknowledged = delivery.status === "fulfilled" && delivery.value.acknowledged === true;
+  return { instructionStatus, deliveryOutcome, acknowledged,
+    ready: ["installed", "pending_restart"].includes(instructionStatus) && deliveryOutcome === "synced" && acknowledged };
+}
 const SHA = /^[a-f0-9]{64}$/;
 const ID = /^[A-Za-z0-9_-]{1,160}$/;
 

package/src/health.mjs

@@ -28,6 +28,15 @@ export async function captureAdmission(root, installationId, generation) {
 
 /** Local-only install metadata. Never send paths or commands as health evidence. */
 export async function recordHealthTargets({ root, installationId, configured, runtimePath }) {
+  if (configured.hermes) {
+    const { inspectHermesCaptureHealth } = await import("./hermes-health.mjs");
+    if ((await inspectHermesCaptureHealth(configured.hermes)).captureState !== "active") {
+      throw new Error("managed Hermes hook inspection metadata incomplete");
+    }
+    await writePrivateFile(targetsPath(root, installationId), JSON.stringify({ version: 1, runtimePath,
+      targets: [{ kind: "hermes", ...configured.hermes }] }));
+    return;
+  }
   const paths = configured.configuredPaths || [configured.mcpPath, configured.settingsPath];
   const targets = [];
   const foundEvents = new Set();
@@ -74,6 +83,12 @@ export async function inspectCaptureHealth(connection, root) {
   try {
     if (!(await stat(metadata.runtimePath)).isFile()) return { captureState: "hooks_missing" };
     for (const target of metadata.targets) {
+      if (target.kind === "hermes") {
+        const { inspectHermesCaptureHealth } = await import("./hermes-health.mjs");
+        const result = await inspectHermesCaptureHealth(target);
+        if (result.captureState !== "active") return result;
+        continue;
+      }
       const text = await readFile(target.path, "utf8");
       if (target.kind === "json") {
         const value = JSON.parse(text);