@halofy/agent-connect 0.9.0 → 0.11.0

package/README.md

@@ -1,7 +1,7 @@
 # Halofy agent lifecycle installer
 
-Status: production release candidate; activation remains gated on exact npm
-publication and deployed protocol verification.
+Status: published installer (`@halofy/agent-connect@0.10.0`). The deployment
+workflow pins the verified tarball; host loading requires separate verification.
 
 This package contains the host-neutral client pieces for installation-bound
 agent connections:
@@ -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,85 @@ 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.
+
+## Connection health and local pause (0.11.0 source)
+
+This source version adds a signed heartbeat immediately and every 60 seconds
+while the existing MCP proxy runs. It inspects the installation's managed hook
+and MCP configuration without repairing it. Health contains only a state; local
+paths stay on disk. Legacy installations without inspection metadata report
+`unknown`. Missing contact may mean an idle host, sleep, or network loss, and
+cannot establish that an employee uninstalled the integration.
+
+Use the installed runtime executable with `pause --connection <installation-id>`
+or `resume --connection <installation-id>`. Pause persists for that installation,
+attempts a bounded flush of already queued events, and skips subsequent capture
+hooks. It does not block MCP. Resume reports inspected health and excludes older
+transcript bodies from catch-up, so paused content is not backfilled. A failed
+state report is retried by the next running-proxy heartbeat or session start.
+
+JSON configuration checks require every managed hook registration and MCP entry.
+Changed Kimi/Codex TOML is conservative: removed/disabled managed configuration
+reports `hooks_missing`; other changes report `unknown` pending reinstallation.
+This package does not add a TOML parser or a device-wide monitoring daemon.
+
+The 0.11.0 source is not proof of a published or deployed artifact. Release must
+publish the exact reviewed npm package, verify its integrity, update the server's
+pinned installer artifact through its existing release process, and prove an
+updated disposable installation. Existing local runtimes do not auto-upgrade.
+
+## Organization instructions (0.10.0)
+
+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/bin/halofy-agent.mjs

@@ -5,6 +5,8 @@ import { runStdioMcpProxy } from "../src/mcp-proxy.mjs";
 import { BoundedEncryptedQueue } from "../src/queue.mjs";
 import { runClaudeLifecycleHook } from "../src/claude-hook.mjs";
 import { HOST_HOOK_EVENTS, runHostLifecycleHook } from "../src/host-hook.mjs";
+import { LifecycleRuntime } from "../src/runtime.mjs";
+import { setCapturePaused } from "../src/health.mjs";
 import { join } from "node:path";
 
 function option(name) {
@@ -18,9 +20,9 @@ const claudeHookEvents = new Set([
   "SessionStart", "UserPromptSubmit", "Stop", "PreCompact", "SessionEnd",
   "SubagentStart", "SubagentStop", "PostToolUse", "PostToolUseFailure", "PostToolBatch",
 ]);
-if (!["mcp", "diagnostics", "hook"].includes(command) ||
+if (!["mcp", "diagnostics", "hook", "pause", "resume"].includes(command) ||
     (command === "hook" && !claudeHookEvents.has(hookEvent) && !HOST_HOOK_EVENTS.has(hookEvent))) {
-  process.stderr.write("Usage: halofy-agent <mcp|diagnostics|hook EVENT> [--connection <installation-id>]\n");
+  process.stderr.write("Usage: halofy-agent <mcp|diagnostics|hook EVENT|pause|resume> [--connection <installation-id>]\n");
   process.exitCode = 2;
 } else {
   try {
@@ -31,6 +33,10 @@ if (!["mcp", "diagnostics", "hook"].includes(command) ||
     if (!connection) throw new Error("no active installation-bound connection");
     if (command === "mcp") {
       await runStdioMcpProxy(connection);
+    } else if (command === "pause" || command === "resume") {
+      const root = defaultRuntimeDirectory();
+      const runtime = new LifecycleRuntime(connection, { root });
+      process.stdout.write(`${JSON.stringify(await setCapturePaused(runtime, root, command === "pause"))}\n`);
     } else if (command === "hook") {
       if (connection.clientKind === "claude-code") await runClaudeLifecycleHook(connection, hookEvent);
       else await runHostLifecycleHook(connection, hookEvent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.9.0",
+  "version": "0.11.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

@@ -1,3 +1,4 @@
+import { captureStateSnapshot } from "./health.mjs";
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
@@ -91,11 +92,27 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     const hookInput = input ?? await readHookInput();
     const session = hostSession(hookInput);
     if (!session) return { handled: true };
-    const runtime = runtimeFactory(connection, { root });
+    const capture = await captureStateSnapshot(root, connection.installationId);
+    const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
+    if (capture.paused) {
+      if (eventName === "SessionStart") {
+        await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
+        // Capture pause does not suspend governed instruction delivery.
+        await runtime.syncInstructions?.().catch(() => {});
+        await runtime.heartbeat(connection.capabilities || {});
+      } else if (eventName === "UserPromptSubmit") {
+        const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
+        const output = recallText(null, "UserPromptSubmit", delivery.notice);
+        if (output) stdout.write(output);
+      }
+      return { handled: true, paused: true };
+    }
 
     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/health.mjs

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { SignedRuntimeTransport } from "./transport.mjs";
+import { readJson, writePrivateFile, withFileLock } from "./storage.mjs";
+
+const statePath = (root, id) => join(root, id, "capture-state.json");
+const targetsPath = (root, id) => join(root, id, "health-targets.json");
+
+export async function capturePaused(root, installationId) {
+  // Corrupt local state cannot silently enable capture.
+  try { return (await readJson(statePath(root, installationId)))?.paused === true; }
+  catch { return true; }
+}
+
+export async function captureStateSnapshot(root, installationId) {
+  try {
+    const state = await readJson(statePath(root, installationId), {});
+    return { paused: state.paused === true, generation: state.generation ?? null, captureAfter: state.captureAfter ?? null };
+  } catch { return { paused: true, generation: null, captureAfter: null }; }
+}
+
+export async function captureAdmission(root, installationId, generation) {
+  const current = await captureStateSnapshot(root, installationId);
+  return !current.paused && current.generation === generation;
+}
+
+/** Local-only install metadata. Never send paths or commands as health evidence. */
+export async function recordHealthTargets({ root, installationId, configured, runtimePath }) {
+  const paths = configured.configuredPaths || [configured.mcpPath, configured.settingsPath];
+  const targets = [];
+  const foundEvents = new Set();
+  for (const path of paths) {
+    const text = await readFile(path, "utf8");
+    if (path.endsWith(".json")) {
+      const value = JSON.parse(text);
+      const hooks = {};
+      for (const event of configured.hookEvents) {
+        const entries = value.hooks?.[event];
+        if (!Array.isArray(entries)) continue;
+        const managed = entries.filter((entry) => JSON.stringify(entry).includes(installationId) &&
+          JSON.stringify(entry).includes("--connection"));
+        if (managed.length) { hooks[event] = managed; foundEvents.add(event); }
+      }
+      const registry = value.mcpServers ? "mcpServers" : value.servers ? "servers" : null;
+      targets.push({ path, kind: "json", hooks, ...(registry ? { registry, mcp: value[registry].halofy } : {}) });
+    } else {
+      // TOML is deliberately conservative: without a bundled TOML parser a
+      // changed document cannot prove that hooks are still enabled.
+      const managedText = text.match(/# BEGIN HALOFY LIFECYCLE[\s\S]*?# END HALOFY LIFECYCLE/)?.[0];
+      targets.push({ path, kind: path.endsWith(".toml") ? "toml" : "script", text,
+        ...(managedText ? { managedText } : {}) });
+      for (const event of configured.hookEvents) {
+        if (text.includes(`event = ${JSON.stringify(event)}`) || path.endsWith(`/${event}`)) foundEvents.add(event);
+      }
+    }
+  }
+  if (configured.hookEvents.some((event) => !foundEvents.has(event))) throw new Error("managed hook inspection metadata incomplete");
+  await writePrivateFile(targetsPath(root, installationId), JSON.stringify({ version: 1, runtimePath, targets }));
+}
+
+function disabled(value) {
+  return value?.enabled === false || value?.disabled === true || value?.disableAllHooks === true;
+}
+
+export async function inspectCaptureHealth(connection, root) {
+  if (await capturePaused(root, connection.installationId)) return { captureState: "paused" };
+  let metadata;
+  try { metadata = await readJson(targetsPath(root, connection.installationId)); }
+  catch { return { captureState: "unknown" }; }
+  if (metadata?.version !== 1 || !metadata.targets?.length) return { captureState: "unknown" };
+  let unknown = false;
+  try {
+    if (!(await stat(metadata.runtimePath)).isFile()) return { captureState: "hooks_missing" };
+    for (const target of metadata.targets) {
+      const text = await readFile(target.path, "utf8");
+      if (target.kind === "json") {
+        const value = JSON.parse(text);
+        if (disabled(value) || disabled(value.hooks) || value.hooksConfig?.enabled === false) return { captureState: "hooks_missing" };
+        for (const [event, expected] of Object.entries(target.hooks)) {
+          const entries = value.hooks?.[event];
+          if (!Array.isArray(entries) || !expected.every((entry) => entries.some((actual) =>
+            !disabled(actual) && isDeepStrictEqual(actual, entry)))) return { captureState: "hooks_missing" };
+        }
+        if (target.registry && (!isDeepStrictEqual(value[target.registry]?.halofy, target.mcp) ||
+            disabled(value[target.registry]?.halofy))) return { captureState: "hooks_missing" };
+      } else if (target.kind === "script") {
+        if (text !== target.text || (process.platform !== "win32" && ((await stat(target.path)).mode & 0o111) === 0)) {
+          return { captureState: "hooks_missing" };
+        }
+      } else if (text !== target.text) {
+        if ((target.managedText && !text.includes(target.managedText)) || /^\s*(?:hooks|enabled)\s*=\s*false\b/m.test(text) ||
+            !text.includes(connection.installationId) || !text.includes("--connection")) return { captureState: "hooks_missing" };
+        unknown = true;
+      }
+    }
+  } catch (error) {
+    return { captureState: error?.code === "ENOENT" || error instanceof SyntaxError ? "hooks_missing" : "unknown" };
+  }
+  return { captureState: unknown ? "unknown" : "active" };
+}
+
+/** Pause applies before flushing so concurrent future hooks cannot enqueue. */
+export async function setCapturePaused(runtime, root, paused, { flushTimeoutMs = 5_000 } = {}) {
+  // Queue admission and pause persistence share a short lock. A capture read
+  // may still be running, but cannot enqueue across this state transition.
+  await withFileLock(runtime.queue.lockPath, async () => {
+    const previous = await readJson(statePath(root, runtime.connection.installationId), {});
+    const now = new Date().toISOString();
+    const resumedAt = !paused && previous.paused === true ? now : previous.captureAfter;
+    await writePrivateFile(statePath(root, runtime.connection.installationId), JSON.stringify({
+      paused, changedAt: now, generation: randomUUID(), ...(resumedAt ? { captureAfter: resumedAt } : {}),
+    }));
+  });
+  let flushed = null;
+  if (paused) {
+    // Dedicated flush transport has one deadline for the entire replay, not
+    // one fresh timeout for every batch. The existing proxy keeps running.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), flushTimeoutMs);
+    try {
+      const flushRuntime = new runtime.constructor(runtime.connection, { root,
+        transport: new SignedRuntimeTransport(runtime.connection, {
+          fetchImpl: runtime.transport.fetch, signal: controller.signal, timeoutMs: flushTimeoutMs,
+        }),
+      });
+      await flushRuntime.replay();
+      flushed = true;
+    } catch { flushed = false; }
+    finally { clearTimeout(timer); }
+  }
+  let reported = false;
+  try { await runtime.heartbeat(runtime.connection.capabilities || {}); reported = true; } catch { /* next proxy tick retries */ }
+  return { paused, reported, ...(paused ? { flushed } : {}) };
+}
+
+/** No overlapping checks and no timers survive proxy shutdown. */
+export function startHealthHeartbeat(runtime, {
+  intervalMs = 60_000,
+  setIntervalImpl = setInterval,
+  clearIntervalImpl = clearInterval,
+} = {}) {
+  let stopped = false;
+  let pending = null;
+  const tick = () => {
+    if (stopped || pending) return pending;
+    pending = Promise.resolve().then(() => runtime.heartbeat(runtime.connection.capabilities || {}))
+      .catch(() => {}).finally(() => { pending = null; });
+    return pending;
+  };
+  void tick();
+  const timer = setIntervalImpl(() => { void tick(); }, intervalMs);
+  timer?.unref?.();
+  return { tick, stop() { stopped = true; clearIntervalImpl(timer); } };
+}

package/src/host-hook.mjs

@@ -1,3 +1,4 @@
+import { captureStateSnapshot } from "./health.mjs";
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
@@ -156,11 +157,27 @@ export async function runHostLifecycleHook(connection, eventName, {
     const hookInput = input ?? await readHookInput();
     const session = hostSession(hookInput);
     if (!session) return { handled: true, unavailable: "missing_host_session" };
-    const runtime = runtimeFactory(connection, { root });
+    const capture = await captureStateSnapshot(root, connection.installationId);
+    const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
+    if (capture.paused) {
+      if (START_EVENTS.has(eventName)) {
+        await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
+        // Capture pause does not suspend governed instruction delivery.
+        await runtime.syncInstructions?.().catch(() => {});
+        await runtime.heartbeat(connection.capabilities || {});
+      } else if (USER_EVENTS.has(eventName)) {
+        const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
+        const output = recallOutput(connection.clientKind, eventName, null, delivery.notice);
+        if (output) stdout.write(output);
+      }
+      return { handled: true, paused: true };
+    }
 
     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,7 +4,9 @@ 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 { inspectCaptureHealth } from "./health.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";
@@ -151,6 +153,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 +204,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({
@@ -217,6 +222,7 @@ export async function installLocalConnection({
     try {
       await new SignedRuntimeTransport(connection, { fetchImpl }).heartbeat(client.capabilities, {
         pluginVersion: RUNTIME_VERSION,
+        health: await inspectCaptureHealth(connection, root),
         proofStorage,
         diagnostics: { queueDepth: 0, oldestPendingAt: null, expiredCount: 0 },
       });
@@ -225,9 +231,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,
@@ -266,6 +276,7 @@ export async function heartbeatInstalledConnection({
   const connection = await new ConnectionStore(root).load(installationId);
   await new SignedRuntimeTransport(connection, { fetchImpl }).heartbeat(connection.capabilities, {
     pluginVersion: connection.pluginVersion,
+    health: await inspectCaptureHealth(connection, root),
     proofStorage: connection.proofStorage,
     diagnostics: { queueDepth: 0, oldestPendingAt: null, expiredCount: 0 },
   });

package/src/installer-cli.mjs

@@ -1,3 +1,4 @@
+import { recordHealthTargets } from "./health.mjs";
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
@@ -16,6 +17,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 +197,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 +252,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 +357,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,
@@ -361,6 +365,7 @@ async function runAllInstaller(input, {
         serverUrl: input.serverUrl,
         runtimePath: bundle.runtimePath,
       }, { claudeConfigPath });
+      await recordHealthTargets({ root, installationId: installed.installationId, configured, runtimePath: bundle.runtimePath });
       let heartbeat = false;
       try {
         heartbeat = await heartbeatInstalledConnection({
@@ -383,6 +388,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 +454,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 = {
@@ -457,6 +464,7 @@ export async function runInstaller(argv, {
     runtimePath: bundle.runtimePath,
   };
   const configured = await configureHost(input.clientKind, common, { claudeConfigPath });
+  await recordHealthTargets({ root, installationId: installed.installationId, configured, runtimePath: bundle.runtimePath });
   let heartbeat = false;
   try {
     heartbeat = await heartbeatInstalledConnection({
@@ -477,6 +485,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/mcp-proxy.mjs

@@ -1,3 +1,6 @@
+import { LifecycleRuntime } from "./runtime.mjs";
+import { defaultRuntimeDirectory } from "./storage.mjs";
+import { startHealthHeartbeat } from "./health.mjs";
 import { createInterface } from "node:readline";
 import { SignedRuntimeTransport } from "./transport.mjs";
 
@@ -24,34 +27,45 @@ export async function runStdioMcpProxy(connection, {
   input = process.stdin,
   output = process.stdout,
   fetchImpl = globalThis.fetch,
+  root = defaultRuntimeDirectory(),
+  heartbeatOptions,
 } = {}) {
+  const healthController = new AbortController();
+  const healthRuntime = new LifecycleRuntime(connection, { root, transport: new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 5_000, signal: healthController.signal }) });
+  const heartbeat = startHealthHeartbeat(healthRuntime, heartbeatOptions);
   const transport = new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 30_000 });
   let mcpSessionId = null;
   const lines = createInterface({ input, crlfDelay: Infinity });
-  for await (const line of lines) {
-    if (!line.trim()) continue;
-    let parsed;
-    try { parsed = JSON.parse(line); } catch { continue; }
-    try {
-      const response = await transport.request("/mcp", {
-        body: JSON.stringify(parsed),
-        headers: {
-          Accept: "application/json, text/event-stream",
-          ...(mcpSessionId ? { "Mcp-Session-Id": mcpSessionId } : {}),
-        },
-        raw: true,
-      });
-      mcpSessionId = response.headers.get("mcp-session-id") || mcpSessionId;
-      await relayResponse(response, parsed, output);
-    } catch {
-      if (parsed.id !== undefined) {
-        output.write(`${JSON.stringify({
-          jsonrpc: "2.0",
-          id: parsed.id,
-          error: { code: -32000, message: "Halofy MCP transport unavailable" },
-        })}\n`);
+  try {
+    for await (const line of lines) {
+      if (!line.trim()) continue;
+      let parsed;
+      try { parsed = JSON.parse(line); } catch { continue; }
+      try {
+        const response = await transport.request("/mcp", {
+          body: JSON.stringify(parsed),
+          headers: {
+            Accept: "application/json, text/event-stream",
+            ...(mcpSessionId ? { "Mcp-Session-Id": mcpSessionId } : {}),
+          },
+          raw: true,
+        });
+        mcpSessionId = response.headers.get("mcp-session-id") || mcpSessionId;
+        await relayResponse(response, parsed, output);
+      } catch {
+        if (parsed.id !== undefined) {
+          output.write(`${JSON.stringify({
+            jsonrpc: "2.0",
+            id: parsed.id,
+            error: { code: -32000, message: "Halofy MCP transport unavailable" },
+          })}\n`);
+        }
       }
     }
+  } finally {
+    heartbeat.stop();
+    healthController.abort();
+    lines.close();
   }
 }
 

package/src/queue.mjs

@@ -141,10 +141,12 @@ export class BoundedEncryptedQueue {
     maxBatchEvents = 100,
     maxBatchBytes = 1024 * 1024,
     acknowledgedSequence = 0,
+    canEnqueue,
   } = {}) {
     return withFileLock(this.lockPath, async () => {
       const state = await this.#read();
       this.#sweep(state);
+      if (canEnqueue && !await canEnqueue()) return { queued: 0, skipped: true };
       const pending = state.items.filter((item) => item.sessionHash === sessionHash).flatMap((item) => item.events || []);
       const existingKeys = new Set(pending.map((event) => event.eventKey));
       let sequence = pending.reduce(

package/src/runtime.mjs

@@ -8,19 +8,26 @@ import {
 import { claudeTranscriptDriver } from "./transcript-drivers/claude.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { readJson, withFileLock, writePrivateFile } from "./storage.mjs";
+import { capturePaused, captureStateSnapshot, captureAdmission, inspectCaptureHealth } from "./health.mjs";
+import { syncAgentInstructions } from "./instructions.mjs";
 import { RUNTIME_VERSION } from "./version.mjs";
 
 export class LifecycleRuntime {
   constructor(connection, {
     root,
     transport = new SignedRuntimeTransport(connection),
+    instructionTransport = new SignedRuntimeTransport(connection, { timeoutMs: 2_000 }),
     maxBatchEvents = 100,
     maxBatchBytes = 1024 * 1024,
     commitThreshold = 20,
+    captureGeneration,
   } = {}) {
     if (!root) throw new Error("runtime storage root is required");
     this.connection = connection;
+    this.root = root;
+    this.captureGeneration = captureGeneration;
     this.transport = transport;
+    this.instructionTransport = instructionTransport;
     const connectionRoot = join(root, connection.installationId);
     this.queue = new BoundedEncryptedQueue(connectionRoot);
     this.cursors = new CursorStore(connectionRoot);
@@ -32,6 +39,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,
@@ -115,18 +129,23 @@ export class LifecycleRuntime {
   }
 
   async captureHostTranscript(hostSessionId, driver, transcriptPath, sessionFacts = {}) {
+    const capture = await captureStateSnapshot(this.root, this.connection.installationId);
+    if (capture.paused) return { queued: 0, acknowledged: 0, paused: true };
     const sessionHash = this.sessionHash(hostSessionId);
     const policy = await this.capturePolicy();
     const queued = await withFileLock(this.operationLockPath, async () => {
+      if (await capturePaused(this.root, this.connection.installationId)) return { queued: 0 };
       const cursor = await this.cursors.get(sessionHash);
-      const suffix = await driver.readSuffix(transcriptPath, cursor, sessionHash);
+      const resumedAt = capture.captureAfter;
+      const suffix = await driver.readSuffix(transcriptPath, cursor, sessionHash, { captureAfter: resumedAt });
       const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
-      const unseenEvents = suffix.events.filter((event) => !recentEventKeys.has(event.eventKey));
+      const unseenEvents = suffix.events.filter((event) => !recentEventKeys.has(event.eventKey) &&
+        (!resumedAt || Date.parse(event.occurredAt) >= Date.parse(resumedAt)));
       // One metadata event whenever the observed content-free session facts
       // change. The event key hashes the payload, so an unchanged snapshot is
       // deduplicated exactly like any repeated event.
       const metadataPayload = driver.buildMetadataPayload(
-        { ...suffix.metadata, ...sessionFacts },
+        { ...suffix.metadata, ...(!resumedAt ? sessionFacts : {}) },
         { installationId: this.connection.installationId, deviceContext: policy.deviceContext },
       );
       if (Object.keys(metadataPayload).length > 0) {
@@ -141,7 +160,9 @@ export class LifecycleRuntime {
           maxBatchEvents: this.maxBatchEvents,
           maxBatchBytes: this.maxBatchBytes,
           acknowledgedSequence: cursor.sequence,
+          canEnqueue: () => captureAdmission(this.root, this.connection.installationId, this.captureGeneration === undefined ? capture.generation : this.captureGeneration),
         });
+      if (result.skipped) return result;
       // Complete ignored/malformed JSONL records carry no event, while every
       // normalized event is already durable in the encrypted queue. Advancing
       // this byte cursor prevents unbounded reparsing without advancing the
@@ -166,36 +187,44 @@ export class LifecycleRuntime {
   }
 
   async enqueueEvents(hostSessionId, events) {
+    const capture = await captureStateSnapshot(this.root, this.connection.installationId);
+    if (capture.paused) return { queued: 0, acknowledged: 0, paused: true };
     const sessionHash = this.sessionHash(hostSessionId);
     await withFileLock(this.operationLockPath, async () => {
-      await this.#enqueueEventsUnlocked(sessionHash, events);
+      if (await capturePaused(this.root, this.connection.installationId)) return;
+      await this.#enqueueEventsUnlocked(sessionHash, events, undefined, this.captureGeneration === undefined ? capture.generation : this.captureGeneration);
     });
     return this.replay();
   }
 
   async enqueueSequencedEvents(hostSessionId, factory) {
+    const capture = await captureStateSnapshot(this.root, this.connection.installationId);
+    if (capture.paused) return { queued: 0, acknowledged: 0, paused: true };
     const sessionHash = this.sessionHash(hostSessionId);
     await withFileLock(this.operationLockPath, async () => {
+      if (await capturePaused(this.root, this.connection.installationId)) return;
       const cursor = await this.cursors.get(sessionHash);
       const events = factory({ sessionHash, nextSequence: cursor.sequence + 1 });
       if (!Array.isArray(events) || events.length < 1 || events.length > this.maxBatchEvents) {
         throw new Error("sequenced host event batch is invalid");
       }
-      await this.#enqueueEventsUnlocked(sessionHash, events, cursor);
+      await this.#enqueueEventsUnlocked(sessionHash, events, cursor, this.captureGeneration === undefined ? capture.generation : this.captureGeneration);
     });
     return this.replay();
   }
 
-  async #enqueueEventsUnlocked(sessionHash, events, knownCursor) {
+  async #enqueueEventsUnlocked(sessionHash, events, knownCursor, generation) {
     const cursor = knownCursor || await this.cursors.get(sessionHash);
     const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
     const unseenEvents = events.filter((event) => !recentEventKeys.has(event.eventKey));
     if (unseenEvents.length === 0) return;
-    await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
+    const result = await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
       maxBatchEvents: this.maxBatchEvents,
       maxBatchBytes: this.maxBatchBytes,
       acknowledgedSequence: cursor.sequence,
+      canEnqueue: () => captureAdmission(this.root, this.connection.installationId, generation),
     });
+    if (result.skipped) return;
     await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
   }
 
@@ -290,6 +319,7 @@ export class LifecycleRuntime {
     const queue = await this.queue.diagnostics();
     const usageGaps = await this.cursors.peekUsageGaps();
     const response = await this.transport.heartbeat(capabilities, {
+      health: await inspectCaptureHealth(this.connection, this.root),
       pluginVersion: this.connection.pluginVersion || `${RUNTIME_VERSION}-local`,
       proofStorage: this.connection.proofStorage || "unknown",
       diagnostics: {

package/src/session.mjs

@@ -664,7 +664,7 @@ function collectClaudeMetadata(metadata, entry) {
   if (cwd) metadata.cwd = cwd;
 }
 
-export async function readClaudeTranscriptSuffix(path, cursor, sessionHash) {
+export async function readClaudeTranscriptSuffix(path, cursor, sessionHash, { captureAfter } = {}) {
   const bytes = await readFile(path);
   const start = Number.isSafeInteger(cursor?.byteOffset) && cursor.byteOffset <= bytes.length ? cursor.byteOffset : 0;
   const suffix = bytes.subarray(start);
@@ -691,6 +691,10 @@ export async function readClaudeTranscriptSuffix(path, cursor, sessionHash) {
     };
     try {
       const entry = JSON.parse(raw);
+      // Filter raw records before fallback timestamps, metadata collection, or
+      // normalization. Unknown source time cannot prove post-resume consent.
+      if (captureAfter && !(typeof entry?.timestamp === "string" &&
+          Date.parse(entry.timestamp) >= Date.parse(captureAfter))) continue;
       if (entry !== null && typeof entry === "object") {
         collectClaudeMetadata(metadata, entry);
         if (entry.type === "assistant" && Array.isArray(entry.message?.content)) {
@@ -705,7 +709,7 @@ export async function readClaudeTranscriptSuffix(path, cursor, sessionHash) {
       }
       events.push(...normalizeClaudeTranscriptEntry(entry, evidence));
     } catch {
-      events.push(normalizeMalformedClaudeTranscriptLine(rawBytes, evidence));
+      if (!captureAfter) events.push(normalizeMalformedClaudeTranscriptLine(rawBytes, evidence));
     }
   }
   // Claude repeats the same usage record on every JSONL line of a multi-block

package/src/transcript-drivers/claude.mjs

@@ -19,8 +19,8 @@ export const claudeTranscriptDriver = {
     return null;
   },
 
-  readSuffix(path, cursor, sessionHash) {
-    return readClaudeTranscriptSuffix(path, cursor, sessionHash);
+  readSuffix(path, cursor, sessionHash, options) {
+    return readClaudeTranscriptSuffix(path, cursor, sessionHash, options);
   },
 
   buildMetadataPayload(metadata, context) {

package/src/transcript-drivers/codex.mjs

@@ -124,7 +124,7 @@ export const codexTranscriptDriver = {
     return path === null ? null : { path };
   },
 
-  async readSuffix(path, cursor, _sessionHash) {
+  async readSuffix(path, cursor, _sessionHash, { captureAfter } = {}) {
     const { buffer, start } = await readSuffixWindow(path, cursor?.byteOffset ?? 0);
     const priorState = cursor?.hostState !== null && typeof cursor?.hostState === "object"
       ? cursor.hostState : {};
@@ -139,6 +139,7 @@ export const codexTranscriptDriver = {
       lastEnd = line.endOffset;
       const entry = line.entry;
       if (entry === null) continue;
+      if (captureAfter && !(typeof entry.timestamp === "string" && Date.parse(entry.timestamp) >= Date.parse(captureAfter))) continue;
       const payload = entry.payload !== null && typeof entry.payload === "object" ? entry.payload : {};
       const occurredAt = typeof entry.timestamp === "string" ? entry.timestamp : new Date().toISOString();
       if (entry.type === "session_meta") {

package/src/transcript-drivers/kimi.mjs

@@ -146,7 +146,7 @@ export const kimiTranscriptDriver = {
     return { path: located.path, sessionFacts };
   },
 
-  async readSuffix(path, cursor, _sessionHash) {
+  async readSuffix(path, cursor, _sessionHash, { captureAfter } = {}) {
     const { buffer, start } = await readSuffixWindow(path, cursor?.byteOffset ?? 0);
     const metadata = {};
     const events = [];
@@ -155,6 +155,7 @@ export const kimiTranscriptDriver = {
       lastEnd = line.endOffset;
       const entry = line.entry;
       if (entry === null) continue;
+      if (captureAfter && !(Number.isSafeInteger(entry.time) && entry.time >= Date.parse(captureAfter))) continue;
       if (entry.type === "usage.record") {
         events.push(usageEventFromRecord(entry, {
           byteOffset: line.byteOffset,

package/src/transport.mjs

@@ -15,10 +15,11 @@ export class RuntimeHttpError extends Error {
 }
 
 export class SignedRuntimeTransport {
-  constructor(connection, { fetchImpl = globalThis.fetch, timeoutMs = 8_000 } = {}) {
+  constructor(connection, { fetchImpl = globalThis.fetch, timeoutMs = 8_000, signal } = {}) {
     this.connection = connection;
     this.fetch = fetchImpl;
     this.timeoutMs = timeoutMs;
+    this.signal = signal;
   }
 
   async request(path, { method = "POST", body, headers = {}, raw = false, maxResponseBytes } = {}) {
@@ -43,7 +44,7 @@ export class SignedRuntimeTransport {
           ...headers,
         },
         body: body === undefined ? undefined : bodyBytes,
-        signal: controller.signal,
+        signal: this.signal ? AbortSignal.any([controller.signal, this.signal]) : controller.signal,
       });
       if (!response.ok) {
         if (maxResponseBytes !== undefined) {
@@ -76,15 +77,15 @@ export class SignedRuntimeTransport {
           return JSON.parse(Buffer.concat(chunks).toString("utf8"));
         } finally { reader.releaseLock(); }
       }
-      return response.json();
+      return await response.json();
     } finally {
       clearTimeout(timer);
     }
   }
 
-  heartbeat(capabilities, { pluginVersion, proofStorage, diagnostics }) {
+  heartbeat(capabilities, { pluginVersion, proofStorage, diagnostics, health }) {
     return this.request("/v1/agent-runtime/heartbeat", {
-      body: { pluginVersion, capabilities, proofStorage, ...(diagnostics ? { diagnostics } : {}) },
+      body: { pluginVersion, capabilities, proofStorage, ...(diagnostics ? { diagnostics } : {}), ...(health ? { health } : {}) },
     });
   }
 
@@ -105,6 +106,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.11.0";
+export const RUNTIME_VERSION = "0.11.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-10.1";