@halofy/agent-connect 0.8.0 → 0.10.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.10.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -128,3 +128,85 @@ 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.
+## Organization instructions (0.10.0 release candidate)
+
+This source adds Govern instruction delivery alongside the existing skill,
+policy, knowledge and delivery-receipt paths. Activation requires the reviewed
+0.10.0 npm publication, matching server deployment and a fresh confirmed
+installation. Source versioning alone is not publication evidence. Existing
+connections without the new local instruction consent/profile snapshot do not
+gain global file-writing authority.
+
+The installer discloses global rule management alongside existing capture and
+MCP behavior. It freezes the selected profile and server-provided namespace in
+the local connection and fetches instructions with the installation proof.
+Subsequent supported session-start hooks refresh them independently of disabled
+memory recall. There is no resident instruction daemon; an offline device or a
+host session without an installed startup hook does not fetch updates. Claude's
+existing hook installation is project-scoped even though its rule file is global.
+
+| Host | Local target | Boundaries |
+|---|---|---|
+| Codex | `CODEX_HOME` or `~/.codex`, active nonempty `AGENTS.override.md` else `AGENTS.md` | Marked section; changing the active target reports a conflict |
+| Claude Code | `CLAUDE_CONFIG_DIR` or `~/.claude`, dedicated `rules/halofy-*.md` | Existing personal/project `CLAUDE.md` remains untouched |
+| Gemini CLI | `GEMINI_CLI_HOME` or home, then `.gemini/GEMINI.md` | Marked section; custom discovery excluding `GEMINI.md` is unsupported |
+| Cursor | `~/.cursor/rules/halofy-*.mdc` with `alwaysApply: true` | Agent Chat only; no claim for Tab, Inline Edit, or cloud hosts |
+| Other packaged hosts | No instruction writes | Reports unsupported; existing capture/MCP continues |
+
+Host mechanisms were checked against official documentation on 2026-09-10:
+[Codex](https://learn.chatgpt.com/docs/agent-configuration/agents-md),
+[Claude Code](https://code.claude.com/docs/en/memory),
+[Gemini CLI](https://geminicli.com/docs/cli/gemini-md/), and
+[Cursor](https://prod.cursor.com/help/customization/rules).
+These are file-format adapters, not real-host loading certification. Host
+precedence, context limits, project configuration and exclusion settings still
+apply. Receipts say `pending_restart`, never loaded or obeyed. Other local OS
+accounts, containers and remote/cloud profiles require their own installation.
+
+Sync validates exact content and bundle digests, scope ancestry/order and size
+before writing. Personal bytes outside a managed block are preserved exactly.
+An isolated ownership manifest, exclusive profile lock, no-follow reads,
+component symlink checks, private backups, concurrent-edit checks and atomic
+replacement protect local content. Unexpected edits, broken/duplicate markers,
+linked files or changed target selection fail without replacing host content.
+Request failure leaves the current installation’s instructions unchanged. A
+confirmed reconnect first retires only verified predecessor-owned instruction
+bytes; old hooks cannot restore them. Conflicting predecessor edits prevent new
+instruction activation while preserving all user content. Otherwise, only a
+verified empty bundle removes managed content; an empty file and removal manifest remain so a
+future authorized re-enable can be recognized safely. Backup files stay outside
+host rules directories, under the runtime instructions directory.
+
+A stale lock is deliberately not automatically deleted; after confirming no
+sync is running, an operator may remove `.halofy-instructions.lock` in the
+selected profile. Local filesystem errors and receipt failures do not interrupt
+capture or MCP. Neither instruction text, filesystem paths nor backups are sent
+in status receipts. Existing policy/knowledge/skill operations and runtime queue
+files are not changed by instruction sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.8.0",
+  "version": "0.10.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"),
     },
   });
 }
@@ -135,6 +96,8 @@ 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 runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
       if (RECALL_INJECTION_ENABLED) {
@@ -147,14 +110,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;
   }
@@ -160,6 +161,8 @@ export async function runHostLifecycleHook(connection, eventName, {
     if (START_EVENTS.has(eventName)) {
       // Refresh/withdraw local context even when replay or heartbeat fails.
       await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
+      // Instructions have their own brownout boundary, independent of recall.
+      await runtime.syncInstructions?.().catch(() => {});
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
       if (RECALL_INJECTION_ENABLED) {
@@ -174,14 +177,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

@@ -4,10 +4,13 @@ import { chmod, cp, rename, rm, unlink } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { generateInstallationKeyPair } from "./crypto.mjs";
 import { ConnectionStore, defaultRuntimeDirectory, ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+import { syncAgentInstructions } from "./instructions.mjs";
 import { 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;
@@ -149,6 +152,7 @@ export async function installLocalConnection({
   root = defaultRuntimeDirectory(),
   fetchImpl = globalThis.fetch,
   sendHeartbeat = true,
+  instructionProfile,
 }) {
   if (!CLIENT_KINDS.includes(clientKind)) throw new Error("the selected lifecycle adapter is not packaged");
   const client = lifecycleClient(clientKind);
@@ -199,6 +203,8 @@ export async function installLocalConnection({
     pluginVersion: RUNTIME_VERSION,
     proofStorage,
     installedAt: new Date().toISOString(),
+    ...(typeof consumed.namespace === "string" ? { namespace: consumed.namespace } : {}),
+    ...(instructionProfile ? { instructionProfile } : {}),
   };
   await store.save(connection);
   await writePrivateFile(join(root, `active-${clientKind}.json`), `${JSON.stringify({
@@ -223,9 +229,13 @@ export async function installLocalConnection({
       heartbeat = false;
     }
   }
+  const instructions = instructionProfile
+    ? await syncAgentInstructions(connection, { root, transport: new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 2_000 }) })
+    : undefined;
   return {
     installationId,
     previousInstallationId: connection.previousInstallationId ?? null,
+    ...(instructions ? { instructions } : {}),
     heartbeat,
     reused: false,
     proofStorage: connection.proofStorage,
@@ -294,32 +304,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 +319,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: {