@halofy/agent-connect 0.9.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.9.0 install <client-kind> \
+npx --yes @halofy/agent-connect@0.10.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -155,3 +155,58 @@ 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.9.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/claude-hook.mjs

@@ -96,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) {

package/src/host-hook.mjs

@@ -161,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) {

package/src/install.mjs

@@ -4,6 +4,7 @@ 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";
@@ -151,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);
@@ -201,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({
@@ -225,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,

package/src/installer-cli.mjs

@@ -16,6 +16,7 @@ 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 { instructionProfile } from "./instructions.mjs";
 import { DISCLOSURE_VERSION, INSTALLER_VERSION } from "./version.mjs";
 import { managedSkillsDirectory } from "./skills-sync.mjs";
 
@@ -195,9 +196,9 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
       ? "This reviewed host surface can report complete coverage when all declared evidence is observed."
       : `This host has partial coverage (${client.reason}); missing categories remain explicit.`,
     "Authorized organization managers may review retained conversations and summaries.",
-    skillsRoot
-      ? `This reads and writes only the skill folders it created under ${skillsRoot}; it does not scan historical files, other applications, clipboard, keystrokes, or other agents.`
-      : "This does not scan historical files, other applications, clipboard, keystrokes, or other agents.",
+    "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.",
+    "Other OS accounts, containers, remote/cloud hosts and unsupported agents are not covered. Instruction precedence remains controlled by the host.",
     "Disconnecting stops future capture but does not erase retained data.",
     `Disclosure: ${DISCLOSURE_VERSION}`,
   ].join("\n");
@@ -250,8 +251,9 @@ export function allDisclosureText({ serverUrl, projectRoot, organization = null,
   lines.push(
     "",
     "Authorized organization managers may review retained conversations and summaries.",
-    "This reads and writes only the skill folders it created for the hosts listed above; it does not scan " +
-    "historical files, other applications, clipboard, keystrokes, or other agents.",
+    "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.",
+    "Other OS accounts, containers, remote/cloud hosts and unsupported agents are not covered. Instruction precedence remains controlled by the host.",
     "Disconnecting stops future capture but does not erase retained data.",
     `Disclosure: ${DISCLOSURE_VERSION}`,
   );
@@ -354,6 +356,7 @@ async function runAllInstaller(input, {
         root,
         fetchImpl,
         sendHeartbeat: false,
+        instructionProfile: instructionProfile(host.clientKind, skillsHome ? { home: skillsHome } : {}),
       });
       const configured = await configureHost(host.clientKind, {
         projectRoot: input.projectRoot,
@@ -383,6 +386,7 @@ async function runAllInstaller(input, {
               conflicts: skills.conflicts.map((c) => c.skillKey), errors: skills.errors.length }
           : null,
         proofStorage: installed.proofStorage,
+        instructions: installed.instructions,
         configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
         replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries || 0,
         nextStep: `Restart ${lifecycleClient(host.clientKind).label}, then check the connection in Halofy.`,
@@ -448,6 +452,7 @@ export async function runInstaller(argv, {
     root,
     fetchImpl,
     sendHeartbeat: false,
+    instructionProfile: instructionProfile(input.clientKind, skillsHome ? { home: skillsHome } : {}),
   });
   const bundle = await installRuntimeBundle({ root, ...(sourceRoot ? { sourceRoot } : {}) });
   const common = {
@@ -477,6 +482,7 @@ export async function runInstaller(argv, {
     installerVersion: INSTALLER_VERSION,
     publishedPackage: true,
     projectConfigured: true,
+    instructions: installed.instructions,
     configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
     replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries || 0,
     mcpConfiguration: localMcpSnippet({

package/src/instructions.mjs

@@ -0,0 +1,266 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { createHash, randomBytes } from "node:crypto";
+import { isActiveInstallation } from "./active.mjs";
+import { ConnectionStore, readJson } from "./storage.mjs";
+import { SignedRuntimeTransport } from "./transport.mjs";
+
+const sha = (value) => createHash("sha256").update(value).digest("hex");
+const HEX = /^[a-f0-9]{64}$/;
+const MARKER = "<!-- HALOFY-INSTRUCTIONS:";
+const fail = (code) => { throw Object.assign(new Error(code), { instructionCode: code }); };
+const plain = (value) => value && typeof value === "object" && !Array.isArray(value);
+const scope = (value) => typeof value === "string" && value.length <= 1024 && !/[\u0000-\u001f\u007f]/.test(value) &&
+  (value === "" || value.split("/").every((part) => part && part !== "." && part !== ".."));
+
+/** Local consent/profile snapshot; never derive a writable path from a server response. */
+export function instructionProfile(clientKind, { home = homedir(), env = process.env } = {}) {
+  const roots = {
+    codex: env.CODEX_HOME || join(home, ".codex"),
+    "claude-code": env.CLAUDE_CONFIG_DIR || join(home, ".claude"),
+    "gemini-cli": join(env.GEMINI_CLI_HOME || home, ".gemini"),
+    cursor: join(home, ".cursor"),
+  };
+  return { version: 1, consent: "organization-instructions-v1", clientKind, root: roots[clientKind] ? resolve(roots[clientKind]) : null };
+}
+
+export function validateInstructionBundle(bundle, expectedNamespace) {
+  if (!plain(bundle) || bundle.schemaVersion !== 1 || !scope(expectedNamespace) ||
+      bundle.namespace !== expectedNamespace || !HEX.test(bundle.digest) || !Array.isArray(bundle.documents) ||
+      Buffer.byteLength(JSON.stringify(bundle)) > 64 * 1024) fail("invalid_bundle");
+  let previous = null;
+  const documents = bundle.documents.map((doc) => {
+    if (!plain(doc) || typeof doc.id !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(doc.id) || !scope(doc.namespace) ||
+        !(doc.namespace === "" || doc.namespace === expectedNamespace || expectedNamespace.startsWith(`${doc.namespace}/`)) ||
+        (previous !== null && !(doc.namespace !== previous && (previous === "" || doc.namespace.startsWith(`${previous}/`)))) ||
+        !Number.isSafeInteger(doc.version) || doc.version < 1 || typeof doc.title !== "string" || !doc.title.trim() || doc.title.length > 160 || doc.title.includes(MARKER) ||
+        /[\u0000-\u001f\u007f]/.test(doc.title) || typeof doc.content !== "string" || !doc.content.trim() ||
+        Buffer.from(doc.title, "utf8").toString("utf8") !== doc.title || Buffer.from(doc.content, "utf8").toString("utf8") !== doc.content ||
+        doc.content.includes("\0") || doc.content.includes(MARKER) || Buffer.byteLength(doc.content) > 16 * 1024 ||
+        !HEX.test(doc.sha256) || sha(doc.content) !== doc.sha256) fail("invalid_bundle");
+    previous = doc.namespace;
+    return { id: doc.id, namespace: doc.namespace, version: doc.version, title: doc.title, content: doc.content, sha256: doc.sha256 };
+  });
+  if (sha(JSON.stringify(documents)) !== bundle.digest) fail("invalid_bundle");
+  return { ...bundle, documents };
+}
+
+// Inspect every existing path component, including the final file. mkdir is
+// deliberately incremental: recursive mkdir can follow a linked ancestor.
+async function safePath(path, { createParents = false } = {}) {
+  if (typeof path !== "string" || !isAbsolute(path) || resolve(path) !== path || path.includes("\0")) fail("unsafe_path");
+  const parsed = parse(path);
+  const parts = path.slice(parsed.root.length).split(sep).filter(Boolean);
+  let current = parsed.root;
+  const chain = [];
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]);
+    let info;
+    try { info = await lstat(current); } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      if (createParents && i < parts.length - 1) {
+        try { await mkdir(current, { mode: 0o700 }); } catch (made) { if (made.code !== "EEXIST") throw made; }
+        info = await lstat(current);
+      } else return chain;
+    }
+    if (info.isSymbolicLink() || (i < parts.length - 1 ? !info.isDirectory() : !info.isFile() && !info.isDirectory())) fail("unsafe_path");
+    chain.push(`${current}:${info.dev}:${info.ino}`);
+  }
+  return chain;
+}
+
+async function snapshot(path) {
+  await safePath(path);
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const info = await handle.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.size > 1024 * 1024) fail("unsafe_file");
+    const bytes = await handle.readFile();
+    return { bytes, mode: info.mode & 0o777, identity: `${info.dev}:${info.ino}:${info.mtimeMs}:${info.ctimeMs}`, exists: true };
+  } catch (error) {
+    if (error.code === "ENOENT") return { bytes: Buffer.alloc(0), mode: 0o600, identity: null, exists: false };
+    throw error;
+  } finally { await handle?.close(); }
+}
+
+async function atomic(path, bytes, prior) {
+  const ancestors = await safePath(path, { createParents: true });
+  const temp = `${path}.${process.pid}.${randomBytes(10).toString("hex")}.tmp`;
+  const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), prior.mode);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await handle.close();
+    const now = await snapshot(path);
+    if (now.identity !== prior.identity || !now.bytes.equals(prior.bytes) ||
+        JSON.stringify(await safePath(path)) !== JSON.stringify(ancestors)) fail("concurrent_edit");
+    await rename(temp, path);
+  } finally {
+    await handle.close().catch(() => {});
+    await unlink(temp).catch((error) => { if (error.code !== "ENOENT") throw error; });
+  }
+}
+
+async function targetFor(connection, owner) {
+  const profile = connection.instructionProfile;
+  if (!plain(profile) || profile.version !== 1 || profile.consent !== "organization-instructions-v1" ||
+      profile.clientKind !== connection.clientKind) fail("reinstall_required");
+  if (!["codex", "claude-code", "gemini-cli", "cursor"].includes(connection.clientKind)) return null;
+  const root = profile.root;
+  await safePath(root);
+  if (connection.clientKind === "codex") {
+    const override = join(root, "AGENTS.override.md");
+    const file = await snapshot(override);
+    return { path: file.bytes.toString("utf8").trim() ? override : join(root, "AGENTS.md"), dedicated: false };
+  }
+  if (connection.clientKind === "gemini-cli") {
+    const settings = await snapshot(join(root, "settings.json"));
+    let parsed;
+    try { parsed = settings.exists ? JSON.parse(settings.bytes.toString("utf8")) : {}; } catch { fail("host_settings_invalid"); }
+    const filename = parsed.context?.fileName;
+    // A non-default discovery configuration can be overridden again by project
+    // settings. Do not guess a writable global filename or change host settings.
+    if (filename !== undefined && filename !== "GEMINI.md" &&
+        !(Array.isArray(filename) && filename.includes("GEMINI.md"))) fail("custom_context_unsupported");
+    return { path: join(root, "GEMINI.md"), dedicated: false };
+  }
+  return { path: join(root, "rules", `halofy-${owner}.${connection.clientKind === "cursor" ? "mdc" : "md"}`), dedicated: true };
+}
+
+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 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) };
+}
+
+/** Writes only owned bytes. Any ambiguity leaves the host file unchanged. */
+export async function applyInstructionBundle(connection, bundle, { root, beforeWrite, canActivate = async () => true } = {}) {
+  bundle = validateInstructionBundle(bundle, connection.namespace);
+  const owner = sha(`${connection.serverUrl}\0${connection.namespace}`).slice(0, 24);
+  const target = await targetFor(connection, owner);
+  if (!target) return { digest: bundle.digest, status: "unsupported", reason: "host_unsupported" };
+  const stateKey = sha(`${connection.clientKind}\0${connection.instructionProfile.root}\0${owner}`);
+  const statePath = join(resolve(root), "instructions", `${stateKey}.json`);
+  await safePath(statePath, { createParents: true });
+  // Profile-level lock remains the same if Codex switches its override file.
+  const lockPath = join(connection.instructionProfile.root, ".halofy-instructions.lock");
+  await safePath(lockPath, { createParents: true });
+  let lock;
+  try {
+    try { lock = await open(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600); }
+    catch (error) { if (error.code === "EEXIST") fail("sync_busy"); throw error; }
+    if (!(await canActivate())) fail("inactive_installation");
+    const initial = await snapshot(target.path);
+    const stateSnapshot = await snapshot(statePath);
+    let state;
+    try { state = stateSnapshot.exists ? JSON.parse(stateSnapshot.bytes.toString("utf8")) : null; } catch { fail("ownership_invalid"); }
+    if (state && (state.version !== 1 || state.path !== target.path || state.owner !== owner ||
+        typeof state.managedHash !== "string" || !HEX.test(state.managedHash))) fail("ownership_conflict");
+    if (state?.removed) {
+      if (target.dedicated && sha(initial.bytes) !== state.managedHash) fail("managed_content_changed");
+      if (!target.dedicated && initial.bytes.includes(Buffer.from(`${MARKER}${owner}:`))) fail("managed_content_changed");
+      if (bundle.documents.length === 0) return { digest: bundle.digest, status: "pending_restart", reason: "no_managed_content" };
+      state = null;
+    }
+    const rendered = render(bundle, owner, connection.clientKind === "cursor");
+    const bytes = initial.bytes;
+    const start = bytes.indexOf(rendered.begin);
+    const end = bytes.indexOf(rendered.end);
+    let prefix = bytes;
+    let suffix = Buffer.alloc(0);
+    let separator = "";
+    if (state) {
+      if (target.dedicated) {
+        if (!initial.exists || sha(bytes) !== state.managedHash) fail("managed_content_changed");
+        prefix = Buffer.alloc(0);
+      } else {
+        if (start < 0 || end < start || bytes.indexOf(rendered.begin, start + 1) !== -1 ||
+            bytes.indexOf(rendered.end, end + 1) !== -1) fail("markers_invalid");
+        const managedEnd = end + rendered.end.length + 1;
+        if (bytes[managedEnd - 1] !== 10 || sha(bytes.subarray(start, managedEnd)) !== state.managedHash) fail("managed_content_changed");
+        separator = state.separator === "\n\n" ? state.separator : "";
+        const prefixEnd = start - Buffer.byteLength(separator);
+        if (prefixEnd < 0 || bytes.subarray(prefixEnd, start).toString() !== separator) fail("managed_content_changed");
+        prefix = bytes.subarray(0, prefixEnd);
+        suffix = bytes.subarray(managedEnd);
+      }
+    } else if (target.dedicated && initial.exists && initial.bytes.length > 0 || start >= 0 || end >= 0 || bytes.includes(Buffer.from(MARKER))) fail("unowned_content");
+    // Refuse malformed owned-looking markers outside the verified region too.
+    if (prefix.includes(Buffer.from(MARKER)) || suffix.includes(Buffer.from(MARKER))) fail("markers_invalid");
+    const removing = bundle.documents.length === 0;
+    if (removing && !state) return { digest: bundle.digest, status: "pending_restart", reason: "no_managed_content" };
+    if (!state && !target.dedicated) separator = prefix.length ? "\n\n" : "";
+    const updated = removing ? Buffer.concat([prefix, suffix]) : Buffer.concat([prefix, Buffer.from(separator), rendered.bytes, suffix]);
+    const next = { version: 1, owner, path: target.path, managedHash: sha(rendered.bytes), separator, digest: bundle.digest };
+    if (!updated.equals(bytes)) {
+      // Backup lives outside the host's rules directory, so it cannot be loaded
+      // as a second rule. Never send backup or filesystem paths to the server.
+      const backup = `${statePath}.${Date.now()}.${randomBytes(6).toString("hex")}.bak`;
+      await atomic(backup, bytes, await snapshot(backup));
+      await beforeWrite?.();
+      if (!(await canActivate())) fail("inactive_installation");
+      if ((await targetFor(connection, owner))?.path !== target.path) fail("host_profile_changed");
+      await atomic(target.path, updated, initial);
+    }
+    if (removing) {
+      // Shared empty files remain to avoid a delete race with personal edits.
+      // Dedicated empty files are harmless and no longer include instructions.
+      await atomic(statePath, Buffer.from(`${JSON.stringify({ ...next, removed: true, managedHash: sha(updated) })}\n`), stateSnapshot);
+    } else {
+      await atomic(statePath, Buffer.from(`${JSON.stringify(next)}\n`), stateSnapshot);
+    }
+    return { digest: bundle.digest, status: "pending_restart", reason: removing ? "managed_content_removed" : "host_reload_required" };
+  } finally {
+    if (lock) { await lock.close(); await safePath(lockPath); await unlink(lockPath); }
+  }
+}
+
+/** A confirmed reconnect retires only verified instruction bytes owned by its
+ * predecessors. The complete chain is validated before the first removal.
+ * Same-owner retries share the manifest and keep their current instruction copy. */
+async function retirePredecessorInstructions(connection, root) {
+  const sameOwner = (left, right) => left.serverUrl === right.serverUrl && left.namespace === right.namespace &&
+    left.clientKind === right.clientKind && left.instructionProfile?.root === right.instructionProfile?.root;
+  const store = new ConnectionStore(root);
+  const visited = new Set([connection.installationId]);
+  const predecessors = [];
+  let previous = connection.previousInstallationId;
+  while (previous) {
+    if (typeof previous !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(previous) || visited.has(previous) || visited.size > 64) fail("predecessor_invalid");
+    visited.add(previous);
+    const prior = await readJson(store.path(previous));
+    if (!prior || prior.clientKind !== connection.clientKind) fail("predecessor_invalid");
+    predecessors.push(prior);
+    previous = prior.previousInstallationId;
+  }
+  const retired = [];
+  for (const prior of predecessors) {
+    if (!prior.instructionProfile || sameOwner(prior, connection) || retired.some((entry) => sameOwner(entry, prior))) continue;
+    const empty = { schemaVersion: 1, namespace: prior.namespace, digest: sha("[]"), documents: [] };
+    await applyInstructionBundle(prior, empty, { root, canActivate: () => isActiveInstallation(connection, root) });
+    retired.push(prior);
+  }
+}
+
+/** Separate best-effort operation: a failed GET never means remove instructions. */
+export async function syncAgentInstructions(connection, { root, transport = new SignedRuntimeTransport(connection, { timeoutMs: 2_000 }) } = {}) {
+  let receipt = { digest: sha("[]"), status: "unavailable", reason: "fetch_unavailable" };
+  try {
+    if (!(await isActiveInstallation(connection, root))) return { ...receipt, status: "unsupported", reason: "inactive_installation" };
+    await retirePredecessorInstructions(connection, root);
+    const bundle = await transport.instructions();
+    receipt.digest = typeof bundle?.digest === "string" && HEX.test(bundle.digest) ? bundle.digest : receipt.digest;
+    receipt = await applyInstructionBundle(connection, bundle, { root, canActivate: () => isActiveInstallation(connection, root) });
+  } catch (error) {
+    const reason = error.instructionCode;
+    const unsupported = ["custom_context_unsupported", "reinstall_required", "inactive_installation"].includes(reason);
+    receipt = { ...receipt, status: unsupported ? "unsupported" : reason && reason !== "invalid_bundle" ? "conflict" : "unavailable", reason: reason || "fetch_unavailable" };
+  }
+  try { await transport.instructionStatus(receipt); } catch { /* A receipt failure cannot disable capture/MCP. */ }
+  return receipt;
+}

package/src/runtime.mjs

@@ -8,19 +8,23 @@ import {
 import { claudeTranscriptDriver } from "./transcript-drivers/claude.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { readJson, withFileLock, writePrivateFile } from "./storage.mjs";
+import { syncAgentInstructions } from "./instructions.mjs";
 import { RUNTIME_VERSION } from "./version.mjs";
 
 export class LifecycleRuntime {
   constructor(connection, {
     root,
     transport = new SignedRuntimeTransport(connection),
+    instructionTransport = new SignedRuntimeTransport(connection, { timeoutMs: 2_000 }),
     maxBatchEvents = 100,
     maxBatchBytes = 1024 * 1024,
     commitThreshold = 20,
   } = {}) {
     if (!root) throw new Error("runtime storage root is required");
     this.connection = connection;
+    this.root = root;
     this.transport = transport;
+    this.instructionTransport = instructionTransport;
     const connectionRoot = join(root, connection.installationId);
     this.queue = new BoundedEncryptedQueue(connectionRoot);
     this.cursors = new CursorStore(connectionRoot);
@@ -32,6 +36,13 @@ export class LifecycleRuntime {
     this.sessions = new Map();
   }
 
+  async syncInstructions() {
+    // Legacy bindings have no consent/profile snapshot. Reinstall the reviewed
+    // package to enable global instruction management.
+    if (!this.connection.instructionProfile) return { status: "unsupported", reason: "reinstall_required" };
+    return syncAgentInstructions(this.connection, { root: this.root, transport: this.instructionTransport });
+  }
+
   sessionHash(hostSessionId) {
     return deriveSessionHash({
       installationId: this.connection.installationId,

package/src/transport.mjs

@@ -105,6 +105,8 @@ export class SignedRuntimeTransport {
   skillDownload(skillId) {
     return this.request(`/v1/agent-runtime/skills/${encodeURIComponent(skillId)}/download`, { method: "GET" });
   }
+  instructions() { return this.request("/v1/agent-runtime/instructions", { method: "GET", maxResponseBytes: 64 * 1024 }); }
+  instructionStatus(body) { return this.request("/v1/agent-runtime/instructions/status", { body, maxResponseBytes: 16 * 1024 }); }
 
   openSession(body) { return this.request("/v1/agent-sessions/open", { body }); }
   appendEvents(sessionId, events) { return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/events`, { body: { events } }); }

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-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";
+export const INSTALLER_VERSION = "0.10.0";
+export const RUNTIME_VERSION = "0.10.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-10.1";