@halofy/agent-connect 0.5.0 → 0.6.0

package/README.md

@@ -16,10 +16,16 @@ agent connections:
 - a stdio-to-signed-Streamable-HTTP MCP proof proxy; and
 - one local claim consumer and proof runtime shared by every packaged adapter.
 
+Hook-driven recall injection is disabled in this release
+(`RECALL_INJECTION_ENABLED` in `src/session.mjs`): the runtime captures
+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:
 
 ```bash
-npx --yes @halofy/agent-connect@0.5.0 install <client-kind> \
+npx --yes @halofy/agent-connect@0.6.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -44,7 +50,10 @@ to conversation-capture evidence by its name.
 
 Run the server-returned command in the operating-system terminal from the
 computer where the selected client runs, never in agent chat. The installer displays
-the capture disclosure, requires the recipient to type `CONNECT`, generates
+the capture disclosure — including the organization the claim binds to, fetched
+from the named server so a spoofed `--server` is recognizable before
+confirmation (`unverified` when the server cannot identify the claim) —
+requires the recipient to type `CONNECT`, generates
 the Ed25519 private key locally, consumes the one-use claim in a JSON body,
 copies the reviewed runtime out of the transient npx cache, and installs the
 signed MCP proxy and lifecycle hooks together. It replaces an existing Halofy
@@ -72,6 +81,20 @@ represented by digest-only placeholders and make coverage partial;
 encrypted retry queue, and real-host fixtures are verified. The adapter never
 opens an arbitrary transcript-referenced local file to fill that gap.
 
+Since 0.6.0, reviewed transcript drivers extend host-reported token usage and
+content-free session metadata to Codex CLI (rollout files) and Kimi Code CLI
+(session wire files). The same containment commitment applies: a driver never
+opens a hook-supplied path. It derives the session file from a validated
+session id (`[A-Za-z0-9_-]{1,128}`) under the host's own root
+(`CODEX_HOME`/`~/.codex`, `KIMI_CODE_HOME`/`~/.kimi-code`), and every
+index-supplied or cached path must realpath-resolve inside that root or the
+read is skipped. Capture additionally requires the installation's frozen
+`tokenUsage` capability — installations consented before 0.6.0 never have
+their transcripts read until reinstalled under the current disclosure. A
+single `install all --claims <kind>=<claim>,…` invocation sweeps the claimed,
+detected hosts with one CONNECT covering the explicitly listed set; each host
+keeps its own installation, capabilities, and status.
+
 Run focused checks from this directory:
 
 ```bash

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Signed Halofy lifecycle installer and runtime for supported agents",
+  "description": "Halofy lifecycle installer and runtime for supported agents; runtime requests are signed with a per-installation Ed25519 key",
   "bin": {
     "agent-connect": "bin/install.mjs",
     "halofy-agent": "bin/halofy-agent.mjs"
@@ -24,7 +24,7 @@
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "check": "node --check src/*.mjs && node --check bin/*.mjs",
+    "check": "node --check src/*.mjs && node --check src/transcript-drivers/*.mjs && node --check bin/*.mjs",
     "prepack": "npm run check && npm test"
   },
   "engines": {

package/src/claude-config.mjs

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { readJson, writePrivateFile } from "./storage.mjs";
+import { readJson, writeHostConfigFile } from "./storage.mjs";
 
 const CLAUDE_HOOKS = Object.freeze({
   SessionStart: { matcher: "startup|resume|clear|compact", timeout: 15 },
@@ -124,12 +124,12 @@ export async function configureClaudeProject({
       replacedClaudeMcpEntries += removeHalofyEntries(project.mcpServers, server.toString());
     }
     if (replacedClaudeMcpEntries > 0) {
-      await writePrivateFile(claudeConfigPath, `${JSON.stringify(claude, null, 2)}\n`);
+      await writeHostConfigFile(claudeConfigPath, `${JSON.stringify(claude, null, 2)}\n`);
     }
   }
 
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
-  await writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   return {
     mcpPath,
     settingsPath,

package/src/claude-hook.mjs

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
-import { normalizeClaudeHookEvent } from "./session.mjs";
+import { normalizeClaudeHookEvent, RECALL_INJECTION_ENABLED, rankedRecallBlocks } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 
 function id(value) {
@@ -42,16 +42,7 @@ function childSession(input) {
 }
 
 function recallText(result, eventName) {
-  const blocks = Array.isArray(result?.blocks) ? result.blocks : Array.isArray(result) ? result : [];
-  const rankedBlocks = blocks
-    .filter((block) => block && typeof block.recallRef === "string" &&
-      typeof block.content === "string" && block.content.trim())
-    .slice(0, 12)
-    .map((block, rank) => ({
-      rank: rank + 1,
-      recallRef: block.recallRef.slice(0, 256),
-      content: block.content.trim(),
-    }));
+  const rankedBlocks = rankedRecallBlocks(result);
   if (rankedBlocks.length === 0) return null;
   return JSON.stringify({
     hookSpecificOutput: {
@@ -95,20 +86,24 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     if (eventName === "SessionStart") {
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
-      const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
-      const recalled = await runtime.recall(
-        session,
-        `${project ? `${project} ` : ""}project policy, conventions, decisions, preferences, and known context`,
-      );
-      const output = recallText(recalled, "SessionStart");
-      if (output) stdout.write(output);
-    } else if (eventName === "UserPromptSubmit") {
-      const prompt = String(hookInput.prompt || hookInput.user_prompt || "").slice(0, 8_000);
-      if (prompt.trim()) {
-        const recalled = await runtime.recall(session, prompt);
-        const output = recallText(recalled, "UserPromptSubmit");
+      if (RECALL_INJECTION_ENABLED) {
+        const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
+        const recalled = await runtime.recall(
+          session,
+          `${project ? `${project} ` : ""}project policy, conventions, decisions, preferences, and known context`,
+        );
+        const output = recallText(recalled, "SessionStart");
         if (output) stdout.write(output);
       }
+    } else if (eventName === "UserPromptSubmit") {
+      if (RECALL_INJECTION_ENABLED) {
+        const prompt = String(hookInput.prompt || hookInput.user_prompt || "").slice(0, 8_000);
+        if (prompt.trim()) {
+          const recalled = await runtime.recall(session, prompt);
+          const output = recallText(recalled, "UserPromptSubmit");
+          if (output) stdout.write(output);
+        }
+      }
     } else if (eventName === "Stop") {
       if (!hookInput.stop_hook_active) {
         await catchUp(runtime, hookInput);

package/src/client-registry.mjs

@@ -58,8 +58,9 @@ export const CLIENT_REGISTRY = Object.freeze({
       subagents: true, compactionCheckpoints: true, contextRecalled: true,
       // 0.5.0: host-reported model token usage, thinking blocks, structured
       // tool outcomes, and content-free session metadata from the native
-      // transcript. Claude Code is the only host whose reviewed adapter
-      // reads these today.
+      // transcript. Since 0.6.0 codex and kimi-cli also report usage and
+      // metadata via their reviewed transcript drivers; thinking blocks and
+      // structured tool outcomes remain Claude Code-only.
       tokenUsage: true, sessionMetadata: true, toolOutcomes: true,
       thinking: true,
     }),
@@ -104,6 +105,9 @@ export const CLIENT_REGISTRY = Object.freeze({
       toolInputs: true, toolOutputs: true, toolFailures: true,
       artifactReferences: true, subagents: true, compactionCheckpoints: true,
       contextRecalled: true,
+      // 0.6.0: host-reported usage and content-free session metadata read
+      // from the session wire by the reviewed kimi transcript driver.
+      tokenUsage: true, sessionMetadata: true,
     }),
   }),
   vscode: Object.freeze({
@@ -131,6 +135,9 @@ export const CLIENT_REGISTRY = Object.freeze({
       subagentStart: true, subagentStop: true, postToolUse: true,
       userMessages: true, toolInputs: true, toolOutputs: true, subagents: true,
       compactionCheckpoints: true, contextRecalled: true,
+      // 0.6.0: host-reported usage and content-free session metadata read
+      // from the native rollout by the reviewed codex transcript driver.
+      tokenUsage: true, sessionMetadata: true,
     }),
   }),
   cline: Object.freeze({

package/src/host-config.mjs

@@ -1,7 +1,8 @@
-import { chmod, readFile } from "node:fs/promises";
+import { chmod, mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+import { readJson, writeHostConfigFile } from "./storage.mjs";
+import { codexHome, kimiHome } from "./host-roots.mjs";
 
 function commandArg(value) {
   const text = String(value);
@@ -92,8 +93,8 @@ export async function configureCursor({
     mcp.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   return { configuredPaths: [hooksPath, mcpPath], hookEvents: Object.keys(CURSOR_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -133,7 +134,7 @@ export async function configureGemini({
     settings.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  await writeHostConfigFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
   return { configuredPaths: [settingsPath], hookEvents: Object.keys(GEMINI_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -172,7 +173,7 @@ export async function configureKimi({
   installationId,
   nodePath = process.execPath,
   runtimePath,
-  kimiRoot = process.env.KIMI_CODE_HOME || join(homedir(), ".kimi-code"),
+  kimiRoot = kimiHome(),
 }) {
   validateInputs({ installationId, runtimePath });
   const configPath = join(kimiRoot, "config.toml");
@@ -197,8 +198,8 @@ export async function configureKimi({
     mcp.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(configPath, replaceKimiManagedHooks(source, hookBlock));
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(configPath, replaceKimiManagedHooks(source, hookBlock));
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   return { configuredPaths: [configPath, mcpPath], hookEvents: Object.keys(KIMI_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -233,8 +234,8 @@ export async function configureVscode({
     mcp.servers,
     managedMcp(nodePath, runtimePath, installationId, { explicitType: true }),
   );
-  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   return { configuredPaths: [hooksPath, mcpPath], hookEvents: Object.keys(VSCODE_HOOKS), replacedLegacyMcpEntries };
 }
 
@@ -292,7 +293,7 @@ export async function configureCodex({
   installationId,
   nodePath = process.execPath,
   runtimePath,
-  codexRoot = process.env.CODEX_HOME || join(homedir(), ".codex"),
+  codexRoot = codexHome(),
 }) {
   validateInputs({ installationId, runtimePath });
   const hooksPath = join(codexRoot, "hooks.json");
@@ -308,11 +309,11 @@ export async function configureCodex({
     `command = ${JSON.stringify(resolve(nodePath))}`,
     `args = ${JSON.stringify([resolve(runtimePath), "mcp", "--connection", installationId])}`,
   ].join("\n");
-  await writePrivateFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
+  await writeHostConfigFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
   const withoutHalomem = removeTomlSection(source, "mcp_servers.halomem");
   const withoutHalofy = removeTomlSection(withoutHalomem.source, "mcp_servers.halofy");
   const withMcp = replaceTomlSection(withoutHalofy.source, "mcp_servers.halofy", section);
-  await writePrivateFile(configPath, enableTomlFeature(withMcp, "hooks"));
+  await writeHostConfigFile(configPath, enableTomlFeature(withMcp, "hooks"));
   return {
     configuredPaths: [hooksPath, configPath],
     hookEvents: Object.keys(CODEX_HOOKS),
@@ -335,12 +336,12 @@ export async function configureCline({
 }) {
   validateInputs({ installationId, runtimePath });
   const hooksRoot = join(clineRoot, "Hooks");
-  await ensurePrivateDirectory(hooksRoot);
+  await mkdir(hooksRoot, { recursive: true });
   const configuredPaths = [];
   for (const [hostEvent, runtimeEvent] of Object.entries(CLINE_HOOKS)) {
     const path = join(hooksRoot, hostEvent);
     const command = managedCommand(nodePath, runtimePath, runtimeEvent, installationId);
-    await writePrivateFile(path, `#!/usr/bin/env sh\nexec ${command}\n`);
+    await writeHostConfigFile(path, `#!/usr/bin/env sh\nexec ${command}\n`);
     if (process.platform !== "win32") await chmod(path, 0o700);
     configuredPaths.push(path);
   }
@@ -351,7 +352,7 @@ export async function configureCline({
     mcp.mcpServers,
     managedMcp(nodePath, runtimePath, installationId),
   );
-  await writePrivateFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  await writeHostConfigFile(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
   configuredPaths.push(mcpPath);
   return { configuredPaths, hookEvents: Object.keys(CLINE_HOOKS), replacedLegacyMcpEntries };
 }

package/src/host-hook.mjs

@@ -1,9 +1,15 @@
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
-import { normalizeClaudeHookEvent, normalizeHostMessageEvent } from "./session.mjs";
+import {
+  normalizeClaudeHookEvent,
+  normalizeHostMessageEvent,
+  RECALL_INJECTION_ENABLED,
+  rankedRecallBlocks,
+} from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { readHookInput } from "./claude-hook.mjs";
+import { transcriptDriverFor } from "./transcript-drivers/index.mjs";
 
 const USER_EVENTS = new Set(["UserPromptSubmit", "beforeSubmitPrompt", "BeforeAgent", "pre_llm_call"]);
 const ASSISTANT_EVENTS = new Set(["afterAgentResponse", "AfterAgent", "post_llm_call", "transform_llm_output"]);
@@ -62,18 +68,8 @@ function toolOutput(input) {
     input.extra?.result ?? input.extra?.error_message;
 }
 
-function recallBlocks(result) {
-  const blocks = Array.isArray(result?.blocks) ? result.blocks : Array.isArray(result) ? result : [];
-  return blocks.filter((block) => block && typeof block.recallRef === "string" &&
-    typeof block.content === "string" && block.content.trim()).slice(0, 12).map((block, rank) => ({
-      rank: rank + 1,
-      recallRef: block.recallRef.slice(0, 256),
-      content: block.content.trim(),
-    }));
-}
-
 function recallOutput(clientKind, eventName, result) {
-  const rankedBlocks = recallBlocks(result);
+  const rankedBlocks = rankedRecallBlocks(result);
   if (rankedBlocks.length === 0) return null;
   const additionalContext = `<<<HALOFY_CONTEXT_BLOCKS_V1>>>\n${JSON.stringify({ rankedBlocks })}\n<<<END_HALOFY_CONTEXT_BLOCKS_V1>>>`;
   if (clientKind === "cursor") {
@@ -121,6 +117,29 @@ async function enqueueTool(runtime, session, eventName, input) {
   ]);
 }
 
+/**
+ * Best-effort transcript catch-up for hosts with a reviewed driver. Consent
+ * is double-gated: the driver must exist for this client kind AND the
+ * install-time frozen capability snapshot must declare tokenUsage — an older
+ * installation never has its transcript read, even under an upgraded runtime.
+ * Failures are swallowed: capture evidence must never degrade the hook path.
+ */
+async function catchUpHost(runtime, connection, session, sessionFacts = {}) {
+  try {
+    if (connection.capabilities?.tokenUsage !== true) return;
+    const driver = transcriptDriverFor(connection.clientKind);
+    if (driver === null) return;
+    const located = await driver.locate(session, {});
+    if (located === null) return;
+    await runtime.captureHostTranscript(session, driver, located.path, {
+      ...(located.sessionFacts ?? {}),
+      ...sessionFacts,
+    });
+  } catch {
+    // Transcript evidence is additive; the hook result stands without it.
+  }
+}
+
 /** Runs one reviewed host hook without blocking the host when Halofy browns out. */
 export async function runHostLifecycleHook(connection, eventName, {
   input,
@@ -139,15 +158,22 @@ export async function runHostLifecycleHook(connection, eventName, {
     if (START_EVENTS.has(eventName)) {
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
-      const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
-      const recalled = await runtime.recall(session,
-        `${project ? `${project} ` : ""}project policy, conventions, decisions, preferences, and known context`);
-      const output = recallOutput(connection.clientKind, eventName, recalled);
-      if (output) stdout.write(output);
+      if (RECALL_INJECTION_ENABLED) {
+        const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
+        const recalled = await runtime.recall(session,
+          `${project ? `${project} ` : ""}project policy, conventions, decisions, preferences, and known context`);
+        const output = recallOutput(connection.clientKind, eventName, recalled);
+        if (output) stdout.write(output);
+      }
     } else if (USER_EVENTS.has(eventName)) {
+      // Prompt capture is independent of recall: hosts without a reviewed
+      // transcript driver rely on this enqueue to reach the archive, and
+      // hook-sourced events stay authoritative for messages even where a
+      // driver adds usage/metadata evidence.
       const prompt = promptText(hookInput);
       await enqueueMessage(runtime, connection, session, "user", prompt, eventName, hookInput);
-      if (connection.clientKind !== "cursor" && typeof prompt === "string" && prompt.trim()) {
+      if (RECALL_INJECTION_ENABLED && connection.clientKind !== "cursor" &&
+          typeof prompt === "string" && prompt.trim()) {
         const recalled = await runtime.recall(session, prompt.slice(0, 8_000));
         const output = recallOutput(connection.clientKind, eventName, recalled);
         if (output) stdout.write(output);
@@ -157,6 +183,7 @@ export async function runHostLifecycleHook(connection, eventName, {
       await runtime.commitIfThreshold(session);
     } else if (TOOL_EVENTS.has(eventName)) {
       await enqueueTool(runtime, session, eventName, hookInput);
+      await catchUpHost(runtime, connection, session);
     } else if (COMPACT_EVENTS.has(eventName)) {
       await runtime.enqueueSequencedEvents(session, ({ sessionHash, nextSequence }) => [
         normalizeClaudeHookEvent("compaction", {
@@ -164,14 +191,20 @@ export async function runHostLifecycleHook(connection, eventName, {
           event_id: eventEvidenceId(eventName, hookInput),
         }, { sessionHash, sequence: nextSequence }),
       ]);
+      await catchUpHost(runtime, connection, session);
       await runtime.commit(session, "pre_compaction");
     } else if (SUBAGENT_START_EVENTS.has(eventName)) {
       await runtime.resolveSession(childSession(hookInput, session), session);
     } else if (SUBAGENT_STOP_EVENTS.has(eventName)) {
+      // Subagent transcript files are a documented per-host limitation; the
+      // parent session still catches up so its usage stays current.
+      await within(10_000, () => catchUpHost(runtime, connection, session));
       await within(10_000, () => runtime.close(childSession(hookInput, session), "session_end"));
     } else if (END_EVENTS.has(eventName)) {
+      await within(10_000, () => catchUpHost(runtime, connection, session, { closeReason: "session_end" }));
       await within(15_000, () => runtime.close(session));
     } else if (STOP_EVENTS.has(eventName)) {
+      await within(10_000, () => catchUpHost(runtime, connection, session));
       if (connection.clientKind === "vscode" || connection.clientKind === "cline") {
         await within(15_000, () => runtime.close(session));
       } else {

package/src/host-roots.mjs

@@ -0,0 +1,13 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Single authority for each host's on-disk root. host-config.mjs (hook/MCP
+// installation) and transcript-drivers/ (session-file location) must agree on
+// these paths or capture silently reads the wrong tree.
+export function codexHome(env = process.env) {
+  return env.CODEX_HOME || join(homedir(), ".codex");
+}
+
+export function kimiHome(env = process.env) {
+  return env.KIMI_CODE_HOME || join(homedir(), ".kimi-code");
+}

package/src/install.mjs

@@ -10,6 +10,105 @@ import { CLIENT_KINDS, CLIENT_REGISTRY, lifecycleClient } from "./client-registr
 
 export const CLAUDE_CAPABILITIES = CLIENT_REGISTRY["claude-code"].capabilities;
 
+/** HTTPS-or-loopback validation shared by every request that carries the claim. */
+export function normalizeLifecycleServerUrl(serverUrl) {
+  const normalizedServer = new URL(serverUrl);
+  if (normalizedServer.protocol !== "https:" && normalizedServer.hostname !== "localhost" &&
+      normalizedServer.hostname !== "127.0.0.1" && normalizedServer.hostname !== "[::1]") {
+    throw new Error("installation claims require HTTPS (localhost is allowed for development)");
+  }
+  normalizedServer.pathname = normalizedServer.pathname.replace(/\/+$/, "");
+  return normalizedServer.toString().replace(/\/$/, "");
+}
+
+/**
+ * Best-effort pre-consumption disclosure: which organization this claim binds
+ * to, shown before the CONNECT confirmation. An older server without the
+ * endpoint, or any failure, yields null — the installer then labels the
+ * organization unverified instead of failing. The claim is not consumed.
+ */
+export async function fetchClaimDisclosure({
+  serverUrl,
+  claim,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 5_000,
+}) {
+  try {
+    const normalizedServerUrl = normalizeLifecycleServerUrl(serverUrl);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(`${normalizedServerUrl}/v1/agent-installations/claim-info`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ claim }),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) return null;
+    const body = await response.json();
+    // Server-supplied text is printed to a terminal: strip control characters
+    // (including ANSI escape introducers) and bound the length.
+    const organization = typeof body?.organization === "string"
+      ? body.organization.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().slice(0, 100)
+      : "";
+    return organization ? { organization } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Batch pre-consumption disclosure for the install-all sweep. One POST — and
+ * therefore one throttle token — covers every claim in the command, so a full
+ * sweep (1 disclosure + N consumes) fits the per-address budget. Entries come
+ * back positionally; an unusable claim is null. Any failure yields null for
+ * the whole batch (older server), never an error.
+ */
+export async function fetchClaimDisclosures({
+  serverUrl,
+  claims,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 5_000,
+}) {
+  try {
+    const normalizedServerUrl = normalizeLifecycleServerUrl(serverUrl);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(`${normalizedServerUrl}/v1/agent-installations/claim-info`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ claims }),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) return null;
+    const body = await response.json();
+    if (!Array.isArray(body?.disclosures)) return null;
+    return claims.map((_, index) => {
+      const entry = body.disclosures[index];
+      if (entry === null || typeof entry !== "object") return null;
+      // Server-supplied text is printed to a terminal: strip control
+      // characters (including ANSI escape introducers) and bound the length.
+      const organization = typeof entry.organization === "string"
+        ? entry.organization.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().slice(0, 100)
+        : "";
+      const clientKind = typeof entry.clientKind === "string" &&
+        /^[a-z0-9][a-z0-9-]{0,63}$/.test(entry.clientKind) ? entry.clientKind : null;
+      return organization ? { organization, clientKind } : null;
+    });
+  } catch {
+    return null;
+  }
+}
+
 export async function consumeInstallationClaim({
   serverUrl,
   claim,
@@ -51,12 +150,7 @@ export async function installLocalConnection({
 }) {
   if (!CLIENT_KINDS.includes(clientKind)) throw new Error("the selected lifecycle adapter is not packaged");
   const client = lifecycleClient(clientKind);
-  const normalizedServer = new URL(serverUrl);
-  if (normalizedServer.protocol !== "https:" && normalizedServer.hostname !== "localhost" && normalizedServer.hostname !== "127.0.0.1") {
-    throw new Error("installation claims require HTTPS (localhost is allowed for development)");
-  }
-  normalizedServer.pathname = normalizedServer.pathname.replace(/\/+$/, "");
-  const normalizedServerUrl = normalizedServer.toString().replace(/\/$/, "");
+  const normalizedServerUrl = normalizeLifecycleServerUrl(serverUrl);
   const store = new ConnectionStore(root);
   const pendingPath = join(root, `pending-${clientKind}.json`);
   const priorPending = await readJson(pendingPath);