@halofy/agent-connect 0.8.0 → 0.9.0

package/README.md

@@ -25,7 +25,7 @@ bounded recall block formats stay in place and tested for when it returns.
 There is one setup path for every packaged client:
 
 ```bash
-npx --yes @halofy/agent-connect@0.8.0 install <client-kind> \
+npx --yes @halofy/agent-connect@0.9.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -128,3 +128,30 @@ heartbeat. Older backends report context unavailable until the matching backend
 release is deployed. Reconnect to install this runtime on existing connections.
 Reconnection retires the previous active installation's owned context. Older
 project hooks consult the active host marker and cannot restore that retired copy.
+
+
+## Scoped badge delivery receipts (0.9.0)
+
+This version adds signed `/v1/agent-runtime/delivery/check` and
+`/v1/agent-runtime/delivery/receipt` requests. Installation and session-start
+refreshes report a content-free version calculated from the complete activated
+policy/knowledge set and installed skill manifest. Incomplete discovery, local
+conflicts, unavailable downloads and unsupported hosts cannot acknowledge synced.
+Updates and removals use the existing scoped delivery routes and native folders.
+
+Supported user-turn hooks check current eligibility before continuing. An
+unchanged version avoids content downloads. A changed version refreshes the
+managed copies and reports `restart_required`; supported hook output includes a
+fixed notice asking for a new session. Cursor's before-submit hook has no reviewed
+context-injection output, so it receives manager-visible receipt status without
+an injected notice. A successful subsequent session-start refresh clears the
+restart requirement. All delivery passes serialize per installation, including
+separate hook processes; replaced installations cannot restore managed copies.
+
+Manager statuses are Not connected, Synced, Sync pending and Needs attention.
+Receipts confirm file delivery only, never host loading or policy compliance.
+Older servers retain installation/session-start refresh behavior but cannot
+confirm delivery status. Existing offline skill limits remain; context refresh
+failures withdraw the managed references. These are source capabilities; package
+publication, installed-client upgrades and production deployment require separate
+release verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Halofy lifecycle installer and runtime for supported agents; runtime requests are signed with a per-installation Ed25519 key",
   "bin": {

package/src/active.mjs

@@ -13,3 +13,11 @@ export async function hasLifecycleMarker(clientKind = "claude-code", root = defa
   const marker = await readJson(join(root, `active-${clientKind}.json`));
   return Boolean(marker?.installationId && marker.protocolVersion !== "legacy");
 }
+
+/** Missing markers support legacy installs; corrupt/replaced markers fail closed. */
+export async function isActiveInstallation(connection, root) {
+  try {
+    const marker = await readJson(join(root, `active-${connection.clientKind}.json`));
+    return !marker || marker.installationId === connection.installationId;
+  } catch { return false; }
+}

package/src/claude-hook.mjs

@@ -1,53 +1,14 @@
 import { createHash } from "node:crypto";
-import { basename, join } from "node:path";
+import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
 import { normalizeClaudeHookEvent, RECALL_INJECTION_ENABLED, rankedRecallBlocks } from "./session.mjs";
-import { defaultRuntimeDirectory, readJson } from "./storage.mjs";
-import { describeSkillSync, syncManagedSkills } from "./skills-sync.mjs";
-import { describeContextSync, syncManagedContext } from "./context-sync.mjs";
+import { defaultRuntimeDirectory } from "./storage.mjs";
+import { syncManagedDelivery } from "./delivery-sync.mjs";
 
-/**
- * Badge skills ride the SessionStart heartbeat (D37): check in, repair, and
- * quarantine, but never let a skills problem degrade memory recall.
- */
+/** Shared delivery refresh remains independent of capture/heartbeat brownouts. */
 export async function syncSkillsAtSessionStart(runtime, connection, root, stderr, syncOptions = {}) {
-  let active;
-  try {
-    active = await readJson(join(root, `active-${connection.clientKind}.json`));
-  } catch {
-    active = { installationId: null };
-  }
-  // Replaced project hooks may still execute. They can retire their copy but
-  // cannot restore content after this host's active installation changed.
-  if (active && active.installationId !== connection.installationId) {
-    const retired = await syncManagedContext({ connection, root, ...syncOptions,
-      transport: { contextPage: async () => ({ items: [], nextCursor: null }) },
-    });
-    stderr.write(`[halofy] inactive installation context: ${describeContextSync(retired)}\n`);
-    return null;
-  }
-  try {
-    const context = await syncManagedContext({ connection, transport: runtime.transport, root, ...syncOptions,
-      canActivate: async () => {
-        const marker = await readJson(join(root, `active-${connection.clientKind}.json`));
-        return !marker || marker.installationId === connection.installationId;
-      },
-    });
-    stderr.write(`[halofy] ${describeContextSync(context)}\n`);
-  } catch (error) {
-    stderr.write(`[halofy] policy and knowledge sync degraded: ${error?.code || "runtime_unavailable"}\n`);
-  }
-  try {
-    const summary = await syncManagedSkills({ connection, transport: runtime.transport, root, ...syncOptions });
-    if (summary.supported && (summary.installed.length || summary.updated.length ||
-        summary.quarantined.length || summary.errors.length)) {
-      stderr.write(`[halofy] ${describeSkillSync(summary)}\n`);
-    }
-    return summary;
-  } catch (error) {
-    stderr.write(`[halofy] skill sync degraded: ${error?.code || "runtime_unavailable"}\n`);
-    return null;
-  }
+  const result = await syncManagedDelivery({ ...syncOptions, connection, transport: runtime.transport, root, stderr, phase: "start" });
+  return result.skills;
 }
 
 function id(value) {
@@ -87,13 +48,13 @@ function childSession(input) {
   return child ? `${parent}:subagent:${child}` : parent;
 }
 
-function recallText(result, eventName) {
+function recallText(result, eventName, notice) {
   const rankedBlocks = rankedRecallBlocks(result);
-  if (rankedBlocks.length === 0) return null;
+  if (rankedBlocks.length === 0 && !notice) return null;
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: eventName,
-      additionalContext: `<<<HALOFY_CONTEXT_BLOCKS_V1>>>\n${JSON.stringify({ rankedBlocks })}\n<<<END_HALOFY_CONTEXT_BLOCKS_V1>>>`,
+      additionalContext: [notice, rankedBlocks.length ? `<<<HALOFY_CONTEXT_BLOCKS_V1>>>\n${JSON.stringify({ rankedBlocks })}\n<<<END_HALOFY_CONTEXT_BLOCKS_V1>>>` : null].filter(Boolean).join("\n\n"),
     },
   });
 }
@@ -147,14 +108,14 @@ export async function runClaudeLifecycleHook(connection, eventName, {
         if (output) stdout.write(output);
       }
     } else if (eventName === "UserPromptSubmit") {
+      const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
+      let recalled = null;
       if (RECALL_INJECTION_ENABLED) {
         const prompt = String(hookInput.prompt || hookInput.user_prompt || "").slice(0, 8_000);
-        if (prompt.trim()) {
-          const recalled = await runtime.recall(session, prompt);
-          const output = recallText(recalled, "UserPromptSubmit");
-          if (output) stdout.write(output);
-        }
+        if (prompt.trim()) recalled = await runtime.recall(session, prompt);
       }
+      const output = recallText(recalled, "UserPromptSubmit", delivery.notice);
+      if (output) stdout.write(output);
     } else if (eventName === "Stop") {
       if (!hookInput.stop_hook_active) {
         await catchUp(runtime, hookInput);

package/src/context-sync.mjs

@@ -2,7 +2,9 @@ import { constants } from "node:fs";
 import { chmod, link, lstat, mkdir, open, readdir, rename, rm } from "node:fs/promises";
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { dirname, join, parse, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { safeDirectory } from "./storage.mjs";
+export { safeDirectory } from "./storage.mjs";
 import { managedSkillsDirectory } from "./skills-sync.mjs";
 
 // A bounded client must report incomplete rather than silently export a prefix.
@@ -23,24 +25,7 @@ async function state(path) {
   try { return await lstat(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
 }
 
-// Check every ancestor, including host home overrides. Do not chmod existing
-// employee directories; only newly created and Halofy-owned directories are private.
-async function safeDirectory(path, create = false) {
-  const absolute = resolve(path);
-  let current = parse(absolute).root;
-  for (const part of absolute.slice(current.length).split(/[\\/]/).filter(Boolean)) {
-    current = join(current, part);
-    let entry = await state(current);
-    if (!entry && create) {
-      try { await mkdir(current, { mode: 0o700 }); } catch (error) { if (error?.code !== "EEXIST") throw error; }
-      entry = await state(current);
-    }
-    if (!entry) throw fail("directory_missing");
-    if (entry.isSymbolicLink() || !entry.isDirectory()) throw fail("unsafe_directory");
-  }
-}
-
-async function readPrivateJson(path) {
+export async function readPrivateJson(path) {
   const entry = await state(path);
   if (!entry) return null;
   if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 64 * 1024 * 1024) throw fail("unsafe_manifest");
@@ -59,7 +44,7 @@ async function saveManifest(stateRoot, value) {
   await rename(temporary, join(stateRoot, "manifest.json"));
 }
 
-async function withLock(stateRoot, action) {
+export async function withContextLock(stateRoot, action) {
   const lockPath = join(stateRoot, "refresh.lock");
   const candidate = join(stateRoot, `lock-${process.pid}-${randomBytes(12).toString("hex")}.tmp`);
   await privateFile(candidate, JSON.stringify({ pid: process.pid }));
@@ -121,9 +106,11 @@ async function validateTree(target, manifest) {
   if (!manifest?.files || !manifest.fileDigests) throw fail("incomplete_context_manifest");
   const directories = new Set(["references", "references/policy", "references/knowledge"]);
   const expected = new Set([OWNER, "SKILL.md", "references", "references/policy", "references/knowledge", ...manifest.files]);
+  const seen = new Set();
   async function visit(path, relative = "") {
     for (const name of await readdir(path)) {
       const rel = relative ? `${relative}/${name}` : name;
+      seen.add(rel);
       const entry = await state(join(path, name));
       if (!entry || entry.isSymbolicLink()) throw fail("unsafe_context_entry");
       if (!expected.has(rel)) throw fail("unmanaged_context_entry");
@@ -143,6 +130,7 @@ async function validateTree(target, manifest) {
     }
   }
   await visit(target);
+  if ([...expected].some((name) => !seen.has(name))) throw fail("missing_context_entry");
 }
 
 function validateItem(item) {
@@ -202,7 +190,7 @@ export async function syncManagedContext({ connection, transport, root: _root, h
     }
     // Existing state is never mutated until its explicit ownership is verified.
     await chmod(stateRoot, 0o700);
-    await withLock(stateRoot, async () => {
+    await withContextLock(stateRoot, async () => {
       let manifest;
       let stage;
       const withdraw = async () => {
@@ -235,6 +223,7 @@ export async function syncManagedContext({ connection, transport, root: _root, h
         const ids = new Set();
         const cursors = new Set();
         const files = [];
+        const tuples = [];
         const fileDigests = {};
         let bytes = 0;
         let cursor;
@@ -253,6 +242,7 @@ export async function syncManagedContext({ connection, transport, root: _root, h
             const file = `references/${item.kind}/${item.id}.md`;
             await privateFile(join(stage, file), text);
             files.push(file);
+            tuples.push([item.kind, item.id, item.namespace, item.title, item.enforcement || "", item.sha256]);
             fileDigests[file] = hash(text);
             if (item.kind === "policy") summary.policies += 1; else summary.knowledge += 1;
           }
@@ -266,7 +256,7 @@ export async function syncManagedContext({ connection, transport, root: _root, h
         fileDigests["SKILL.md"] = hash(skillText);
         await privateFile(join(stage, OWNER), JSON.stringify({ version: 1, token, installationId: connection.installationId }));
         // Save ownership before activation so a crash cannot orphan a new copy.
-        const next = { version: 1, token, installationId: connection.installationId, files, fileDigests, refreshedAt: now().toISOString() };
+        const next = { version: 1, token, installationId: connection.installationId, files, fileDigests, tuples, refreshedAt: now().toISOString() };
         await safeDirectory(skillsRoot);
         await safeDirectory(stateRoot);
         if (await state(target)) {
@@ -281,6 +271,7 @@ export async function syncManagedContext({ connection, transport, root: _root, h
         else await rm(stage, { recursive: true, force: true });
         stage = null;
         summary.complete = true;
+        Object.defineProperty(summary, "tuples", { value: tuples });
       } catch (error) {
         summary.errors.push({ stage: "refresh", code: error?.code || "context_unavailable" });
         try { await withdraw(); }
@@ -301,3 +292,24 @@ export function describeContextSync(summary) {
   if (!summary.complete) return `policies and knowledge: incomplete (${summary.errors.map((entry) => entry.code).join(", ") || "unavailable"})${summary.removed ? "; previous reference copy removed from discovery" : ""}`;
   return `policies and knowledge: refreshed ${summary.policies} policies, ${summary.knowledge} knowledge references`;
 }
+
+/** Verify the active copy before reusing a prior receipt without downloads. */
+export async function readManagedContextTuples({ connection, home = homedir(), env = process.env }) {
+  const skillsRoot = managedSkillsDirectory(connection.clientKind, { home, env });
+  if (!skillsRoot) throw fail("unsupported_host");
+  const name = managedContextName(connection.installationId);
+  const stateRoot = join(dirname(skillsRoot), `.${name}-state`);
+  const target = join(skillsRoot, name);
+  await safeDirectory(stateRoot);
+  const manifest = await readPrivateJson(join(stateRoot, "manifest.json"));
+  const owner = await readPrivateJson(join(stateRoot, STATE_OWNER));
+  if (manifest?.version !== 1 || manifest.installationId !== connection.installationId
+    || manifest.token !== owner?.token || !Array.isArray(manifest.tuples)
+    || !Array.isArray(manifest.files) || manifest.files.length !== manifest.tuples.length) throw fail("incomplete_context_manifest");
+  await safeDirectory(skillsRoot);
+  if (manifest.files.length) {
+    if (!(await owned(target, owner.token, connection.installationId))) throw fail("missing_context_entry");
+    await validateTree(target, manifest);
+  } else if (await state(target)) throw fail("unexpected_context_entry");
+  return manifest.tuples;
+}

package/src/delivery-sync.mjs

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { isActiveInstallation } from "./active.mjs";
+import { safeDirectory, readPrivateJson, withContextLock, readManagedContextTuples, syncManagedContext, describeContextSync } from "./context-sync.mjs";
+import { syncManagedSkills, readManagedSkillTuples, describeSkillSync } from "./skills-sync.mjs";
+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.";
+const SHA = /^[a-f0-9]{64}$/;
+const ID = /^[A-Za-z0-9_-]{1,160}$/;
+
+/** Contract hash: lexical serialized tuples, no locale-dependent ordering. */
+export function deliveryVersion(context, skills) {
+  const sort = (tuples) => [...tuples].sort((a, b) => {
+    const left = JSON.stringify(a), right = JSON.stringify(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  return createHash("sha256").update(JSON.stringify({ context: sort(context), skills: sort(skills) })).digest("hex");
+}
+
+/** Serializes the whole check/download/receipt, across concurrent hook processes.
+ * A dead process lock can be recovered; a live writer is never timed out/stolen. */
+export async function syncManagedDelivery({ connection, transport, root, phase = "start", stderr = process.stderr,
+  contextSync = syncManagedContext, ...options }) {
+  let result = { outcome: "failed", acknowledged: false, changed: false, context: null, skills: null };
+  try {
+    if (phase === "turn" && typeof transport?.deliveryCheck !== "function") return { ...result, reason: "upgrade_required" };
+    if (typeof connection.installationId !== "string" || !ID.test(connection.installationId)) throw new Error("invalid installation");
+    const stateRoot = join(root, `delivery-${connection.installationId}`);
+    await safeDirectory(stateRoot, true);
+    return await withContextLock(stateRoot, async () => {
+      const active = () => isActiveInstallation(connection, root);
+      if (!(await active())) {
+        const retired = await syncManagedContext({ ...options, connection, root,
+          transport: { contextPage: async () => ({ items: [], nextCursor: null }) } });
+        stderr.write(`[halofy] inactive installation context: ${describeContextSync(retired)}\n`);
+        return { ...result, reason: "inactive_installation" };
+      }
+      let check = null;
+      try {
+        check = await transport.deliveryCheck(phase === "turn" ? {} : { refresh: true });
+        if (!check || !SHA.test(check.version) || typeof check.syncRequired !== "boolean"
+          || (check.syncRequired ? typeof check.attemptId !== "string" || !ID.test(check.attemptId) : check.attemptId !== null)) throw new Error("invalid check");
+      } catch (error) {
+        if (phase === "turn" && error?.status === 404) return { ...result, reason: "upgrade_required" };
+        check = null;
+        stderr.write("[halofy] delivery status unavailable; continuing existing reference refresh\n");
+      }
+      let predecessorError = false;
+      try { await retirePredecessorContent({ ...options, connection, root }); }
+      catch { predecessorError = true; }
+      let previous = null;
+      try { previous = await readPrivateJson(join(stateRoot, "receipt.json")); }
+      catch { /* Local receipt cache damage cannot prevent a fresh sync. */ }
+      if (phase === "turn" && check && !predecessorError) {
+        let installedVersion = null;
+        try {
+          installedVersion = deliveryVersion(
+            await readManagedContextTuples({ ...options, connection }),
+            await readManagedSkillTuples({ ...options, connection, root }));
+        } catch { /* Missing or modified local copies require repair. */ }
+        if (installedVersion === check.version && await active()) {
+          if (!check.syncRequired) return previous?.version === installedVersion && previous.outcome === "restart_required"
+            ? { ...result, outcome: "restart_required", unchanged: true, notice: DELIVERY_NOTICE }
+            : { ...result, outcome: "synced", unchanged: true };
+          if (previous?.version === installedVersion && previous.outcome === "restart_required") {
+            await transport.deliveryReceipt({ attemptId: check.attemptId, version: installedVersion, outcome: "restart_required" });
+            return { ...result, outcome: "restart_required", acknowledged: true, unchanged: true, notice: DELIVERY_NOTICE };
+          }
+        }
+        if (!check.syncRequired) check = await transport.deliveryCheck({ refresh: true });
+      }
+      let context, skills;
+      try {
+        if (predecessorError) throw new Error("predecessor cleanup incomplete");
+        context = await contextSync({ ...options, connection, root, transport, canActivate: active });
+      }
+      catch { context = { supported: true, complete: false, errors: [{ code: "context_unavailable" }] }; }
+      stderr.write(`[halofy] ${describeContextSync(context)}\n`);
+      try {
+        if (predecessorError) throw new Error("predecessor cleanup incomplete");
+        skills = await syncManagedSkills({ ...options, connection, root, transport });
+      }
+      catch { skills = { supported: true, complete: false, checkedIn: false, installed: [], updated: [],
+        quarantined: [], conflicts: [], unchanged: [], errors: [{ code: "storage_unavailable" }] }; }
+      if (skills.skillsRoot) stderr.write(`[halofy] ${describeSkillSync(skills)}\n`);
+      const complete = context.complete && skills.complete && Array.isArray(context.tuples)
+        && Array.isArray(skills.tuples) && await active();
+      const version = complete ? deliveryVersion(context.tuples, skills.tuples) : deliveryVersion([], []);
+      const changed = complete && previous?.version !== version;
+      const outcome = !complete ? "failed" : phase === "turn" ? "restart_required" : "synced";
+      result = { ...result, context, skills, outcome, changed,
+        ...(outcome === "restart_required" ? { notice: DELIVERY_NOTICE } : {}) };
+      // Fresh discovery may race a manager update: server compares the computed
+      // activated version against this attempt and current eligibility again.
+      if (check?.attemptId) {
+        await transport.deliveryReceipt({ attemptId: check.attemptId, version, outcome });
+        result.acknowledged = true;
+      }
+      if (complete) await writePrivateFile(join(stateRoot, "receipt.json"), JSON.stringify({ version, outcome }));
+      return result;
+    });
+  } catch {
+    stderr.write("[halofy] delivery sync degraded: unavailable\n");
+    return { ...result, acknowledged: false, reason: "unavailable" };
+  }
+}

package/src/host-hook.mjs

@@ -9,6 +9,7 @@ import {
 } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { readHookInput, syncSkillsAtSessionStart } from "./claude-hook.mjs";
+import { syncManagedDelivery } from "./delivery-sync.mjs";
 import { transcriptDriverFor } from "./transcript-drivers/index.mjs";
 
 const USER_EVENTS = new Set(["UserPromptSubmit", "beforeSubmitPrompt", "BeforeAgent", "pre_llm_call"]);
@@ -68,10 +69,10 @@ function toolOutput(input) {
     input.extra?.result ?? input.extra?.error_message;
 }
 
-function recallOutput(clientKind, eventName, result) {
+function recallOutput(clientKind, eventName, result, notice) {
   const rankedBlocks = rankedRecallBlocks(result);
-  if (rankedBlocks.length === 0) return null;
-  const additionalContext = `<<<HALOFY_CONTEXT_BLOCKS_V1>>>\n${JSON.stringify({ rankedBlocks })}\n<<<END_HALOFY_CONTEXT_BLOCKS_V1>>>`;
+  if (rankedBlocks.length === 0 && !notice) return null;
+  const additionalContext = [notice, rankedBlocks.length ? `<<<HALOFY_CONTEXT_BLOCKS_V1>>>\n${JSON.stringify({ rankedBlocks })}\n<<<END_HALOFY_CONTEXT_BLOCKS_V1>>>` : null].filter(Boolean).join("\n\n");
   if (clientKind === "cursor") {
     return START_EVENTS.has(eventName) ? JSON.stringify({ additional_context: additionalContext }) : null;
   }
@@ -174,14 +175,16 @@ export async function runHostLifecycleHook(connection, eventName, {
       // transcript driver rely on this enqueue to reach the archive, and
       // hook-sourced events stay authoritative for messages even where a
       // driver adds usage/metadata evidence.
+      const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
       const prompt = promptText(hookInput);
+      let recalled = null;
       await enqueueMessage(runtime, connection, session, "user", prompt, eventName, hookInput);
       if (RECALL_INJECTION_ENABLED && connection.clientKind !== "cursor" &&
           typeof prompt === "string" && prompt.trim()) {
-        const recalled = await runtime.recall(session, prompt.slice(0, 8_000));
-        const output = recallOutput(connection.clientKind, eventName, recalled);
-        if (output) stdout.write(output);
+        recalled = await runtime.recall(session, prompt.slice(0, 8_000));
       }
+      const output = recallOutput(connection.clientKind, eventName, recalled, delivery.notice);
+      if (output) stdout.write(output);
     } else if (ASSISTANT_EVENTS.has(eventName)) {
       await enqueueMessage(runtime, connection, session, "assistant", assistantText(hookInput), eventName, hookInput);
       await runtime.commitIfThreshold(session);

package/src/install.mjs

@@ -8,6 +8,8 @@ import { SignedRuntimeTransport } from "./transport.mjs";
 import { INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
 import { CLIENT_KINDS, CLIENT_REGISTRY, lifecycleClient } from "./client-registry.mjs";
 import { syncManagedSkills } from "./skills-sync.mjs";
+import { syncManagedDelivery } from "./delivery-sync.mjs";
+import { retirePredecessorContent } from "./predecessor-sync.mjs";
 import { syncManagedContext } from "./context-sync.mjs";
 
 export const CLAUDE_CAPABILITIES = CLIENT_REGISTRY["claude-code"].capabilities;
@@ -294,32 +296,14 @@ export async function syncInstalledSkills({
 
 /** Refresh the installation's policy and knowledge references. */
 export async function syncInstalledContext({
-  installationId, root = defaultRuntimeDirectory(), fetchImpl = globalThis.fetch, home, env,
+  installationId, root = defaultRuntimeDirectory(), fetchImpl = globalThis.fetch, home, env, transport,
 }) {
   const store = new ConnectionStore(root);
   const connection = await store.load(installationId);
   const options = { root, ...(home ? { home } : {}), ...(env ? { env } : {}) };
-  const visited = new Set([installationId]);
-  let previous = connection.previousInstallationId;
-  while (previous) {
-    if (typeof previous !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(previous) ||
-        visited.has(previous) || visited.size > 64) {
-      throw Object.assign(new Error("invalid context predecessor chain"), { code: "context_predecessor_invalid" });
-    }
-    visited.add(previous);
-    const prior = await readJson(store.path(previous));
-    if (prior && prior.clientKind !== connection.clientKind) {
-      throw Object.assign(new Error("context predecessor host mismatch"), { code: "context_predecessor_invalid" });
-    }
-    const retired = await syncManagedContext({
-      ...options, connection: { installationId: previous, clientKind: connection.clientKind },
-      transport: { contextPage: async () => ({ items: [], nextCursor: null }) },
-    });
-    if (!retired.complete && !retired.removed) return retired;
-    previous = prior?.previousInstallationId;
-  }
+  await retirePredecessorContent({ ...options, connection });
   return syncManagedContext({
-    ...options, connection, transport: new SignedRuntimeTransport(connection, { fetchImpl }),
+    ...options, connection, transport: transport || new SignedRuntimeTransport(connection, { fetchImpl }),
     canActivate: async () => {
       const marker = await readJson(join(root, `active-${connection.clientKind}.json`));
       return !marker || marker.installationId === installationId;
@@ -327,6 +311,13 @@ export async function syncInstalledContext({
   });
 }
 
+/** Installer uses the same complete, serialized delivery attempt as hooks. */
+export async function syncInstalledDelivery({ installationId, root = defaultRuntimeDirectory(), fetchImpl = globalThis.fetch, home, env, stderr }) {
+  const connection = await new ConnectionStore(root).load(installationId);
+  const transport = new SignedRuntimeTransport(connection, { fetchImpl });
+  return syncManagedDelivery({ connection, root, home, env, transport, stderr, phase: "install" });
+}
+
 export function localMcpSnippet({ nodePath = process.execPath, proxyPath, installationId }) {
   return {
     mcpServers: {

package/src/installer-cli.mjs

@@ -10,16 +10,14 @@ import {
   installLocalConnection,
   installRuntimeBundle,
   localMcpSnippet,
-  syncInstalledSkills,
-  syncInstalledContext,
+  syncInstalledDelivery,
 } from "./install.mjs";
 import { configureClaudeProject } from "./claude-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 { DISCLOSURE_VERSION, INSTALLER_VERSION } from "./version.mjs";
-import { describeSkillSync, managedSkillsDirectory } from "./skills-sync.mjs";
-import { describeContextSync } from "./context-sync.mjs";
+import { managedSkillsDirectory } from "./skills-sync.mjs";
 
 const CLAIM_PATTERN = /^hsc_[A-Za-z0-9_-]{43}$/;
 
@@ -371,18 +369,8 @@ async function runAllInstaller(input, {
       } catch {
         heartbeat = false;
       }
-      // Skills land during the sweep too; a skills problem is reported per
-      // host, never fatal to the install.
-      let skills = null;
-      try {
-        skills = await syncInstalledSkills({
-          installationId: installed.installationId, root, fetchImpl,
-          ...(skillsHome ? { home: skillsHome } : {}),
-        });
-      } catch {
-        skills = null;
-      }
-      const context = await syncContextForInstall({ installationId: installed.installationId, root, fetchImpl, skillsHome, output });
+      const delivery = await syncDeliveryForInstall({ installationId: installed.installationId, root, fetchImpl, skillsHome, output });
+      const { skills, context } = delivery;
       results.push({
         context,
         clientKind: host.clientKind,
@@ -479,20 +467,8 @@ export async function runInstaller(argv, {
   } catch {
     heartbeat = false;
   }
-  // Skills land now, not at the next session: the badge already resolves the
-  // team + org set server-side, so the folder is populated before the user
-  // restarts the host. A skills problem is reported, never fatal.
-  let skills = null;
-  try {
-    skills = await syncInstalledSkills({
-      installationId: installed.installationId, root, fetchImpl, ...(skillsHome ? { home: skillsHome } : {}),
-    });
-    output.write(`${describeSkillSync(skills)}\n`);
-  } catch (error) {
-    skills = null;
-    output.write(`skills: unavailable (${error?.code || "runtime_unavailable"})\n`);
-  }
-  const context = await syncContextForInstall({ installationId: installed.installationId, root, fetchImpl, skillsHome, output });
+  const delivery = await syncDeliveryForInstall({ installationId: installed.installationId, root, fetchImpl, skillsHome, output });
+  const { skills, context } = delivery;
   return {
     context,
     status: heartbeat ? "configured_heartbeat_verified" : "configured_heartbeat_unavailable",
@@ -516,15 +492,13 @@ export async function runInstaller(argv, {
   };
 }
 
-async function syncContextForInstall({ installationId, root, fetchImpl, skillsHome, output }) {
+async function syncDeliveryForInstall({ installationId, root, fetchImpl, skillsHome, output }) {
   try {
-    const summary = await syncInstalledContext({
-      installationId, root, fetchImpl, ...(skillsHome ? { home: skillsHome } : {}),
+    return await syncInstalledDelivery({
+      installationId, root, fetchImpl, ...(skillsHome ? { home: skillsHome } : {}), stderr: output,
     });
-    output.write(`${describeContextSync(summary)}\n`);
-    return summary;
-  } catch (error) {
-    output.write(`policies and knowledge: unavailable (${error?.code || "runtime_unavailable"})\n`);
-    return { complete: false, errors: [{ code: error?.code || "runtime_unavailable" }] };
+  } catch {
+    output.write("delivery: unavailable\n");
+    return { skills: null, context: { complete: false, errors: [{ code: "runtime_unavailable" }] } };
   }
 }

package/src/predecessor-sync.mjs

@@ -0,0 +1,33 @@
+import { join } from "node:path";
+import { ConnectionStore, readJson, safeDirectory } from "./storage.mjs";
+import { syncManagedContext, withContextLock } from "./context-sync.mjs";
+import { retireManagedSkills } from "./skills-sync.mjs";
+
+/** Every delivery attempt must finish reconnect cleanup, including hook retries
+ * after an interrupted installer. This obligation travels in the connection. */
+export async function retirePredecessorContent({ connection, root, ...options }) {
+  const store = new ConnectionStore(root);
+  const visited = new Set([connection.installationId]);
+  let previous = connection.previousInstallationId;
+  while (previous) {
+    if (typeof previous !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(previous)
+      || visited.has(previous) || visited.size > 64) {
+      throw Object.assign(new Error("invalid context predecessor chain"), { code: "context_predecessor_invalid" });
+    }
+    visited.add(previous);
+    const prior = await readJson(store.path(previous));
+    if (prior && prior.clientKind !== connection.clientKind) {
+      throw Object.assign(new Error("context predecessor host mismatch"), { code: "context_predecessor_invalid" });
+    }
+    const priorConnection = { installationId: previous, clientKind: connection.clientKind };
+    const priorState = join(root, `delivery-${previous}`);
+    await safeDirectory(priorState, true);
+    await withContextLock(priorState, async () => {
+      const retired = await syncManagedContext({ ...options, root, connection: priorConnection,
+        transport: { contextPage: async () => ({ items: [], nextCursor: null }) } });
+      if (!retired.complete && !retired.removed) throw Object.assign(new Error("predecessor cleanup incomplete"), { code: "context_predecessor_incomplete" });
+      await retireManagedSkills({ ...options, root, connection: priorConnection });
+    });
+    previous = prior?.previousInstallationId;
+  }
+}

package/src/skills-sync.mjs

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, rename, stat } from "node:fs/promises";
+import { mkdir, readFile, rename, lstat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+import { isActiveInstallation } from "./active.mjs";
+import { ensurePrivateDirectory, readJson, safeDirectory, writePrivateFile } from "./storage.mjs";
 
 /**
  * Badge-delivered skills (CONTRACTS-S16-SKILL-TRACKING D37–D39 on the signed
@@ -62,7 +63,7 @@ function safeKey(skillKey) {
 
 async function pathState(path) {
   try {
-    return await stat(path);
+    return await lstat(path);
   } catch (error) {
     if (error?.code === "ENOENT") return null;
     throw error;
@@ -80,6 +81,9 @@ async function readText(path) {
 
 /** Move a managed copy aside with its bytes intact; never `rm`. */
 async function quarantine(skillsRoot, quarantineRoot, skillKey, now) {
+  if (!safeKey(skillKey)) throw new Error("invalid managed skill key");
+  await safeDirectory(skillsRoot);
+  await safeDirectory(quarantineRoot, true);
   const from = join(skillsRoot, skillKey);
   if (!(await pathState(from))) return null;
   await ensurePrivateDirectory(quarantineRoot);
@@ -99,10 +103,15 @@ async function isManaged(skillsRoot, skillKey, manifestEntry) {
 }
 
 export async function loadSkillsManifest(root, installationId) {
+  if (typeof installationId !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(installationId)) throw new Error("invalid installation");
+  await safeDirectory(root, true);
+  const manifestFile = await pathState(skillsManifestPath(root, installationId));
+  if (manifestFile && (!manifestFile.isFile() || manifestFile.isSymbolicLink())) throw new Error("unsafe skill manifest");
   const manifest = await readJson(skillsManifestPath(root, installationId), null);
-  if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.installs)) {
-    return { version: 1, installationId, installs: [], lastCheckinAt: null };
-  }
+  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");
   return manifest;
 }
 
@@ -126,6 +135,7 @@ export async function syncManagedSkills({
     supported: skillsRoot !== null,
     skillsRoot,
     checkedIn: false,
+    complete: false,
     installed: [],
     updated: [],
     quarantined: [],
@@ -134,30 +144,46 @@ export async function syncManagedSkills({
     errors: [],
   };
   if (!skillsRoot) return summary;
+  await safeDirectory(skillsRoot, true);
 
   const manifestPath = skillsManifestPath(root, connection.installationId);
   const quarantineRoot = join(root, "skills-quarantine", connection.installationId);
   const manifest = await loadSkillsManifest(root, connection.installationId);
-  const byId = new Map(manifest.installs.map((entry) => [entry.skillId, entry]));
   const current = now();
 
+  const active = () => isActiveInstallation(connection, root);
+  if (!(await active())) {
+    summary.errors.push({ stage: "checkin", code: "inactive_installation" });
+    return summary;
+  }
   let response;
   try {
     response = await transport.skillsCheckin(manifest.installs.map(({ skillId, sha }) => ({ skillId, sha })));
+    if (!response || !Array.isArray(response.skills) || !Array.isArray(response.items)
+      || response.skills.some((skill) => !safeKey(skill?.skillKey) || typeof skill.skillId !== "string"
+        || !/^[a-f0-9]{64}$/.test(skill.sha))
+      || new Set(response.skills.map((skill) => skill.skillId)).size !== response.skills.length
+      || new Set(response.skills.map((skill) => skill.skillKey)).size !== response.skills.length) {
+      throw Object.assign(new Error("invalid skill discovery"), { code: "invalid_skill_discovery" });
+    }
+    if (!(await active())) throw Object.assign(new Error("inactive installation"), { code: "inactive_installation" });
     summary.checkedIn = true;
   } catch (error) {
     summary.errors.push({ stage: "checkin", code: error?.code || "runtime_unavailable" });
+    if (error?.code === "inactive_installation") return summary;
     const last = manifest.lastCheckinAt ? Date.parse(manifest.lastCheckinAt) : NaN;
     if (Number.isFinite(last) && current.getTime() - last > STALE_AFTER_MS) {
+      const failedWithdrawals = [];
       for (const entry of manifest.installs) {
         try {
           const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
           if (moved) summary.quarantined.push({ skillKey: entry.skillKey, reason: "stale_checkin", to: moved });
         } catch (fsError) {
+          failedWithdrawals.push(entry);
           summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: fsError?.code || "fs_error" });
         }
       }
-      manifest.installs = [];
+      manifest.installs = failedWithdrawals;
       await writePrivateFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
     }
     return summary;
@@ -172,6 +198,7 @@ export async function syncManagedSkills({
   //    lists that the badge no longer resolves.
   const verdicts = new Map((Array.isArray(response?.items) ? response.items : []).map((item) => [item.skillId, item]));
   const survivors = [];
+  const failedWithdrawals = [];
   for (const entry of manifest.installs) {
     const verdict = verdicts.get(entry.skillId);
     const status = verdict?.status;
@@ -183,6 +210,7 @@ export async function syncManagedSkills({
     } catch (error) {
       summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: error?.code || "fs_error" });
       survivors.push(entry);
+      failedWithdrawals.push(entry);
     }
   }
   manifest.installs = survivors;
@@ -196,11 +224,21 @@ export async function syncManagedSkills({
       entry.skillId = verdict.currentSkillId;
     }
   }
-  const next = [];
+  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 file = join(dir, "SKILL.md");
+    if (!(await active())) {
+      summary.errors.push({ stage: "download", code: "inactive_installation" });
+      return summary;
+    }
+    const directoryEntry = await pathState(dir);
+    const fileEntry = await pathState(file);
+    if (directoryEntry?.isSymbolicLink() || fileEntry?.isSymbolicLink()) {
+      summary.conflicts.push({ skillKey: skill.skillKey, reason: "unsafe_path" });
+      continue;
+    }
     const onDisk = await readText(file);
     const intact = entry && typeof onDisk === "string" && digest(onDisk) === entry.fileSha256;
     if (entry && entry.sha === skill.sha && intact) {
@@ -216,7 +254,12 @@ export async function syncManagedSkills({
       const exported = await transport.skillDownload(skill.skillId);
       const content = typeof exported?.content === "string" ? exported.content : null;
       if (!content) throw Object.assign(new Error("skill export was empty"), { code: "empty_export" });
-      await mkdir(dir, { recursive: true });
+      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 (!(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");
       await writePrivateFile(file, content);
       const record = {
         skillId: skill.skillId,
@@ -248,6 +291,12 @@ export async function syncManagedSkills({
       summary.errors.push({ stage: "ack", code: error?.code || "runtime_unavailable" });
     }
   }
+  summary.complete = summary.checkedIn && !summary.errors.length && !summary.conflicts.length
+    && manifest.installs.length === wanted.size && await active();
+  if (summary.complete) {
+    try { Object.defineProperty(summary, "tuples", { value: await readManagedSkillTuples({ connection, root, home, env }) }); }
+    catch { summary.complete = false; }
+  }
   return summary;
 }
 
@@ -264,3 +313,45 @@ export function describeSkillSync(summary) {
   if (!summary.checkedIn) parts.unshift("check-in unavailable");
   return `skills (${basename(dirname(summary.skillsRoot))}/${basename(summary.skillsRoot)}): ${parts.join(", ") || "nothing to do"}`;
 }
+
+/** Verify exported definition bytes, not just claimed frontmatter/manifest SHAs. */
+export async function readManagedSkillTuples({ connection, root, home = homedir(), env = process.env }) {
+  const skillsRoot = managedSkillsDirectory(connection.clientKind, { home, env });
+  if (skillsRoot) await safeDirectory(skillsRoot);
+  await safeDirectory(root);
+  const manifestEntry = await pathState(skillsManifestPath(root, connection.installationId));
+  if (!skillsRoot || !manifestEntry?.isFile() || manifestEntry.isSymbolicLink()) throw new Error("missing skill evidence");
+  const manifest = await loadSkillsManifest(root, connection.installationId);
+  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 content = await readText(file);
+    const separator = content?.indexOf("\n---\n\n");
+    // The export wrapper adds exactly one blank line and one terminal newline.
+    const definition = separator >= 0 && content.endsWith("\n") ? content.slice(separator + 6, -1) : null;
+    if (definition === null || digest(content) !== entry.fileSha256 || digest(definition) !== entry.sha) throw new Error("modified skill evidence");
+  }
+  return manifest.installs.map(({ skillId, skillKey, sha }) => [skillId, skillKey, sha]);
+}
+
+/** Retire a reconnect predecessor's managed discovery before activating its replacement.
+ * Move the owned directory intact, including employee edits, outside discovery;
+ * never delete or follow its contents. An unowned collision remains untouched. */
+export async function retireManagedSkills({ connection, root, home = homedir(), env = process.env, now = () => new Date() }) {
+  const skillsRoot = managedSkillsDirectory(connection.clientKind, { home, env });
+  if (!skillsRoot) return;
+  const manifest = await loadSkillsManifest(root, connection.installationId);
+  if (!manifest.installs.length) return;
+  await safeDirectory(skillsRoot);
+  for (const entry of manifest.installs) {
+    const dir = join(skillsRoot, 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());
+  }
+  manifest.installs = [];
+  await writePrivateFile(skillsManifestPath(root, connection.installationId), `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/src/storage.mjs

@@ -1,6 +1,6 @@
 import { constants } from "node:fs";
-import { access, chmod, mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { access, chmod, mkdir, lstat, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { dirname, join, parse, resolve } from "node:path";
 import { homedir, platform } from "node:os";
 import { randomBytes } from "node:crypto";
 
@@ -132,3 +132,21 @@ export class ConnectionStore {
     }
   }
 }
+
+/** Refuse symlinks at every ancestor before touching managed runtime paths. */
+export async function safeDirectory(path, create = false) {
+  const absolute = resolve(path);
+  let current = parse(absolute).root;
+  for (const part of absolute.slice(current.length).split(/[\\/]/).filter(Boolean)) {
+    current = join(current, part);
+    let entry;
+    try { entry = await lstat(current); }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+    if (!entry && create) {
+      try { await mkdir(current, { mode: 0o700 }); } catch (error) { if (error?.code !== "EEXIST") throw error; }
+      entry = await lstat(current);
+    }
+    if (!entry) throw Object.assign(new Error("directory_missing"), { code: "directory_missing" });
+    if (entry.isSymbolicLink() || !entry.isDirectory()) throw Object.assign(new Error("unsafe_directory"), { code: "unsafe_directory" });
+  }
+}

package/src/transport.mjs

@@ -90,6 +90,12 @@ export class SignedRuntimeTransport {
 
   /** Badge skill check-in beacon: exactly the installed {skillId, sha} pairs (D39). */
   skillsCheckin(items) { return this.request("/v1/agent-runtime/skills/checkin", { body: { items } }); }
+  deliveryCheck({ refresh = false } = {}) {
+    return this.request("/v1/agent-runtime/delivery/check", { body: refresh ? { refresh: true } : {}, maxResponseBytes: 16 * 1024 });
+  }
+  deliveryReceipt(receipt) {
+    return this.request("/v1/agent-runtime/delivery/receipt", { body: receipt, maxResponseBytes: 16 * 1024 });
+  }
   contextPage(cursor) {
     return this.request("/v1/agent-runtime/context", {
       body: cursor === undefined ? {} : { cursor }, maxResponseBytes: 8 * 1024 * 1024,

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.8.0";
-export const RUNTIME_VERSION = "0.8.0";
+export const INSTALLER_VERSION = "0.9.0";
+export const RUNTIME_VERSION = "0.9.0";
 export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-08.1";