@halofy/agent-connect 0.12.1 → 0.13.1

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({

package/src/instructions.mjs

@@ -136,7 +136,11 @@ async function targetFor(connection, owner) {
 function render(bundle, owner, cursor) {
   const begin = `${MARKER}${owner}:BEGIN -->`;
   const end = `${MARKER}${owner}:END -->`;
-  const content = bundle.documents.map((doc) => `## ${doc.title}\n\n${doc.content}`).join("\n\n");
+  const content = bundle.documents.map((doc) => {
+    // Preserve the authored bytes; omit only our redundant display heading.
+    const heading = doc.content.trimStart().split(/\r?\n/, 1)[0].match(/^#{1,6}\s+(.+?)(?:\s+#+)?\s*$/);
+    return heading?.[1] === doc.title ? doc.content : `## ${doc.title}\n\n${doc.content}`;
+  }).join("\n\n");
   const text = `${cursor ? "---\nalwaysApply: true\n---\n" : ""}${begin}\n# Organization agent instructions\n\n${content}\n${end}\n`;
   return { begin: Buffer.from(begin), end: Buffer.from(end), bytes: Buffer.from(text) };
 }

package/src/runtime.mjs

@@ -11,6 +11,21 @@ import { readJson, withFileLock, writePrivateFile } from "./storage.mjs";
 import { capturePaused, captureStateSnapshot, captureAdmission, inspectCaptureHealth } from "./health.mjs";
 import { syncAgentInstructions } from "./instructions.mjs";
 import { RUNTIME_VERSION } from "./version.mjs";
+import { isActiveInstallation } from "./active.mjs";
+
+function acknowledgedPrefix(response, batchLength) {
+  const accepted = response?.acceptedCount !== undefined ? response.acceptedCount
+    : response?.acceptedPrefix !== undefined ? response.acceptedPrefix : response?.accepted;
+  const duplicates = response?.acceptedCount === undefined && response?.acceptedPrefix === undefined
+    ? (response?.duplicates ?? 0) : 0;
+  if (!Number.isSafeInteger(accepted) || accepted < 0 ||
+      !Number.isSafeInteger(duplicates) || duplicates < 0 || accepted + duplicates > batchLength) {
+    const error = new Error("append response did not acknowledge a valid event prefix");
+    error.code = "invalid_append_acknowledgement";
+    throw error;
+  }
+  return accepted + duplicates;
+}
 
 export class LifecycleRuntime {
   constructor(connection, {
@@ -177,7 +192,8 @@ export class LifecycleRuntime {
       if (usageGaps > 0) await this.cursors.bumpUsageGaps(usageGaps);
       return result;
     });
-    if (queued.queued === 0) return { queued: 0, acknowledged: 0 };
+    // A previous hook may have persisted this entire suffix before its append
+    // failed. Retry that durable queue even when there are no new host records.
     const replay = await this.replay();
     return { queued: queued.queued, acknowledged: replay.acknowledged };
   }
@@ -228,13 +244,20 @@ export class LifecycleRuntime {
     await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
   }
 
-  async replay() {
-    return withFileLock(this.operationLockPath, () => this.#replayUnlocked());
+  async replay({ maxBatches = Number.MAX_SAFE_INTEGER, onlyWhileActive = false } = {}) {
+    if (!Number.isSafeInteger(maxBatches) || maxBatches < 1) throw new Error("invalid replay batch limit");
+    return withFileLock(this.operationLockPath, async () => {
+      if (onlyWhileActive && (await capturePaused(this.root, this.connection.installationId) ||
+          !await isActiveInstallation(this.connection, this.root))) {
+        return { acknowledged: 0, ...(await this.queue.diagnostics()) };
+      }
+      return this.#replayUnlocked(maxBatches);
+    });
   }
 
-  async #replayUnlocked() {
+  async #replayUnlocked(maxBatches = Number.MAX_SAFE_INTEGER) {
     let acknowledged = 0;
-    while (true) {
+    for (let batch = 0; batch < maxBatches; batch += 1) {
       const head = await this.queue.peek();
       if (!head) break;
       const sessionId = await this.resolveSessionByHash(head.sessionHash);
@@ -244,23 +267,11 @@ export class LifecycleRuntime {
         payloadSha256,
         ...event
       }) => ({ ...event, eventId: eventKey })));
-      const accepted = Math.max(0, Math.min(
-        head.events.length,
-        Number(response?.acceptedCount ?? response?.acceptedPrefix ??
-          (response?.accepted === undefined ? head.events.length : Number(response.accepted) + Number(response.duplicates ?? 0))),
-      ));
-      if (accepted === 0) {
-        if (Number.isSafeInteger(response?.nextExpectedSequence)) {
-          const expected = response.nextExpectedSequence;
-          const firstExpected = head.events.findIndex((event) => event.sequence >= expected);
-          if (firstExpected > 0) {
-            await this.#acknowledge(head, firstExpected);
-            acknowledged += firstExpected;
-            continue;
-          }
-        }
-        break;
-      }
+      // A success HTTP status or an advanced server cursor is insufficient:
+      // the prefix must be explicitly accepted or confirmed as duplicates.
+      // In particular, event_conflict must retain the rejected local bodies.
+      const accepted = acknowledgedPrefix(response, head.events.length);
+      if (accepted === 0) break;
       await this.#acknowledge(head, accepted);
       acknowledged += accepted;
     }

package/src/skill-guard.mjs

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { safeDirectory, writePrivateFile } from "./storage.mjs";
+import { readPrivateJson, withContextLock } from "./context-sync.mjs";
+import { loadSkillsManifest, managedSkillsDirectory, readManagedSkillTuples } from "./skills-sync.mjs";
+import { SignedRuntimeTransport } from "./transport.mjs";
+
+const PREFIX = "halofy-managed-";
+const ID = /^[A-Za-z0-9_-]{1,160}$/;
+const KEY = /^[a-z0-9][a-z0-9._-]{0,199}$/i;
+const SHA = /^[a-f0-9]{64}$/;
+const hash = value => createHash("sha256").update(value).digest("hex");
+const enabled = connection => connection.clientKind === "claude-code" && connection.skillGuardVersion === 1;
+const stateRoot = root => join(root, "claude-skill-guard");
+const validEntry = entry => entry && ID.test(entry.installationId) && ID.test(entry.skillId)
+  && KEY.test(entry.skillKey) && !entry.skillKey.includes("..") && SHA.test(entry.sha)
+  && entry.nativeSkillKey === guardedSkillName({ installationId: entry.installationId }, entry);
+
+/** Native identity is immutable across updates, restores and reconnects. */
+export function guardedSkillName(connection, skill) {
+  return `${PREFIX}${hash(JSON.stringify([connection.installationId, skill.skillId, skill.sha])).slice(0, 40)}`;
+}
+export function managedNativeSkillKey(connection, skill) {
+  return enabled(connection) ? guardedSkillName(connection, skill) : skill.skillKey;
+}
+
+async function readHistory(root) {
+  const dir = stateRoot(root);
+  await safeDirectory(dir);
+  for (const name of ["initialized.json", "history.json"]) {
+    const entry = await lstat(join(dir, name));
+    if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 4 * 1024 * 1024) throw new Error("invalid skill guard evidence");
+  }
+  const anchor = await readPrivateJson(join(dir, "initialized.json"));
+  const history = await readPrivateJson(join(dir, "history.json"));
+  if (anchor?.version !== 1 || history?.version !== 1 || !Array.isArray(history.entries)
+    || !Array.isArray(history.legacyKeys) || history.entries.length > 10000 || history.legacyKeys.length > 10000
+    || history.entries.some(entry => !validEntry(entry))
+    || history.legacyKeys.some(key => typeof key !== "string" || !KEY.test(key) || key.includes(".."))
+    || new Set(history.entries.map(entry => entry.nativeSkillKey)).size !== history.entries.length) {
+    throw new Error("invalid skill guard evidence");
+  }
+  return history;
+}
+
+/** Explicit installer bootstrap only. Hook/sync reads never reset missing history. */
+export async function initializeSkillGuard(root) {
+  const dir = stateRoot(root);
+  await safeDirectory(dir, true);
+  return withContextLock(dir, async () => {
+    const names = await readdir(dir);
+    if (names.includes("initialized.json") || names.includes("history.json")) return readHistory(root);
+    const connections = await readdir(join(root, "connections")).catch(error => {
+      if (error.code === "ENOENT") return []; throw error;
+    });
+    if (connections.length > 1000) throw new Error("skill guard connection limit");
+    const legacyKeys = new Set();
+    for (const name of connections) {
+      if (!/^[A-Za-z0-9_-]{1,160}\.json$/.test(name)) continue;
+      const connection = await readPrivateJson(join(root, "connections", name));
+      if (connection?.clientKind !== "claude-code") continue;
+      if (connection.skillGuardVersion === 1) throw new Error("missing initialized skill history");
+      const manifest = await loadSkillsManifest(root, connection.installationId);
+      for (const entry of manifest.installs) legacyKeys.add(entry.skillKey);
+      // Pre-guard runtimes removed manifest entries after withdrawal, but kept
+      // owned directories in quarantine. Preserve those legacy cache identities.
+      const quarantine = join(root, "skills-quarantine", connection.installationId);
+      let withdrawn = [];
+      try { await safeDirectory(quarantine); withdrawn = await readdir(quarantine); }
+      catch (error) { if (error.code !== "ENOENT" && error.code !== "directory_missing") throw error; }
+      if (withdrawn.length > 10000) throw new Error("legacy skill history limit");
+      for (const name of withdrawn) {
+        const match = /^(.+)-[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{3}Z$/.exec(name);
+        if (!match || !KEY.test(match[1]) || match[1].includes("..")) throw new Error("unrecognized legacy quarantine");
+        await safeDirectory(join(quarantine, name));
+        legacyKeys.add(match[1]);
+      }
+    }
+    if (legacyKeys.size > 10000) throw new Error("legacy skill history limit");
+    const history = { version: 1, entries: [], legacyKeys: [...legacyKeys] };
+    await writePrivateFile(join(dir, "history.json"), JSON.stringify(history));
+    await writePrivateFile(join(dir, "initialized.json"), JSON.stringify({ version: 1 }));
+    return history;
+  });
+}
+
+/** Record ownership before activation/withdrawal; records are never removed. */
+export async function recordSkillOwnership(connection, root, entries) {
+  if (!enabled(connection)) return;
+  const dir = stateRoot(root);
+  await safeDirectory(dir);
+  await withContextLock(dir, async () => {
+    const history = await readHistory(root);
+    for (const entry of entries) {
+      if (!entry.nativeSkillKey) {
+        if (!history.legacyKeys.includes(entry.skillKey)) history.legacyKeys.push(entry.skillKey);
+      } else {
+        const record = { installationId: connection.installationId, skillId: entry.skillId,
+          skillKey: entry.skillKey, sha: entry.sha, nativeSkillKey: entry.nativeSkillKey };
+        if (!validEntry(record)) throw new Error("invalid owned skill");
+        if (!history.entries.some(item => item.nativeSkillKey === record.nativeSkillKey)) history.entries.push(record);
+      }
+    }
+    if (history.entries.length > 10000 || history.legacyKeys.length > 10000) throw new Error("skill guard history limit");
+    await writePrivateFile(join(dir, "history.json"), JSON.stringify(history));
+  });
+}
+
+export function skillInvocationDenial(reason = "This Halofy managed skill is withdrawn, changed, or could not be verified. Refresh Halofy and start a new conversation before using it.") {
+  return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny",
+    permissionDecisionReason: reason } };
+}
+
+/** No allow decision: host permissions retain their normal authority. */
+async function checkClaudeSkillInvocation({ connection, root, input, home, env, transport, signal }) {
+  if (typeof input?.tool_name === "string" && input.tool_name !== "Skill") return null;
+  try {
+    if (typeof input.tool_input?.skill !== "string") throw new Error("missing skill identity");
+    // Claude trims native names before resolving cached plain-name skills.
+    const name = input.tool_input.skill.trim().replace(/^\//, "").trim().toLowerCase();
+    let history;
+    try { history = await readHistory(root); }
+    catch { return skillInvocationDenial("Halofy skill ownership evidence is unavailable; managed and employee skills cannot be safely distinguished. Skill calls are paused. Ask your administrator to restore verified ownership history or review the reconnect migration; do not recreate an empty history."); }
+    if (history.legacyKeys.some(key => key.toLowerCase() === name)) return skillInvocationDenial();
+    const owned = history.entries.find(entry => entry.nativeSkillKey === name);
+    if (!owned && !name.startsWith(PREFIX)) return null;
+    if (!owned || !enabled(connection) || owned.installationId !== connection.installationId) throw new Error("unknown managed skill");
+    const active = async () => {
+      await safeDirectory(root);
+      const marker = await readPrivateJson(join(root, "active-claude-code.json"));
+      return marker?.installationId === connection.installationId && marker?.protocolVersion === "1";
+    };
+    if (!(await active())) throw new Error("inactive installation");
+    const manifest = await loadSkillsManifest(root, connection.installationId);
+    const local = manifest.installs.find(entry => entry.nativeSkillKey === name && entry.skillId === owned.skillId && entry.sha === owned.sha);
+    if (!local) throw new Error("withdrawn managed copy");
+    // Verify all recorded bytes, then verify the exact local alias again after the network read.
+    await readManagedSkillTuples({ connection, root, home, env });
+    const current = await (transport ?? new SignedRuntimeTransport(connection, { timeoutMs: 3000, signal }))
+      .skillsCheckin([{ skillId: owned.skillId, sha: owned.sha }]);
+    if (!Array.isArray(current?.items) || current.items.length !== 1
+      || current.items[0].skillId !== owned.skillId || current.items[0].status !== "approved"
+      || !Array.isArray(current.skills) || !current.skills.some(entry => entry.skillId === owned.skillId
+        && entry.skillKey === owned.skillKey && entry.sha === owned.sha)) throw new Error("skill no longer eligible");
+    const path = join(managedSkillsDirectory("claude-code", { home, env }), name, "SKILL.md");
+    const bytes = await readFile(path);
+    if (hash(bytes) !== local.fileSha256 || !(await active())) throw new Error("changed managed copy");
+    await readManagedSkillTuples({ connection, root, home, env });
+    const latest = await loadSkillsManifest(root, connection.installationId);
+    if (!latest.installs.some(entry => entry.nativeSkillKey === name && entry.skillId === owned.skillId && entry.sha === owned.sha)) throw new Error("withdrawn during check");
+    await readHistory(root);
+    return null;
+  } catch { return skillInvocationDenial(); }
+}
+
+/** Bound the entire guard, including local reads, below the native hook timeout.
+ * The CLI flushes and exits after this decision so stuck filesystem work cannot
+ * turn a host timeout into a fail-open native invocation. */
+export async function guardClaudeSkillInvocation(options) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    return await Promise.race([
+      checkClaudeSkillInvocation({ ...options, signal: controller.signal }),
+      new Promise(resolve => { timer = setTimeout(() => {
+        controller.abort(); resolve(skillInvocationDenial());
+      }, 4500); }),
+    ]);
+  } finally { clearTimeout(timer); controller.abort(); }
+}

package/src/skills-sync.mjs

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, lstat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
+import { managedNativeSkillKey, recordSkillOwnership } from "./skill-guard.mjs";
 import { isActiveInstallation } from "./active.mjs";
 import { ensurePrivateDirectory, readJson, safeDirectory, writePrivateFile } from "./storage.mjs";
 
@@ -11,11 +12,12 @@ import { ensurePrivateDirectory, readJson, safeDirectory, writePrivateFile } fro
  * skill on its team + org chain; this module mirrors that set into the host's
  * own skills folder and keeps it there.
  *
- * Every managed copy is written as `<skillsRoot>/<skillKey>/SKILL.md`, the
+ * Every managed copy is written as `<skillsRoot>/<nativeSkillKey>/SKILL.md`, the
  * layout Claude Code and Codex both read. A manifest under the runtime home
  * records what was written (id, sha, file digest) so the next check-in can
  * report it, drift can be repaired, and a withdrawn skill can be quarantined
  * — moved, never deleted (D7 on the client mirror).
+ * Guarded Claude installs use immutable aliases; other hosts use skillKey.
  *
  * A folder this runtime did not create is never touched: an employee's own
  * skill with a colliding name is reported as a conflict and left alone.
@@ -111,15 +113,16 @@ export async function loadSkillsManifest(root, installationId) {
   if (!manifestFile) return { version: 1, installationId, installs: [], lastCheckinAt: null };
   if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.installs)) throw new Error("invalid skill manifest");
   if (manifest.installationId !== installationId || manifest.installs.some((entry) =>
-    !safeKey(entry?.skillKey) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha))) throw new Error("invalid skill manifest");
+    !safeKey(entry?.skillKey) || (entry.nativeSkillKey !== undefined && !safeKey(entry.nativeSkillKey)) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha))) throw new Error("invalid skill manifest");
   return manifest;
 }
 
 /**
  * One sync pass. Never throws for server or filesystem trouble on a single
  * skill; the summary names what happened so callers (installer, SessionStart
- * hooks) can report it. A failed check-in leaves installed copies usable
- * until the 7-day staleness allowance runs out, then quarantines them (D37).
+ * hooks) can report it. A failed check-in retains installed copies until the
+ * 7-day staleness allowance runs out, then quarantines them (D37). Retention
+ * is not invocation permission: guarded Claude calls require a fresh check.
  */
 export async function syncManagedSkills({
   connection,
@@ -150,6 +153,7 @@ export async function syncManagedSkills({
   const quarantineRoot = join(root, "skills-quarantine", connection.installationId);
   const manifest = await loadSkillsManifest(root, connection.installationId);
   const current = now();
+  await recordSkillOwnership(connection, root, manifest.installs);
 
   const active = () => isActiveInstallation(connection, root);
   if (!(await active())) {
@@ -176,7 +180,7 @@ export async function syncManagedSkills({
       const failedWithdrawals = [];
       for (const entry of manifest.installs) {
         try {
-          const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
+          const moved = await quarantine(skillsRoot, quarantineRoot, entry.nativeSkillKey || entry.skillKey, current);
           if (moved) summary.quarantined.push({ skillKey: entry.skillKey, reason: "stale_checkin", to: moved });
         } catch (fsError) {
           failedWithdrawals.push(entry);
@@ -202,10 +206,12 @@ export async function syncManagedSkills({
   for (const entry of manifest.installs) {
     const verdict = verdicts.get(entry.skillId);
     const status = verdict?.status;
-    const withdrawn = status === "revoked" || status === "unknown" || (!wanted.has(entry.skillId) && status !== "stale");
+    const desired = wanted.get(entry.skillId) ?? wanted.get(verdict?.currentSkillId);
+    const renamed = desired && (entry.nativeSkillKey || entry.skillKey) !== managedNativeSkillKey(connection, desired);
+    const withdrawn = renamed || status === "revoked" || status === "unknown" || (!wanted.has(entry.skillId) && status !== "stale");
     if (!withdrawn) { survivors.push(entry); continue; }
     try {
-      const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
+      const moved = await quarantine(skillsRoot, quarantineRoot, entry.nativeSkillKey || entry.skillKey, current);
       summary.quarantined.push({ skillKey: entry.skillKey, reason: status || "not_resolved", to: moved });
     } catch (error) {
       summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: error?.code || "fs_error" });
@@ -220,14 +226,15 @@ export async function syncManagedSkills({
   //    to the row that replaced it.
   for (const entry of manifest.installs) {
     const verdict = verdicts.get(entry.skillId);
-    if (verdict?.status === "stale" && verdict.currentSkillId && !wanted.has(entry.skillId)) {
+    if (connection.skillGuardVersion !== 1 && verdict?.status === "stale" && verdict.currentSkillId && !wanted.has(entry.skillId)) {
       entry.skillId = verdict.currentSkillId;
     }
   }
   const next = [...failedWithdrawals];
   for (const skill of wanted.values()) {
-    const entry = manifest.installs.find((candidate) => candidate.skillId === skill.skillId);
-    const dir = join(skillsRoot, skill.skillKey);
+    const entry = manifest.installs.find((candidate) => candidate.skillId === skill.skillId && (candidate.nativeSkillKey || candidate.skillKey) === managedNativeSkillKey(connection, skill));
+    const nativeSkillKey = managedNativeSkillKey(connection, skill);
+    const dir = join(skillsRoot, nativeSkillKey);
     const file = join(dir, "SKILL.md");
     if (!(await active())) {
       summary.errors.push({ stage: "download", code: "inactive_installation" });
@@ -246,17 +253,24 @@ export async function syncManagedSkills({
       next.push({ ...entry, lastCheckinAt: current.toISOString() });
       continue;
     }
-    if (!(await isManaged(skillsRoot, skill.skillKey, entry)) && (await pathState(dir))) {
+    if (!(await isManaged(skillsRoot, nativeSkillKey, entry)) && (await pathState(dir))) {
       summary.conflicts.push({ skillKey: skill.skillKey, reason: "unmanaged_folder" });
       continue;
     }
     try {
       const exported = await transport.skillDownload(skill.skillId);
-      const content = typeof exported?.content === "string" ? exported.content : null;
+      let content = typeof exported?.content === "string" ? exported.content : null;
       if (!content) throw Object.assign(new Error("skill export was empty"), { code: "empty_export" });
       if (!content.startsWith("---\n") || !content.split("\n---\n")[0].split("\n").includes(`content_sha256: ${skill.sha}`)) {
         throw Object.assign(new Error("skill digest mismatch"), { code: "skill_digest_mismatch" });
       }
+      if (connection.clientKind === "claude-code" && connection.skillGuardVersion === 1) {
+        const boundary = content.indexOf("\n---\n");
+        const frontmatter = content.slice(0, boundary);
+        if ((frontmatter.match(/^name:.*$/gm) || []).length !== 1) throw new Error("missing native skill name");
+        content = frontmatter.replace(/^name:.*$/m, `name: ${nativeSkillKey}`) + content.slice(boundary);
+        await recordSkillOwnership(connection, root, [{ ...skill, nativeSkillKey }]);
+      }
       if (!(await active())) throw Object.assign(new Error("inactive installation"), { code: "inactive_installation" });
       await safeDirectory(dir, true);
       if ((await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill file");
@@ -264,6 +278,7 @@ export async function syncManagedSkills({
       const record = {
         skillId: skill.skillId,
         skillKey: skill.skillKey,
+        ...(nativeSkillKey !== skill.skillKey ? { nativeSkillKey } : {}),
         sha: skill.sha,
         fileSha256: digest(content),
         namespace: skill.namespace,
@@ -325,8 +340,8 @@ export async function readManagedSkillTuples({ connection, root, home = homedir(
   if (manifest.installationId !== connection.installationId || !manifest.lastCheckinAt) throw new Error("incomplete skill evidence");
   for (const entry of manifest.installs) {
     if (!safeKey(entry.skillKey) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha)) throw new Error("invalid skill evidence");
-    const dir = join(skillsRoot, entry.skillKey), file = join(dir, "SKILL.md");
-    if ((await pathState(dir))?.isSymbolicLink() || (await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill evidence");
+    const dir = join(skillsRoot, entry.nativeSkillKey || entry.skillKey), file = join(dir, "SKILL.md");
+    if (!(await pathState(dir))?.isDirectory() || !(await pathState(file))?.isFile() || (await pathState(dir))?.isSymbolicLink() || (await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill evidence");
     const content = await readText(file);
     const separator = content?.indexOf("\n---\n\n");
     // The export wrapper adds exactly one blank line and one terminal newline.
@@ -343,14 +358,15 @@ export async function retireManagedSkills({ connection, root, home = homedir(),
   const skillsRoot = managedSkillsDirectory(connection.clientKind, { home, env });
   if (!skillsRoot) return;
   const manifest = await loadSkillsManifest(root, connection.installationId);
+  await recordSkillOwnership(connection, root, manifest.installs);
   if (!manifest.installs.length) return;
   await safeDirectory(skillsRoot);
   for (const entry of manifest.installs) {
-    const dir = join(skillsRoot, entry.skillKey);
+    const dir = join(skillsRoot, entry.nativeSkillKey || entry.skillKey);
     const disk = await pathState(dir);
     if (!disk) continue;
     if (disk.isSymbolicLink() || !disk.isDirectory()) throw new Error("unsafe predecessor skill");
-    await quarantine(skillsRoot, join(root, "skills-quarantine", connection.installationId), entry.skillKey, now());
+    await quarantine(skillsRoot, join(root, "skills-quarantine", connection.installationId), entry.nativeSkillKey || entry.skillKey, now());
   }
   manifest.installs = [];
   await writePrivateFile(skillsManifestPath(root, connection.installationId), `${JSON.stringify(manifest, null, 2)}\n`);

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.12.1";
-export const RUNTIME_VERSION = "0.12.1";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-10.1";
+export const INSTALLER_VERSION = "0.13.1";
+export const RUNTIME_VERSION = "0.13.1";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-17.1";