@halofy/agent-connect 0.5.1 → 0.6.0

package/README.md

@@ -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.5.1 install <client-kind> \
+npx --yes @halofy/agent-connect@0.6.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -81,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,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "description": "Halofy lifecycle installer and runtime for supported agents; runtime requests are signed with a per-installation Ed25519 key",
   "bin": {
@@ -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/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

@@ -2,6 +2,7 @@ import { chmod, mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { readJson, writeHostConfigFile } from "./storage.mjs";
+import { codexHome, kimiHome } from "./host-roots.mjs";
 
 function commandArg(value) {
   const text = String(value);
@@ -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");
@@ -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");

package/src/host-hook.mjs

@@ -9,6 +9,7 @@ import {
 } 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"]);
@@ -116,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,
@@ -142,8 +166,10 @@ export async function runHostLifecycleHook(connection, eventName, {
         if (output) stdout.write(output);
       }
     } else if (USER_EVENTS.has(eventName)) {
-      // Prompt capture is independent of recall: non-Claude hosts have no
-      // transcript, so this enqueue is how user messages reach the archive.
+      // 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 (RECALL_INJECTION_ENABLED && connection.clientKind !== "cursor" &&
@@ -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

@@ -61,6 +61,54 @@ export async function fetchClaimDisclosure({
   }
 }
 
+/**
+ * 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,

package/src/installer-cli.mjs

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import {
   fetchClaimDisclosure,
+  fetchClaimDisclosures,
   heartbeatInstalledConnection,
   installLocalConnection,
   installRuntimeBundle,
@@ -16,9 +17,50 @@ import { CLIENT_KINDS, lifecycleClient } from "./client-registry.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { DISCLOSURE_VERSION, INSTALLER_VERSION } from "./version.mjs";
 
+const CLAIM_PATTERN = /^hsc_[A-Za-z0-9_-]{43}$/;
+
+function parseAllInstallerArgs(argv) {
+  const values = new Map();
+  for (let index = 2; index < argv.length; index += 1) {
+    const name = argv[index];
+    if (!["--server", "--claims", "--claude-project"].includes(name) || values.has(name)) {
+      throw new Error("unsupported or duplicate installer argument");
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`${name} requires a value`);
+    values.set(name, value);
+    index += 1;
+  }
+  const serverUrl = values.get("--server");
+  const rawClaims = values.get("--claims");
+  const usage = "Usage: agent-connect install all --server <https-url> --claims <client>=<one-use-claim>[,...]";
+  if (!serverUrl || !rawClaims) throw new Error(usage);
+  const pairs = rawClaims.split(",");
+  if (pairs.length < 1 || pairs.length > CLIENT_KINDS.length) throw new Error(usage);
+  const selections = [];
+  const kinds = new Set();
+  for (const pair of pairs) {
+    const separator = pair.indexOf("=");
+    const clientKind = separator === -1 ? "" : pair.slice(0, separator);
+    const claim = separator === -1 ? "" : pair.slice(separator + 1);
+    if (!CLIENT_KINDS.includes(clientKind) || !CLAIM_PATTERN.test(claim) || kinds.has(clientKind)) {
+      throw new Error(usage);
+    }
+    kinds.add(clientKind);
+    selections.push({ clientKind, claim });
+  }
+  return {
+    mode: "all",
+    selections,
+    serverUrl,
+    projectRoot: resolve(values.get("--claude-project") || process.cwd()),
+  };
+}
+
 export function parseInstallerArgs(argv) {
   const command = argv[0];
   const clientKind = argv[1];
+  if (command === "install" && clientKind === "all") return parseAllInstallerArgs(argv);
   const values = new Map();
   for (let index = 2; index < argv.length; index += 1) {
     const name = argv[index];
@@ -37,6 +79,7 @@ export function parseInstallerArgs(argv) {
     throw new Error("Usage: agent-connect install <supported-client> --server <https-url> --claim <one-use-claim>");
   }
   return {
+    mode: "single",
     clientKind,
     serverUrl,
     claim,
@@ -82,8 +125,20 @@ export function detectClient(clientKind) {
   return String(result.stdout || result.stderr || "").trim().slice(0, 128) || "detected";
 }
 
-export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersion, organization = null }) {
-  const client = lifecycleClient(clientKind);
+/** Non-throwing detection probe for the install-all sweep. */
+export async function probeClient(clientKind, {
+  detectClaude = detectClaudeCode,
+  detectHost = detectClient,
+} = {}) {
+  try {
+    const version = clientKind === "claude-code" ? await detectClaude() : await detectHost(clientKind);
+    return { detected: true, version };
+  } catch (error) {
+    return { detected: false, reason: error?.message || "not detected" };
+  }
+}
+
+function captureCategories(client) {
   const observedCategories = [
     ["user messages", client.capabilities.userMessages],
     ["assistant messages", client.capabilities.assistantMessages],
@@ -101,8 +156,15 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
     ["tool outcomes (durations, failure flags, byte sizes; file paths only as salted hashes)", client.capabilities.toolOutcomes],
     ["host and session metadata (app version, permission mode, effort, session title; directory paths hashed unless your organization enables full device context)", client.capabilities.sessionMetadata],
   ];
-  const supported = observedCategories.filter(([, value]) => value === true).map(([name]) => name);
-  const unsupported = observedCategories.filter(([, value]) => value !== true).map(([name]) => name);
+  return {
+    supported: observedCategories.filter(([, value]) => value === true).map(([name]) => name),
+    unsupported: observedCategories.filter(([, value]) => value !== true).map(([name]) => name),
+  };
+}
+
+export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersion, organization = null }) {
+  const client = lifecycleClient(clientKind);
+  const { supported, unsupported } = captureCategories(client);
   return [
     `Halofy ${client.label} lifecycle connection`,
     `Installer: @halofy/agent-connect@${INSTALLER_VERSION}`,
@@ -132,6 +194,55 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
   ].join("\n");
 }
 
+/**
+ * One disclosure for the whole sweep: shared header, one capture-category
+ * section per detected host, and an explicit statement of which minted claims
+ * will expire unused. One CONNECT then covers exactly the listed hosts —
+ * explicit per-host consent, never a silent fan-out.
+ */
+export function allDisclosureText({ serverUrl, projectRoot, organization = null, hosts, unusedKinds = [] }) {
+  const lines = [
+    "Halofy all-agents lifecycle connection",
+    `Installer: @halofy/agent-connect@${INSTALLER_VERSION}`,
+    `Server: ${new URL(serverUrl).origin}`,
+    // The server named by --server identifies the organization this command
+    // binds to, so a spoofed command is recognizable before CONNECT.
+    `Organization: ${organization || "unverified (the server did not identify this command's organization)"}`,
+    `Project: ${projectRoot}`,
+    `Hosts to be connected: ${hosts.map((host) => lifecycleClient(host.clientKind).label).join(", ")}`,
+    "",
+    "Each host gets its own installation binding, capability record, and connection status:",
+  ];
+  for (const host of hosts) {
+    const client = lifecycleClient(host.clientKind);
+    const { supported, unsupported } = captureCategories(client);
+    lines.push(
+      "",
+      `--- ${client.label} (${host.clientVersion}) ---`,
+      `Supported capture categories: ${supported.length > 0 ? supported.join(", ") : "none"}.`,
+      `Unsupported capture categories: ${unsupported.length > 0 ? unsupported.join(", ") : "none"}.`,
+      client.coverage === "complete"
+        ? "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.`,
+    );
+  }
+  if (unusedKinds.length > 0) {
+    lines.push(
+      "",
+      `Claims for ${unusedKinds.map((kind) => lifecycleClient(kind).label).join(", ")} were issued ` +
+      "but those hosts were not detected here; they expire unused within 10 minutes.",
+    );
+  }
+  lines.push(
+    "",
+    "Authorized organization managers may review retained conversations and summaries.",
+    "This does not scan historical files, other applications, clipboard, keystrokes, or other agents.",
+    "Disconnecting stops future capture but does not erase retained data.",
+    `Disclosure: ${DISCLOSURE_VERSION}`,
+  );
+  return lines.join("\n");
+}
+
 export async function confirmDisclosure({ input = process.stdin, output = process.stdout } = {}) {
   if (!input.isTTY || !output.isTTY) throw new Error("interactive terminal confirmation is required");
   const prompt = createInterface({ input, output });
@@ -144,6 +255,136 @@ export async function confirmDisclosure({ input = process.stdin, output = proces
   return true;
 }
 
+async function configureHost(clientKind, common, { claudeConfigPath } = {}) {
+  if (clientKind === "claude-code") {
+    return configureClaudeProject({ ...common, ...(claudeConfigPath ? { claudeConfigPath } : {}) });
+  }
+  if (clientKind === "cursor") return configureCursor(common);
+  if (clientKind === "gemini-cli") return configureGemini(common);
+  if (clientKind === "kimi-cli") return configureKimi(common);
+  if (clientKind === "vscode") return configureVscode(common);
+  if (clientKind === "codex") return configureCodex(common);
+  if (clientKind === "cline") return configureCline(common);
+  throw new Error("the selected adapter is not packaged yet");
+}
+
+async function runAllInstaller(input, {
+  root,
+  output,
+  detectClaude,
+  detectHost,
+  confirm,
+  fetchImpl,
+  sourceRoot,
+  claudeConfigPath,
+}) {
+  const probes = [];
+  for (const selection of input.selections) {
+    probes.push({ ...selection, probe: await probeClient(selection.clientKind, { detectClaude, detectHost }) });
+  }
+  const detected = probes.filter((entry) => entry.probe.detected);
+  const skipped = probes.filter((entry) => !entry.probe.detected)
+    .map((entry) => ({ clientKind: entry.clientKind, reason: "not_detected" }));
+  if (detected.length === 0) {
+    throw new Error("no claimed agents were detected on this machine: " +
+      probes.map((entry) => `${lifecycleClient(entry.clientKind).label} (${entry.probe.reason})`).join("; "));
+  }
+
+  // One batch disclosure call spends one throttle token for the whole sweep.
+  const disclosures = await fetchClaimDisclosures({
+    serverUrl: input.serverUrl,
+    claims: input.selections.map((selection) => selection.claim),
+    fetchImpl,
+  });
+  let organization = null;
+  if (disclosures !== null) {
+    const organizations = new Set();
+    for (let index = 0; index < input.selections.length; index += 1) {
+      const disclosure = disclosures[index];
+      if (!disclosure) continue;
+      // A claim minted for one client kind pasted behind another label is a
+      // spoofed or reassembled command — refuse before any consent prompt.
+      if (disclosure.clientKind !== null && disclosure.clientKind !== input.selections[index].clientKind) {
+        throw new Error(`the claim labeled ${input.selections[index].clientKind} was issued for ` +
+          `${disclosure.clientKind}; refuse this command and generate a fresh one`);
+      }
+      if (disclosure.organization) organizations.add(disclosure.organization);
+    }
+    if (organizations.size > 1) {
+      throw new Error("the claims in this command belong to different organizations; " +
+        "refuse this command and generate a fresh one");
+    }
+    organization = organizations.size === 1 ? [...organizations][0] : null;
+  }
+
+  output.write(`${allDisclosureText({
+    serverUrl: input.serverUrl,
+    projectRoot: input.projectRoot,
+    organization,
+    hosts: detected.map((entry) => ({ clientKind: entry.clientKind, clientVersion: entry.probe.version })),
+    unusedKinds: skipped.map((entry) => entry.clientKind),
+  })}\n`);
+  await confirm();
+
+  // The reviewed runtime bundle installs exactly once for the whole sweep.
+  const bundle = await installRuntimeBundle({ root, ...(sourceRoot ? { sourceRoot } : {}) });
+  const results = [];
+  for (const host of detected) {
+    try {
+      const installed = await installLocalConnection({
+        serverUrl: input.serverUrl,
+        claim: host.claim,
+        clientKind: host.clientKind,
+        root,
+        fetchImpl,
+        sendHeartbeat: false,
+      });
+      const configured = await configureHost(host.clientKind, {
+        projectRoot: input.projectRoot,
+        installationId: installed.installationId,
+        serverUrl: input.serverUrl,
+        runtimePath: bundle.runtimePath,
+      }, { claudeConfigPath });
+      let heartbeat = false;
+      try {
+        heartbeat = await heartbeatInstalledConnection({
+          installationId: installed.installationId, root, fetchImpl,
+        });
+      } catch {
+        heartbeat = false;
+      }
+      results.push({
+        clientKind: host.clientKind,
+        status: heartbeat ? "configured_heartbeat_verified" : "configured_heartbeat_unavailable",
+        installationId: installed.installationId,
+        proofStorage: installed.proofStorage,
+        configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
+        replacedLegacyMcpEntries: configured.replacedLegacyMcpEntries || 0,
+        nextStep: `Restart ${lifecycleClient(host.clientKind).label}, then check the connection in Halofy.`,
+      });
+    } catch (error) {
+      // One host failing must not abort the others; the failure is reported,
+      // never hidden.
+      skipped.push({
+        clientKind: host.clientKind,
+        reason: `failed:${(error?.message || "install_error").slice(0, 200)}`,
+      });
+    }
+  }
+  if (results.length === 0) {
+    throw new Error("every detected agent failed to install: " +
+      skipped.map((entry) => `${entry.clientKind} (${entry.reason})`).join("; "));
+  }
+  return {
+    status: skipped.some((entry) => entry.reason.startsWith("failed:"))
+      ? "completed_with_failures" : "completed",
+    installerVersion: INSTALLER_VERSION,
+    publishedPackage: true,
+    results,
+    skipped,
+  };
+}
+
 export async function runInstaller(argv, {
   root = defaultRuntimeDirectory(),
   output = process.stdout,
@@ -155,6 +396,11 @@ export async function runInstaller(argv, {
   claudeConfigPath,
 } = {}) {
   const input = parseInstallerArgs(argv);
+  if (input.mode === "all") {
+    return runAllInstaller(input, {
+      root, output, detectClaude, detectHost, confirm, fetchImpl, sourceRoot, claudeConfigPath,
+    });
+  }
   const clientVersion = input.clientKind === "claude-code" ? await detectClaude() : await detectHost(input.clientKind);
   const claimDisclosure = await fetchClaimDisclosure({
     serverUrl: input.serverUrl,
@@ -183,21 +429,7 @@ export async function runInstaller(argv, {
     serverUrl: input.serverUrl,
     runtimePath: bundle.runtimePath,
   };
-  const configured = input.clientKind === "claude-code"
-    ? await configureClaudeProject({ ...common, ...(claudeConfigPath ? { claudeConfigPath } : {}) })
-    : input.clientKind === "cursor"
-      ? await configureCursor(common)
-      : input.clientKind === "gemini-cli"
-        ? await configureGemini(common)
-        : input.clientKind === "kimi-cli"
-          ? await configureKimi(common)
-          : input.clientKind === "vscode"
-            ? await configureVscode(common)
-            : input.clientKind === "codex"
-              ? await configureCodex(common)
-              : input.clientKind === "cline"
-                ? await configureCline(common)
-                : (() => { throw new Error("the selected adapter is not packaged yet"); })();
+  const configured = await configureHost(input.clientKind, common, { claudeConfigPath });
   let heartbeat = false;
   try {
     heartbeat = await heartbeatInstalledConnection({

package/src/runtime.mjs

@@ -2,12 +2,10 @@ import { createHash, randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { BoundedEncryptedQueue } from "./queue.mjs";
 import {
-  buildClaudeMetadataPayload,
-  claudeMetadataEvent,
   CursorStore,
   deriveSessionHash,
-  readClaudeTranscriptSuffix,
 } from "./session.mjs";
+import { claudeTranscriptDriver } from "./transcript-drivers/claude.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { readJson, withFileLock, writePrivateFile } from "./storage.mjs";
 import { RUNTIME_VERSION } from "./version.mjs";
@@ -113,26 +111,30 @@ export class LifecycleRuntime {
   }
 
   async captureClaudeTranscript(hostSessionId, transcriptPath, sessionFacts = {}) {
+    return this.captureHostTranscript(hostSessionId, claudeTranscriptDriver, transcriptPath, sessionFacts);
+  }
+
+  async captureHostTranscript(hostSessionId, driver, transcriptPath, sessionFacts = {}) {
     const sessionHash = this.sessionHash(hostSessionId);
     const policy = await this.capturePolicy();
     const queued = await withFileLock(this.operationLockPath, async () => {
       const cursor = await this.cursors.get(sessionHash);
-      const suffix = await readClaudeTranscriptSuffix(transcriptPath, cursor, sessionHash);
+      const suffix = await driver.readSuffix(transcriptPath, cursor, sessionHash);
       const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
       const unseenEvents = suffix.events.filter((event) => !recentEventKeys.has(event.eventKey));
       // 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 = buildClaudeMetadataPayload(
+      const metadataPayload = driver.buildMetadataPayload(
         { ...suffix.metadata, ...sessionFacts },
         { installationId: this.connection.installationId, deviceContext: policy.deviceContext },
       );
       if (Object.keys(metadataPayload).length > 0) {
-        const metadataEvent = claudeMetadataEvent(metadataPayload);
+        const metadataEvent = driver.metadataEvent(metadataPayload);
         if (!recentEventKeys.has(metadataEvent.eventKey)) unseenEvents.push(metadataEvent);
       }
       const usageGaps = unseenEvents.filter((event) =>
-        event.type === "usage" && event.eventKey.startsWith("claude:usage-gap:")).length;
+        event.type === "usage" && event.eventKey.startsWith(driver.usageGapPrefix)).length;
       const result = unseenEvents.length === 0
         ? { queued: 0 }
         : await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
@@ -144,8 +146,11 @@ export class LifecycleRuntime {
       // normalized event is already durable in the encrypted queue. Advancing
       // this byte cursor prevents unbounded reparsing without advancing the
       // separately acknowledged event sequence.
-      if (suffix.observedEndOffset > cursor.byteOffset) {
-        await this.cursors.update(sessionHash, { byteOffset: suffix.observedEndOffset });
+      const patch = {};
+      if (suffix.observedEndOffset > cursor.byteOffset) patch.byteOffset = suffix.observedEndOffset;
+      if (suffix.hostState !== undefined) patch.hostState = suffix.hostState;
+      if (Object.keys(patch).length > 0) {
+        await this.cursors.update(sessionHash, patch);
       }
       await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
       if (usageGaps > 0) await this.cursors.bumpUsageGaps(usageGaps);

package/src/session.mjs

@@ -86,7 +86,7 @@ function boundedCompletePayload(payload, { role, body, format = "json", extra =
   });
 }
 
-function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset, part }) {
+export function normalizedEvent({ eventKey, type, occurredAt, payload, sourceEndOffset, part }) {
   const {
     role,
     contentFormat = "json",
@@ -300,15 +300,15 @@ export function stripInjectedContext(value) {
   return String(value);
 }
 
-function usageInt(value) {
+export function usageInt(value) {
   return Number.isSafeInteger(value) && value >= 0 && value < 2 ** 31 ? value : null;
 }
 
-function usageLabel(value) {
+export function usageLabel(value) {
   return typeof value === "string" && /^[\x20-\x7e]{1,128}$/.test(value) ? value : null;
 }
 
-const USAGE_MODEL_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+export const USAGE_MODEL_PATTERN = /^[A-Za-z0-9._:/-]{1,128}$/;
 
 /**
  * One host-reported usage record per assistant message (PRD §8.1). Claude
@@ -769,15 +769,19 @@ export function buildClaudeMetadataPayload(metadata, { installationId, deviceCon
   return payload;
 }
 
-export function claudeMetadataEvent(payload) {
+export function hostMetadataEvent(namespace, payload) {
   return normalizedEvent({
-    eventKey: `claude:metadata:${digest(stableJson(payload))}`,
+    eventKey: `${namespace}:metadata:${digest(stableJson(payload))}`,
     type: "metadata",
     occurredAt: new Date().toISOString(),
     payload: { contentFormat: "json", captureStatus: "complete", ...payload },
   });
 }
 
+export function claudeMetadataEvent(payload) {
+  return hostMetadataEvent("claude", payload);
+}
+
 export class CursorStore {
   constructor(root) {
     this.path = join(root, "cursors.json");

package/src/transcript-drivers/claude.mjs

@@ -0,0 +1,33 @@
+import {
+  buildClaudeMetadataPayload,
+  claudeMetadataEvent,
+  readClaudeTranscriptSuffix,
+} from "../session.mjs";
+
+/**
+ * Thin delegation over the reviewed Claude Code adapter. The claude path is
+ * frozen — its eventKeys are pinned by the golden fixture test and must stay
+ * byte-identical for server-side dedupe history. Claude Code hooks pass the
+ * transcript path directly, so this driver has no locate step.
+ */
+export const claudeTranscriptDriver = {
+  clientKind: "claude-code",
+  eventKeyNamespace: "claude",
+  usageGapPrefix: "claude:usage-gap:",
+
+  async locate() {
+    return null;
+  },
+
+  readSuffix(path, cursor, sessionHash) {
+    return readClaudeTranscriptSuffix(path, cursor, sessionHash);
+  },
+
+  buildMetadataPayload(metadata, context) {
+    return buildClaudeMetadataPayload(metadata, context);
+  },
+
+  metadataEvent(payload) {
+    return claudeMetadataEvent(payload);
+  },
+};

package/src/transcript-drivers/codex.mjs

@@ -0,0 +1,188 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  buildClaudeMetadataPayload,
+  hostMetadataEvent,
+  normalizedEvent,
+  usageInt,
+  USAGE_MODEL_PATTERN,
+} from "../session.mjs";
+import { codexHome } from "../host-roots.mjs";
+import {
+  boundedHostSessionId,
+  boundedHostState,
+  boundedMetadataText,
+  completeJsonlLines,
+  containedPath,
+  drainedEndOffset,
+  MAX_DRIVER_SUFFIX_BYTES,
+  readSuffixWindow,
+} from "./shared.mjs";
+
+const NAMESPACE = "codex";
+const PROVIDER_PATTERN = /^[a-z0-9-]{1,64}$/;
+
+/**
+ * Codex rollouts live at
+ * `<codexHome>/sessions/YYYY/MM/DD/rollout-<ts>-<session-id>.jsonl` — the
+ * session id is the filename suffix. The hook payload is never trusted for a
+ * path; only the validated session id is interpolated, and every result is
+ * containment-checked under the codex root.
+ */
+async function locateRollout(root, sessionId) {
+  const sessionsRoot = join(root, "sessions");
+  let names;
+  try {
+    names = await readdir(sessionsRoot, { recursive: true });
+  } catch {
+    return null;
+  }
+  const suffix = `-${sessionId}.jsonl`;
+  const matches = names.filter((name) => {
+    const base = String(name).split(/[\\/]/).pop();
+    return base.startsWith("rollout-") && base.endsWith(suffix);
+  }).sort();
+  if (matches.length === 0) return null;
+  // Timestamped names sort chronologically; take the newest.
+  return containedPath(sessionsRoot, matches[matches.length - 1]);
+}
+
+function usageEventFromTokenCount(info, { model, provider, byteOffset, endOffset, occurredAt }) {
+  const usage = info?.last_token_usage;
+  const input = usageInt(usage?.input_tokens);
+  const output = usageInt(usage?.output_tokens);
+  if (usage === null || typeof usage !== "object" || (input === null && output === null)) {
+    return normalizedEvent({
+      eventKey: `${NAMESPACE}:usage-gap:${byteOffset}`,
+      type: "usage",
+      occurredAt,
+      payload: {
+        role: "assistant", contentFormat: "json", captureStatus: "complete",
+        gap: true, reason: "usage_unavailable",
+      },
+      sourceEndOffset: endOffset,
+    });
+  }
+  if (model === null) {
+    return normalizedEvent({
+      eventKey: `${NAMESPACE}:usage-gap:${byteOffset}`,
+      type: "usage",
+      occurredAt,
+      payload: {
+        role: "assistant", contentFormat: "json", captureStatus: "complete",
+        gap: true, reason: "model_unknown",
+      },
+      sourceEndOffset: endOffset,
+    });
+  }
+  const cached = usageInt(usage.cached_input_tokens) ?? 0;
+  const cacheWrite = usageInt(usage.cache_write_input_tokens) ?? 0;
+  // Verified against real rollouts: input_tokens is inclusive of BOTH the
+  // cached-read and cache-write tokens (total_tokens = input + output). The
+  // server prices input, cache-read, and cache-write as disjoint buckets, so
+  // the uncached-and-unwritten remainder is what belongs in inputTokens;
+  // clamp for malformed hosts.
+  const inputTokens = input === null ? null : Math.max(0, input - cached - cacheWrite);
+  return normalizedEvent({
+    eventKey: `${NAMESPACE}:usage:${byteOffset}`,
+    type: "usage",
+    occurredAt,
+    payload: {
+      role: "assistant",
+      contentFormat: "json",
+      captureStatus: "complete",
+      provider,
+      model,
+      providerRequestId: null,
+      messageId: null,
+      stopReason: null,
+      serviceTier: null,
+      effort: null,
+      sidechain: false,
+      latencyMs: null,
+      inputTokens,
+      outputTokens: output,
+      cacheReadTokens: usageInt(usage.cached_input_tokens),
+      cacheWriteTokens: usageInt(usage.cache_write_input_tokens),
+      cacheWrite1hTokens: null,
+      cacheWrite5mTokens: null,
+      reasoningTokens: usageInt(usage.reasoning_output_tokens),
+    },
+    sourceEndOffset: endOffset,
+  });
+}
+
+export const codexTranscriptDriver = {
+  clientKind: "codex",
+  eventKeyNamespace: NAMESPACE,
+  usageGapPrefix: `${NAMESPACE}:usage-gap:`,
+
+  async locate(hostSessionId, { env = process.env } = {}) {
+    const sessionId = boundedHostSessionId(hostSessionId);
+    if (sessionId === null) return null;
+    const path = await locateRollout(codexHome(env), sessionId);
+    return path === null ? null : { path };
+  },
+
+  async readSuffix(path, cursor, _sessionHash) {
+    const { buffer, start } = await readSuffixWindow(path, cursor?.byteOffset ?? 0);
+    const priorState = cursor?.hostState !== null && typeof cursor?.hostState === "object"
+      ? cursor.hostState : {};
+    let model = typeof priorState.model === "string" && USAGE_MODEL_PATTERN.test(priorState.model)
+      ? priorState.model : null;
+    let provider = typeof priorState.provider === "string" && PROVIDER_PATTERN.test(priorState.provider)
+      ? priorState.provider : "openai";
+    const metadata = {};
+    const events = [];
+    let lastEnd = start;
+    for (const line of completeJsonlLines(buffer, start)) {
+      lastEnd = line.endOffset;
+      const entry = line.entry;
+      if (entry === null) 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") {
+        if (typeof payload.model_provider === "string" && PROVIDER_PATTERN.test(payload.model_provider)) {
+          provider = payload.model_provider;
+        }
+        const hostVersion = boundedMetadataText(payload.cli_version, 64);
+        if (hostVersion) metadata.hostVersion = hostVersion;
+        const entrypoint = boundedMetadataText(payload.originator, 64);
+        if (entrypoint) metadata.entrypoint = entrypoint;
+        const metaCwd = boundedMetadataText(payload.cwd, 2048);
+        if (metaCwd) metadata.cwd = metaCwd;
+        continue;
+      }
+      if (entry.type === "turn_context") {
+        if (typeof payload.model === "string" && USAGE_MODEL_PATTERN.test(payload.model)) {
+          model = payload.model;
+        }
+        const turnCwd = boundedMetadataText(payload.cwd, 2048);
+        if (turnCwd) metadata.cwd = turnCwd;
+        continue;
+      }
+      if (entry.type === "event_msg" && payload.type === "token_count") {
+        events.push(usageEventFromTokenCount(payload.info, {
+          model, provider,
+          byteOffset: line.byteOffset,
+          endOffset: line.endOffset,
+          occurredAt,
+        }));
+      }
+    }
+    return {
+      events,
+      observedEndOffset: drainedEndOffset(lastEnd, start, buffer.length, MAX_DRIVER_SUFFIX_BYTES),
+      metadata,
+      hostState: boundedHostState({ ...priorState, model, provider }),
+    };
+  },
+
+  buildMetadataPayload(metadata, context) {
+    return buildClaudeMetadataPayload(metadata, context);
+  },
+
+  metadataEvent(payload) {
+    return hostMetadataEvent(NAMESPACE, payload);
+  },
+};

package/src/transcript-drivers/index.mjs

@@ -0,0 +1,18 @@
+import { claudeTranscriptDriver } from "./claude.mjs";
+import { codexTranscriptDriver } from "./codex.mjs";
+import { kimiTranscriptDriver } from "./kimi.mjs";
+
+const DRIVERS = Object.freeze({
+  "claude-code": claudeTranscriptDriver,
+  codex: codexTranscriptDriver,
+  "kimi-cli": kimiTranscriptDriver,
+});
+
+/**
+ * The reviewed transcript driver for a client kind, or null. Hosts without a
+ * reviewed driver keep hooks-only capture — absence is a supported state,
+ * never an error.
+ */
+export function transcriptDriverFor(clientKind) {
+  return DRIVERS[String(clientKind ?? "")] ?? null;
+}

package/src/transcript-drivers/kimi.mjs

@@ -0,0 +1,180 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  buildClaudeMetadataPayload,
+  hostMetadataEvent,
+  normalizedEvent,
+  usageInt,
+  USAGE_MODEL_PATTERN,
+} from "../session.mjs";
+import { kimiHome } from "../host-roots.mjs";
+import {
+  boundedHostSessionId,
+  boundedHostState,
+  boundedMetadataText,
+  completeJsonlLines,
+  containedPath,
+  drainedEndOffset,
+  MAX_DRIVER_SUFFIX_BYTES,
+  readSuffixWindow,
+} from "./shared.mjs";
+
+const NAMESPACE = "kimi-cli";
+const MAX_INDEX_BYTES = 8 * 1024 * 1024;
+
+async function readableFile(root, candidate) {
+  const contained = await containedPath(root, candidate);
+  if (contained === null) return null;
+  try {
+    return (await stat(contained)).isFile() ? contained : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Kimi's `session_index.jsonl` maps sessionId -> sessionDir. The index is
+ * host-written but its paths are still treated as untrusted: every sessionDir
+ * is containment-checked under the kimi root before any file inside it is
+ * opened. The primary wire is `<sessionDir>/agents/main/wire.jsonl`; older
+ * layouts kept `<sessionDir>/wire.jsonl`.
+ */
+async function locateWire(root, sessionId) {
+  let indexText;
+  try {
+    indexText = await readFile(join(root, "session_index.jsonl"), "utf8");
+  } catch {
+    return null;
+  }
+  if (Buffer.byteLength(indexText, "utf8") > MAX_INDEX_BYTES) return null;
+  const wanted = new Set([sessionId, `session_${sessionId}`]);
+  let sessionDir = null;
+  let workDir = null;
+  for (const line of indexText.split("\n")) {
+    if (!line) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (entry !== null && typeof entry === "object" && wanted.has(entry.sessionId) &&
+        typeof entry.sessionDir === "string") {
+      sessionDir = entry.sessionDir; // keep last — the index is append-ordered
+      workDir = typeof entry.workDir === "string" ? entry.workDir : null;
+    }
+  }
+  if (sessionDir === null) return null;
+  const containedDir = await containedPath(root, sessionDir);
+  if (containedDir === null) return null;
+  const path = await readableFile(root, join(containedDir, "agents", "main", "wire.jsonl")) ||
+    await readableFile(root, join(containedDir, "wire.jsonl"));
+  if (path === null) return null;
+  const statePath = await readableFile(root, join(containedDir, "state.json"));
+  return { path, statePath, workDir };
+}
+
+function usageEventFromRecord(entry, { byteOffset, endOffset }) {
+  const usage = entry.usage !== null && typeof entry.usage === "object" ? entry.usage : null;
+  const model = typeof entry.model === "string" && USAGE_MODEL_PATTERN.test(entry.model)
+    ? entry.model : null;
+  const occurredAt = Number.isSafeInteger(entry.time) && entry.time > 0
+    ? new Date(entry.time).toISOString() : new Date().toISOString();
+  const input = usageInt(usage?.inputOther);
+  const output = usageInt(usage?.output);
+  if (usage === null || model === null || (input === null && output === null)) {
+    return normalizedEvent({
+      eventKey: `${NAMESPACE}:usage-gap:${byteOffset}`,
+      type: "usage",
+      occurredAt,
+      payload: {
+        role: "assistant", contentFormat: "json", captureStatus: "complete",
+        gap: true, reason: model === null && usage !== null ? "model_unknown" : "usage_unavailable",
+      },
+      sourceEndOffset: endOffset,
+    });
+  }
+  return normalizedEvent({
+    eventKey: `${NAMESPACE}:usage:${byteOffset}`,
+    type: "usage",
+    occurredAt,
+    payload: {
+      role: "assistant",
+      contentFormat: "json",
+      captureStatus: "complete",
+      provider: "moonshot",
+      model,
+      providerRequestId: null,
+      messageId: null,
+      stopReason: null,
+      serviceTier: null,
+      effort: null,
+      sidechain: false,
+      latencyMs: null,
+      // usage.record buckets are named as disjoint shares of the prompt.
+      inputTokens: input,
+      outputTokens: output,
+      cacheReadTokens: usageInt(usage.inputCacheRead),
+      cacheWriteTokens: usageInt(usage.inputCacheCreation),
+      cacheWrite1hTokens: null,
+      cacheWrite5mTokens: null,
+      reasoningTokens: null,
+    },
+    sourceEndOffset: endOffset,
+  });
+}
+
+export const kimiTranscriptDriver = {
+  clientKind: "kimi-cli",
+  eventKeyNamespace: NAMESPACE,
+  usageGapPrefix: `${NAMESPACE}:usage-gap:`,
+
+  async locate(hostSessionId, { env = process.env } = {}) {
+    const raw = String(hostSessionId ?? "");
+    const sessionId = boundedHostSessionId(raw.startsWith("session_") ? raw.slice("session_".length) : raw);
+    if (sessionId === null) return null;
+    const located = await locateWire(kimiHome(env), sessionId);
+    if (located === null) return null;
+    const sessionFacts = {};
+    const cwd = boundedMetadataText(located.workDir, 2048);
+    if (cwd) sessionFacts.cwd = cwd;
+    if (located.statePath !== null) {
+      try {
+        const state = JSON.parse(await readFile(located.statePath, "utf8"));
+        const title = boundedMetadataText(state?.title, 512);
+        if (title) sessionFacts.title = title;
+      } catch {
+        // state.json is optional evidence, never a failure.
+      }
+    }
+    return { path: located.path, sessionFacts };
+  },
+
+  async readSuffix(path, cursor, _sessionHash) {
+    const { buffer, start } = await readSuffixWindow(path, cursor?.byteOffset ?? 0);
+    const metadata = {};
+    const events = [];
+    let lastEnd = start;
+    for (const line of completeJsonlLines(buffer, start)) {
+      lastEnd = line.endOffset;
+      const entry = line.entry;
+      if (entry === null) continue;
+      if (entry.type === "usage.record") {
+        events.push(usageEventFromRecord(entry, {
+          byteOffset: line.byteOffset,
+          endOffset: line.endOffset,
+        }));
+      }
+    }
+    return {
+      events,
+      observedEndOffset: drainedEndOffset(lastEnd, start, buffer.length, MAX_DRIVER_SUFFIX_BYTES),
+      metadata,
+      hostState: boundedHostState(cursor?.hostState),
+    };
+  },
+
+  buildMetadataPayload(metadata, context) {
+    return buildClaudeMetadataPayload(metadata, context);
+  },
+
+  metadataEvent(payload) {
+    return hostMetadataEvent(NAMESPACE, payload);
+  },
+};

package/src/transcript-drivers/shared.mjs

@@ -0,0 +1,104 @@
+import { open, realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+
+// Windowed suffix budget per catch-up call. Successive calls drain the
+// remainder; nothing is skipped, memory stays bounded even for giant files.
+export const MAX_DRIVER_SUFFIX_BYTES = 8 * 1024 * 1024;
+
+// Host session ids are interpolated into filesystem lookups. Anything with a
+// path character is refused outright — no capture beats a contained read of
+// the wrong file (README containment commitment).
+const HOST_SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+
+export function boundedHostSessionId(value) {
+  const text = String(value ?? "");
+  return HOST_SESSION_ID_PATTERN.test(text) ? text : null;
+}
+
+/**
+ * Resolve `candidate` and require it to live under `root` after every
+ * symlink is followed. Index files and cached paths are untrusted input;
+ * any escape resolves to null (no capture), never an error.
+ */
+export async function containedPath(root, candidate) {
+  try {
+    const realRoot = await realpath(root);
+    const resolved = resolve(realRoot, String(candidate ?? ""));
+    if (resolved !== realRoot && !resolved.startsWith(realRoot + sep)) return null;
+    const real = await realpath(resolved);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) return null;
+    return real;
+  } catch {
+    return null;
+  }
+}
+
+/** Positioned read of at most `maxBytes` starting at `byteOffset`. */
+export async function readSuffixWindow(path, byteOffset, maxBytes = MAX_DRIVER_SUFFIX_BYTES) {
+  const handle = await open(path, "r");
+  try {
+    const size = (await handle.stat()).size;
+    const start = Number.isSafeInteger(byteOffset) && byteOffset >= 0 && byteOffset <= size
+      ? byteOffset : 0;
+    const length = Math.min(size - start, maxBytes);
+    const buffer = Buffer.alloc(length);
+    if (length > 0) await handle.read(buffer, 0, length, start);
+    return { buffer, start };
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Yield `{ entry, byteOffset, endOffset }` for every complete JSONL line in
+ * the window. An unparseable line yields `entry: null` (drivers skip it —
+ * unlike the Claude archive, an ignored line is the norm for selective
+ * usage/metadata readers). A trailing record without its newline is left
+ * unread for the next catch-up.
+ */
+export function* completeJsonlLines(buffer, start) {
+  let position = 0;
+  while (position < buffer.length) {
+    const newline = buffer.indexOf(0x0a, position);
+    if (newline === -1) break;
+    let entry = null;
+    try {
+      const parsed = JSON.parse(buffer.subarray(position, newline).toString("utf8"));
+      entry = parsed !== null && typeof parsed === "object" ? parsed : null;
+    } catch {
+      entry = null;
+    }
+    yield { entry, byteOffset: start + position, endOffset: start + newline + 1 };
+    position = newline + 1;
+  }
+}
+
+/**
+ * End offset for a drained window. If a full window held no newline at all
+ * (pathological single-line file), advance past it rather than re-reading the
+ * same bytes forever — usage lines are tiny, so nothing real is lost.
+ */
+export function drainedEndOffset(lastEndOffset, start, bufferLength, maxBytes) {
+  if (lastEndOffset > start) return lastEndOffset;
+  if (bufferLength >= maxBytes) return start + bufferLength;
+  return start;
+}
+
+const MAX_HOST_STATE_BYTES = 1024;
+
+/** Bound the per-session driver scratch state persisted on the cursor. */
+export function boundedHostState(value) {
+  if (value === null || typeof value !== "object") return undefined;
+  const serialized = JSON.stringify(value);
+  return Buffer.byteLength(serialized, "utf8") <= MAX_HOST_STATE_BYTES ? value : undefined;
+}
+
+/**
+ * Bound for host-supplied metadata strings, mirroring collectClaudeMetadata:
+ * non-empty, capped, and free of control characters. The server rejects a
+ * whole batch over an oversized field, so bounding here is not cosmetic.
+ */
+export function boundedMetadataText(value, max) {
+  return typeof value === "string" && value.length > 0 && value.length <= max &&
+    !/[\u0000-\u001f\u007f]/.test(value) ? value : undefined;
+}

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.5.1";
-export const RUNTIME_VERSION = "0.5.1";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-31.1";
+export const INSTALLER_VERSION = "0.6.0";
+export const RUNTIME_VERSION = "0.6.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-31.2";