@halofy/agent-connect 0.8.0 → 0.10.0

package/src/installer-cli.mjs

@@ -10,16 +10,15 @@ 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 { instructionProfile } from "./instructions.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}$/;
 
@@ -197,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");
@@ -252,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}`,
   );
@@ -356,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,
@@ -371,18 +372,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,
@@ -395,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.`,
@@ -460,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 = {
@@ -479,20 +472,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",
@@ -501,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({
@@ -516,15 +498,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/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/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/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,