@halofy/agent-connect 0.12.0 → 0.12.1

package/README.md

@@ -1,7 +1,9 @@
 # Halofy agent lifecycle installer
 
-Status: published installer (`@halofy/agent-connect@0.10.0`). The deployment
-workflow pins the verified tarball; host loading requires separate verification.
+Status: source for `@halofy/agent-connect@0.12.1`; publication and deployment
+require separate verification. The production console supplies the command for
+the verified published package pinned by the deployment workflow. Host loading
+requires separate verification.
 
 This package contains the host-neutral client pieces for installation-bound
 agent connections:
@@ -22,12 +24,14 @@ 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.
 
-## Browser sign-in (0.12.0 source)
+## Browser sign-in
 
-Users assigned to a team can run the installer without a manually copied badge:
+Users assigned to a team can run the installer without a manually copied badge.
+Use the production console’s verified command. After 0.12.1 is published and
+verified, the command for this source version is:
 
 ```bash
-npx @halofy/agent-connect@0.12.0 install claude-code --server https://app.halofy.ai
+npx @halofy/agent-connect@0.12.1 install claude-code --server https://app.halofy.ai
 ```
 
 `login <client-kind> --server <origin>` is an alias for the same installation
@@ -40,13 +44,12 @@ 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:
-
+Browser sign-in requires the matching server enrollment endpoints. The example
+above does not establish that 0.12.1 is published or enabled in production. The
+manual claim path remains supported; after publication, its 0.12.1 form is:
 
 ```bash
-npx --yes @halofy/agent-connect@0.10.0 install <client-kind> \
+npx --yes @halofy/agent-connect@0.12.1 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -220,6 +223,16 @@ 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.
 
+Version 0.12.1 gives instruction GET and its best-effort status receipt one shared
+8-second deadline at startup or direct refresh, and 15 seconds during interactive
+installation. A failed GET preserves current instructions; a receipt timeout does
+not undo a completed local update or prove server acknowledgement. Other request
+and host-hook limits are unchanged; this is not a deadline guarantee for the
+whole startup sequence. Startup runs instruction sync alongside skill/reference
+delivery, including while capture is paused, so slow reference downloads or
+receipts do not hold up the instruction fetch. Replay and heartbeat still follow
+both refreshes.
+
 | 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 |

package/package.json

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

@@ -12,6 +12,15 @@ export async function syncSkillsAtSessionStart(runtime, connection, root, stderr
   return result.skills;
 }
 
+/** Disjoint owned files and locks let instructions refresh without waiting for
+ * skill/reference downloads or their receipt. Both settle before capture work. */
+export async function syncConfigurationAtSessionStart(runtime, connection, root, stderr, syncOptions = {}) {
+  await Promise.allSettled([
+    Promise.resolve().then(() => runtime.syncInstructions?.()),
+    syncSkillsAtSessionStart(runtime, connection, root, stderr, syncOptions),
+  ]);
+}
+
 function id(value) {
   return createHash("sha256").update(String(value)).digest("hex");
 }
@@ -96,9 +105,8 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     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(() => {});
+        // Capture pause does not suspend instruction or reference delivery.
+        await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
         await runtime.heartbeat(connection.capabilities || {});
       } else if (eventName === "UserPromptSubmit") {
         const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
@@ -110,9 +118,7 @@ export async function runClaudeLifecycleHook(connection, eventName, {
 
     if (eventName === "SessionStart") {
       // Refresh/withdraw local context even when replay or heartbeat fails.
-      await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-      // Instructions have their own brownout boundary, independent of recall.
-      await runtime.syncInstructions?.().catch(() => {});
+      await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
       if (RECALL_INJECTION_ENABLED) {

package/src/host-hook.mjs

@@ -9,7 +9,7 @@ import {
   rankedRecallBlocks,
 } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
-import { readHookInput, syncSkillsAtSessionStart } from "./claude-hook.mjs";
+import { readHookInput, syncConfigurationAtSessionStart } from "./claude-hook.mjs";
 import { syncManagedDelivery } from "./delivery-sync.mjs";
 import { transcriptDriverFor } from "./transcript-drivers/index.mjs";
 
@@ -161,9 +161,8 @@ export async function runHostLifecycleHook(connection, eventName, {
     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(() => {});
+        // Capture pause does not suspend instruction or reference delivery.
+        await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
         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" });
@@ -175,9 +174,7 @@ export async function runHostLifecycleHook(connection, eventName, {
 
     if (START_EVENTS.has(eventName)) {
       // Refresh/withdraw local context even when replay or heartbeat fails.
-      await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-      // Instructions have their own brownout boundary, independent of recall.
-      await runtime.syncInstructions?.().catch(() => {});
+      await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
       if (RECALL_INJECTION_ENABLED) {

package/src/install.mjs

@@ -4,7 +4,7 @@ import { chmod, cp, rename, rm, unlink } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { generateInstallationKeyPair } from "./crypto.mjs";
 import { ConnectionStore, defaultRuntimeDirectory, ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
-import { syncAgentInstructions } from "./instructions.mjs";
+import { INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS, syncAgentInstructions } from "./instructions.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { inspectCaptureHealth } from "./health.mjs";
 import { INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
@@ -232,7 +232,7 @@ export async function installLocalConnection({
     }
   }
   const instructions = instructionProfile
-    ? await syncAgentInstructions(connection, { root, transport: new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 2_000 }) })
+    ? await syncAgentInstructions(connection, { root, fetchImpl, timeoutMs: INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS })
     : undefined;
   return {
     installationId,

package/src/instructions.mjs

@@ -7,6 +7,9 @@ import { isActiveInstallation } from "./active.mjs";
 import { ConnectionStore, readJson } from "./storage.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 
+export const INSTRUCTION_SYNC_TIMEOUT_MS = 8_000;
+export const INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS = 15_000;
+
 const sha = (value) => createHash("sha256").update(value).digest("hex");
 const HEX = /^[a-f0-9]{64}$/;
 const MARKER = "<!-- HALOFY-INSTRUCTIONS:";
@@ -247,20 +250,32 @@ async function retirePredecessorInstructions(connection, root) {
   }
 }
 
-/** Separate best-effort operation: a failed GET never means remove instructions. */
-export async function syncAgentInstructions(connection, { root, transport = new SignedRuntimeTransport(connection, { timeoutMs: 2_000 }) } = {}) {
+/** Separate best-effort operation: a failed GET never means remove instructions.
+ * GET and receipt share one deadline so a slow receipt cannot double startup delay.
+ * An explicitly injected transport retains its own cancellation policy. */
+export async function syncAgentInstructions(connection, {
+  root, transport, fetchImpl = globalThis.fetch, timeoutMs = INSTRUCTION_SYNC_TIMEOUT_MS,
+} = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const activeTransport = transport ?? new SignedRuntimeTransport(connection, {
+    fetchImpl, timeoutMs, signal: controller.signal,
+  });
   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;
+    try {
+      if (!(await isActiveInstallation(connection, root))) return { ...receipt, status: "unsupported", reason: "inactive_installation" };
+      await retirePredecessorInstructions(connection, root);
+      const bundle = await activeTransport.instructions();
+      if (!transport) controller.signal.throwIfAborted();
+      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 activeTransport.instructionStatus(receipt); } catch { /* A receipt failure cannot disable capture/MCP. */ }
+    return receipt;
+  } finally { clearTimeout(timer); }
 }

package/src/runtime.mjs

@@ -16,7 +16,7 @@ export class LifecycleRuntime {
   constructor(connection, {
     root,
     transport = new SignedRuntimeTransport(connection),
-    instructionTransport = new SignedRuntimeTransport(connection, { timeoutMs: 2_000 }),
+    instructionTransport,
     maxBatchEvents = 100,
     maxBatchBytes = 1024 * 1024,
     commitThreshold = 20,

package/src/version.mjs

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