@halofy/agent-connect 0.10.0 → 0.12.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:
@@ -22,7 +22,28 @@ conversations and serves the agent-invoked MCP memory tools, but does not push
 recalled memory into host sessions on session start or prompt submit. The
 bounded recall block formats stay in place and tested for when it returns.
 
-There is one setup path for every packaged client:
+## Browser sign-in (0.12.0 source)
+
+Users assigned to a team can run the installer without a manually copied badge:
+
+```bash
+npx @halofy/agent-connect@0.12.0 install claude-code --server https://app.halofy.ai
+```
+
+`login <client-kind> --server <origin>` is an alias for the same installation
+flow. The installer opens the existing Halofy sign-in page, displays a public
+verification code, and waits for the user to confirm their authorized team and
+device. Google sign-in is available through the existing console authentication.
+A per-installation Ed25519 key is saved privately before enrollment; the approval
+claim is bound to that same key. Device secrets and claims are never printed or
+put in browser URLs. Retry a failed/expired sign-in with the same command; the
+pending key survives retries. Installation still requires the terminal's
+explicit CONNECT disclosure before changing host configuration.
+
+This source version requires the matching server enrollment endpoints and a
+published 0.12.0 package before the npx example can be used remotely. The existing
+manual claim path remains supported:
+
 
 ```bash
 npx --yes @halofy/agent-connect@0.10.0 install <client-kind> \
@@ -155,7 +176,34 @@ confirm delivery status. Existing offline skill limits remain; context refresh
 failures withdraw the managed references. These are source capabilities; package
 publication, installed-client upgrades and production deployment require separate
 release verification.
-## Organization instructions (0.10.0 release candidate)
+
+## 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

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.10.0",
+  "version": "0.12.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,7 +92,21 @@ 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.

package/src/enrollment.mjs

@@ -0,0 +1,83 @@
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { generateInstallationKeyPair } from "./crypto.mjs";
+import { normalizeLifecycleServerUrl } from "./install.mjs";
+import { readJson, writePrivateFile, defaultRuntimeDirectory } from "./storage.mjs";
+import { CLIENT_KINDS } from "./client-registry.mjs";
+
+export async function prepareInstallationKey(root, clientKind) {
+  const path = join(root, `pending-${clientKind}.json`);
+  const previous = await readJson(path);
+  if (previous) {
+    if (!previous.publicJwk || !previous.privateJwk || !previous.installationIdCandidate) {
+      throw new Error("pending installation key is invalid; repair local runtime storage before retrying");
+    }
+    return previous;
+  }
+  const key = { ...generateInstallationKeyPair(), installationIdCandidate: `local_${randomUUID()}` };
+  await writePrivateFile(path, `${JSON.stringify(key)}\n`);
+  return key;
+}
+
+export function openVerificationBrowser(uri) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", uri] : [uri];
+  const child = spawn(command, args, { shell: false, detached: true, stdio: "ignore" });
+  child.on("error", () => {}); // Printed URL remains usable when there is no desktop browser.
+  child.unref();
+}
+
+/** Device secrets stay in memory. Only the public human code reaches browser/terminal. */
+export async function enrollWithBrowser({ serverUrl, clientKind, root = defaultRuntimeDirectory(),
+  fetchImpl = globalThis.fetch, output = process.stdout, openBrowser = openVerificationBrowser,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now }) {
+  if (!CLIENT_KINDS.includes(clientKind)) throw new Error("unsupported enrollment client");
+  const server = normalizeLifecycleServerUrl(serverUrl);
+  const base = new URL(server);
+  if (!["https:", "http:"].includes(base.protocol) || base.username || base.password || base.search || base.hash || base.pathname !== "/") {
+    throw new Error("sign-in requires a server origin without credentials, path or query");
+  }
+  const key = await prepareInstallationKey(root, clientKind);
+  async function request(path, body) {
+    let response;
+    try {
+      response = await fetchImpl(`${server}/v1/agent-enrollment/${path}`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+        redirect: "error", signal: AbortSignal.timeout(15_000),
+      });
+    } catch { throw new Error("sign-in connection unavailable; retry sign-in"); }
+    if (!response.ok) {
+      throw new Error(response.status === 429 ? "sign-in rate limit reached; try again later" :
+        response.status === 410 ? "sign-in expired; retry sign-in" : "sign-in denied or unavailable; retry sign-in");
+    }
+    try { return await response.json(); } catch { throw new Error("invalid sign-in response"); }
+  }
+  const start = await request("start", { clientKind, publicKeyJwk: key.publicJwk });
+  let uri;
+  try { uri = new URL(start.verificationUri); } catch { throw new Error("invalid sign-in response"); }
+  if (typeof start.deviceCode !== "string" || !/^[A-Za-z0-9_-]{32,128}$/.test(start.deviceCode) ||
+      typeof start.userCode !== "string" || !/^[A-Za-z0-9-]{4,32}$/.test(start.userCode) ||
+      uri.origin !== base.origin || uri.username || uri.password || uri.pathname !== "/console/connect" ||
+      uri.hash || uri.search !== `?code=${start.userCode}` ||
+      !Number.isFinite(start.expiresIn) || start.expiresIn <= 0 || start.expiresIn > 1800 ||
+      !Number.isFinite(start.interval) || start.interval < 1 || start.interval > 60) {
+    throw new Error("invalid sign-in response");
+  }
+  const deadline = now() + start.expiresIn * 1000;
+  output.write(`Sign in and confirm this device: ${uri.href}\nCode: ${start.userCode}\n`);
+  try { await openBrowser(uri.href); } catch { /* URL is available for manual opening. */ }
+  while (now() < deadline) {
+    await sleep(start.interval * 1000);
+    if (now() >= deadline) break;
+    const token = await request("token", { deviceCode: start.deviceCode });
+    if (token.status === "pending") continue;
+    if (token.status === "expired") throw new Error("sign-in expired; retry sign-in");
+    if (token.status === "denied") throw new Error("sign-in denied; retry sign-in");
+    if (token.status !== "approved" || token.clientKind !== clientKind ||
+        typeof token.claim !== "string" || !/^hsc_[A-Za-z0-9_-]{43}$/.test(token.claim) ||
+        typeof token.organization !== "string" || !token.organization.trim()) throw new Error("invalid sign-in response");
+    return { claim: token.claim, organization: token.organization.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().slice(0, 100) };
+  }
+  throw new Error("sign-in expired; retry sign-in");
+}

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,7 +157,21 @@ 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.

package/src/install.mjs

@@ -6,6 +6,7 @@ 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";
@@ -221,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 },
       });
@@ -274,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,5 @@
+import { enrollWithBrowser } from "./enrollment.mjs";
+import { recordHealthTargets } from "./health.mjs";
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
@@ -77,9 +79,9 @@ export function parseInstallerArgs(argv) {
   }
   const serverUrl = values.get("--server");
   const claim = values.get("--claim");
-  if (command !== "install" || !CLIENT_KINDS.includes(clientKind) || !serverUrl || !claim ||
-      !/^hsc_[A-Za-z0-9_-]{43}$/.test(claim)) {
-    throw new Error("Usage: agent-connect install <supported-client> --server <https-url> --claim <one-use-claim>");
+  if (!["install", "login"].includes(command) || !CLIENT_KINDS.includes(clientKind) || !serverUrl ||
+      (claim !== undefined && !/^hsc_[A-Za-z0-9_-]{43}$/.test(claim))) {
+    throw new Error("Usage: agent-connect install|login <supported-client> --server <https-url> [--claim <one-use-claim>]");
   }
   return {
     mode: "single",
@@ -364,6 +366,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({
@@ -424,6 +427,9 @@ export async function runInstaller(argv, {
   sourceRoot,
   claudeConfigPath,
   skillsHome,
+  openBrowser,
+  enrollmentSleep,
+  enrollmentNow,
 } = {}) {
   const input = parseInstallerArgs(argv);
   if (input.mode === "all") {
@@ -433,7 +439,13 @@ export async function runInstaller(argv, {
     });
   }
   const clientVersion = input.clientKind === "claude-code" ? await detectClaude() : await detectHost(input.clientKind);
-  const claimDisclosure = await fetchClaimDisclosure({
+  const enrollment = !input.claim ? await enrollWithBrowser({
+    serverUrl: input.serverUrl, clientKind: input.clientKind, root, fetchImpl, output,
+    ...(openBrowser ? { openBrowser } : {}), ...(enrollmentSleep ? { sleep: enrollmentSleep } : {}),
+    ...(enrollmentNow ? { now: enrollmentNow } : {}),
+  }) : null;
+  if (enrollment) input.claim = enrollment.claim;
+  const claimDisclosure = enrollment || await fetchClaimDisclosure({
     serverUrl: input.serverUrl,
     claim: input.claim,
     fetchImpl,
@@ -462,6 +474,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({

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,6 +8,7 @@ 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";
 
@@ -19,10 +20,12 @@ export class LifecycleRuntime {
     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);
@@ -126,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) {
@@ -152,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
@@ -177,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));
   }
 
@@ -301,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 } : {}) },
     });
   }
 

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.10.0";
-export const RUNTIME_VERSION = "0.10.0";
+export const INSTALLER_VERSION = "0.12.0";
+export const RUNTIME_VERSION = "0.12.0";
 export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-10.1";