agent-peers 0.1.0 → 0.3.0

package/src/diagnostics.mjs

@@ -1,14 +1,56 @@
-import { lstatSync } from "node:fs";
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { isAbsolute, join } from "node:path";
-import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
 import { VERSION } from "./version.mjs";
 import { claudeHome, peersHome } from "./wire.mjs";
+import { loggingConfig } from "./logging.mjs";
+import { daemonSocket } from "./app-server.mjs";
 
 const require = createRequire(import.meta.url);
 
-// Inspect metadata only: no configuration writes, daemon startup or model turns.
-export function diagnose() {
+function daemonStat(path) {
+  const link = lstatSync(path);
+  if (!link.isSymbolicLink()) return link;
+  if (process.getuid && link.uid !== process.getuid()) throw new Error("daemon socket link must belong to this user");
+  // Codex publishes its short runtime socket through an owned symlink. Only this
+  // daemon endpoint permits indirection; peer registry/socket rules stay strict.
+  let target;
+  try { target = realpathSync(path); }
+  catch (error) {
+    if (error.code === "ENOENT") throw Object.assign(new Error(readlinkSync(path)), { code: "STALE_LINK" });
+    throw error;
+  }
+  for (const directory of [dirname(path), dirname(target)]) {
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o022)) {
+      throw new Error("daemon socket link and target require owned directories without shared write access");
+    }
+  }
+  return lstatSync(target);
+}
+
+const START_DAEMON = "start it with `codex app-server daemon start`, or open a Codex session";
+
+// One handshake and a loaded-thread read: a socket file can outlive its server, for example
+// across a reboot. Nothing is logged, started or loaded.
+async function daemonAnswers(path) {
+  const { AppServer } = await import("./app-server.mjs");
+  const app = new AppServer(undefined, { connectTimeoutMs: 2000, handshakeTimeoutMs: 2000, log: () => {} });
+  try {
+    const result = await app.request("thread/loaded/list", {}, 3000);
+    const count = Array.isArray(result?.data) ? `${result.data.length}${result.nextCursor ? "+" : ""}` : "unknown";
+    return { status: "ok", message: `${path} (answering; ${count} loaded threads)` };
+  } catch (error) {
+    const reason = error?.code === "ECONNREFUSED" ? "connection refused" : String(error?.code || error?.message || "no answer");
+    const configured = process.env.AGENT_PEERS_CODEX_APP_SERVER ? "the configured app-server" : "Codex's shared daemon";
+    return { status: "warning", message: `${path} is not answering (${reason}); ${configured} is not running` +
+      (process.env.AGENT_PEERS_CODEX_APP_SERVER ? "" : `: ${START_DAEMON}`) };
+  } finally { app.close(); }
+}
+
+// Inspect metadata and ask the app-server one read-only question: no configuration writes,
+// daemon startup or model turns.
+export async function diagnose() {
   const checks = [];
   const add = (name, status, message) => checks.push({ name, status, message });
   add("node", Number(process.versions.node.split(".")[0]) >= 22 ? "ok" : "error", process.version);
@@ -20,23 +62,30 @@ export function diagnose() {
   const paths = [
     ["claude registry", join(claudeHome(), "sessions"), "directory", false],
     ["peer registry", peersHome(), "directory", true],
-    ["codex daemon", process.env.AGENT_PEERS_CODEX_APP_SERVER ||
-      join(process.env.CODEX_HOME || join(homedir(), ".codex"), "app-server-control", "app-server-control.sock"), "socket", false],
+    ["codex daemon", daemonSocket(), "socket", false],
   ];
   for (const [name, path, kind, privateMode] of paths) {
     if (!isAbsolute(path)) { add(name, "error", `expected an absolute path: ${path}`); continue; }
     try {
-      const stat = lstatSync(path);
+      const stat = kind === "socket" ? daemonStat(path) : lstatSync(path);
       if (stat.isSymbolicLink() || (kind === "socket" ? !stat.isSocket() : !stat.isDirectory())) {
         add(name, "error", `${path} must be a ${kind}, not a symlink or another file type`);
       } else if ((process.getuid && stat.uid !== process.getuid()) || (stat.mode & (privateMode ? 0o077 : 0o022))) {
         add(name, "error", `${path} must belong to this user and have safe permissions`);
+      } else if (kind === "socket") {
+        const live = await daemonAnswers(path);
+        add(name, live.status, live.message);
       } else add(name, "ok", path);
     } catch (error) {
-      if (error.code === "ENOENT") add(name, "warning", `${path} is absent; start the corresponding agent to use it`);
+      if (error.code === "STALE_LINK") add(name, "warning", `${path} links to a missing socket (${error.message}); Codex's shared daemon is not running: ${START_DAEMON}`);
+      else if (error.code === "ENOENT") add(name, "warning", `${path} is absent; start the corresponding agent to use it`);
       else add(name, "error", `${path}: ${error.message}`);
     }
   }
-  add("compatibility", "warning", "Socket presence is not a delivery check. Codex must use its shared daemon; Hermes replies require the documented route APIs. See the compatibility guide.");
-  return { version: VERSION, ok: !checks.some((c) => c.status === "error"), checks };
+  const logging = loggingConfig();
+  add("logging", logging.enabled && !logging.valid ? "error" : "ok", logging.enabled
+    ? `enabled; ${logging.mode}: ${logging.location}${logging.valid ? "" : "; expected an absolute normalized path"}`
+    : `disabled; set AGENT_PEERS_DEBUG=1 to capture future events in ${logging.location}`);
+  add("compatibility", "warning", "An answering daemon is not a delivery check. Codex threads are reachable only on the app-server agent-peers is pointed at; Hermes replies require the documented route APIs. See the compatibility guide.");
+  return { version: VERSION, ok: !checks.some((c) => c.status === "error"), logging, checks };
 }

package/src/discovery.mjs

@@ -40,18 +40,47 @@ export function codexDiscovery(peers, threads, self) {
   return [...rows.values()];
 }
 
+// Explain a route mismatch without sending anything or treating a nickname as a bridge
+// address. Match against all discovered peers so an abbreviation cannot silently select
+// one native agent when another peer has a matching name.
+export function nativeRouteError(to, peers) {
+  if (typeof to !== "string" || !to || to.startsWith("uds:")) return null;
+  const exact = peers.filter((p) => p.name === to || p.name === `codex:${to}` || p.name === `claude:${to}` ||
+    p.native?.target === to || p.threadId === to);
+  const matches = exact.length ? exact : peers.filter((p) => p.name.includes(to));
+  if (matches.length !== 1) return null;
+  const p = matches[0];
+  if (p.native?.reachable !== true || !p.native.target || p.bridge) return null;
+  const subagent = p.native.target !== "/root";
+  let message = `${JSON.stringify(p.name)} is a native Codex ${subagent ? "subagent" : "agent"} without a bridge route; ` +
+    `send_peer cannot address it. Use native ${p.native.tool} ${JSON.stringify({ target: p.native.target })}.`;
+  if (p.status === "idle") {
+    message += subagent
+      ? ` It is idle; use native followup_task ${JSON.stringify({ target: p.native.target })} to start a turn; send_message only queues a message.`
+      : " Native send_message does not start an idle turn for the root agent.";
+  }
+  if (subagent) message += " Direct app-server input, including codex_tui.send_message_to_thread, is unsupported for subagents.";
+  return message;
+}
+
 export function formatCodexPeer(p) {
   const native = p.native.reachable === true
     ? `yes — ${p.native.tool} ${JSON.stringify({ target: p.native.target })}`
     : `${p.native.reachable === false ? "no" : "unknown"} (${p.native.reason})`;
-  const bridge = p.bridge ? `${p.bridge.tool} ${JSON.stringify({ to: p.bridge.to })}` : "none (use native messaging)";
-  return `${p.name}  ${p.status ?? ""}  cwd=${p.cwd}\n  native: ${native}\n  bridge: ${bridge}`;
+  const subagent = p.native.reachable === true && p.native.target !== "/root";
+  const bridge = p.bridge ? `${p.bridge.tool} ${JSON.stringify({ to: p.bridge.to })}`
+    : subagent ? "none (use native messaging; send_peer and direct app-server input cannot target this subagent)"
+    : p.native.reachable === true ? "none (use native messaging)" : "none (check list_agents for a native target)";
+  const wake = subagent && p.status === "idle"
+    ? `\n  start idle turn: followup_task ${JSON.stringify({ target: p.native.target })} (send_message only queues a message)` : "";
+  return `${p.name}  ${p.status ?? ""}  cwd=${p.cwd}\n  native: ${native}\n  bridge: ${bridge}${wake}`;
 }
 
 // The CLI is also used outside Codex, where there is no caller thread to compare.
 // Name the platform explicitly rather than implying Claude's SendMessage is a Codex tool.
 export function formatSessionPeer(p) {
-  return `${p.name}  ${p.status ?? ""}  cwd=${p.cwd}\n` +
+  return `${p.name}  ${p.status ?? ""}${p.reachable === false ? "  stale" : ""}  cwd=${p.cwd}\n` +
+    (p.reachable === false ? "  stale: the socket refused a connection; the record is kept\n" : "") +
     `  Claude native: SendMessage ${JSON.stringify({ to: p.address })}\n` +
     `  Codex bridge: send_peer ${JSON.stringify({ to: p.address })}`;
 }

package/src/guidance.mjs

@@ -1,5 +1,4 @@
 // Codex's session guidance; the same preference appears in the Claude setup snippet.
 export const coordinationGuidance =
-  "Before messaging, weigh its value against token cost and distraction; keep it concise and avoid repetitive or low-value chatter. " +
-  "Prefer coordination around scope, decisions, and handoffs. " +
-  "Routine progress updates can usually wait; use your judgment about when a discussion or reply would help.";
+  "Keep coordination useful and brief. Send what's new; link existing detail rather than repeating it. " +
+  "Reply when it adds value.";

package/src/hermes-bridge.mjs

@@ -6,6 +6,7 @@ import { chmodSync, lstatSync, rmSync } from "node:fs";
 import { createServer } from "node:net";
 import { dirname, join } from "node:path";
 import { AppServer } from "./app-server.mjs";
+import { errorFields, logEvent, logIdentity } from "./logging.mjs";
 import {
   MAX_LINE, MAX_SOCKET_PATH, address, allPeers, messageLine, parseEnvelope, peerSocket, post, readLines,
 } from "./wire.mjs";
@@ -14,6 +15,11 @@ const BUCKET = 30, REFILL_PER_S = 0.5, DEDUP_MS = 30_000, IDLE_MS = 600_000;
 const QUEUE_MAX = 50, TOTAL_QUEUE_MAX = 200, SOURCES_MAX = 256, SESSIONS_MAX = 256;
 const IPC_QUEUE_MAX = 128, IPC_WRITE_TIMEOUT_MS = 5000;
 const logger = (message) => console.error(`[hermes-bridge ${process.pid}] ${message}`);
+const event = (name, fields) => logEvent("hermes-bridge", name, fields);
+const safeError = (error) => {
+  const { reason, errorCode } = errorFields(error);
+  return errorCode && errorCode !== "unknown" ? `${reason} (${errorCode})` : reason;
+};
 
 function requiredString(value, field, max = MAX_LINE) {
   if (typeof value !== "string" || !value.trim() || value.length > max) {
@@ -53,7 +59,39 @@ export class HermesBridge {
     this.#log = log;
   }
 
+  #introduced = new Set();
+
+  #firstContact(key) {
+    if (this.#introduced.has(key)) return false;
+    if (this.#introduced.size >= 4096) this.#introduced.clear();
+    this.#introduced.add(key);
+    return true;
+  }
+
   async request(method, params = {}) {
+    const operationId = randomUUID(), started = performance.now();
+    const fields = {
+      operationId, method: ["list_peers", "send_peer", "close_session"].includes(method) ? method : "unknown",
+      ...(typeof params?.session === "string" ? { sessionId: logIdentity(params.session) } : {}),
+      ...(typeof params?.to === "string" ? { targetId: logIdentity(params.to) } : {}),
+      ...(typeof params?.message === "string" ? { bytes: Buffer.byteLength(params.message) } : {}),
+    };
+    event("tool.request", fields);
+    try {
+      const result = await this.#request(method, params, operationId);
+      event("tool.result", {
+        ...fields, durationMs: performance.now() - started,
+        outcome: result.note || result.status && result.status !== "delivered" ? "warning" : "success",
+        ...(Array.isArray(result.peers) ? { bridgeCount: result.peers.length } : {}),
+      });
+      return result;
+    } catch (error) {
+      event("tool.result", { ...fields, outcome: "error", durationMs: performance.now() - started, ...errorFields(error) });
+      throw error;
+    }
+  }
+
+  async #request(method, params, operationId) {
     if (this.#closed) throw new Error("Hermes bridge is closed");
     if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error("params must be an object");
     if (method === "list_peers") return this.#listPeers();
@@ -63,7 +101,7 @@ export class HermesBridge {
     const previous = this.#locks.get(session) ?? Promise.resolve();
     const operation = previous.catch(() => {}).then(async () => {
       if (this.#closed) throw new Error("Hermes bridge is closed");
-      if (method === "send_peer") return this.#send(session, params);
+      if (method === "send_peer") return this.#send(session, params, operationId);
       const routes = [...this.#routes.values()].filter((route) => route.session === session);
       await Promise.all(routes.map((route) => this.#retire(route)));
       return { closed: routes.length > 0 };
@@ -137,12 +175,18 @@ export class HermesBridge {
       buckets: new Map(), recent: new Map(), pending: new Map(), queued: 0, chain: Promise.resolve(),
     };
     route.server = createServer((conn) => {
-      if (route.closed || route.connections.size >= QUEUE_MAX) return conn.destroy();
+      if (route.closed || route.connections.size >= QUEUE_MAX) {
+        event("receive.dropped", { sessionId: logIdentity(session), reason: route.closed ? "closed" : "queue_full" });
+        return conn.destroy();
+      }
       route.connections.add(conn);
       conn.once("close", () => route.connections.delete(conn));
       readLines(conn, (line) => this.#receive(route, line));
     });
-    route.server.on("error", (error) => this.#log(`inbox error: ${error.message}`));
+    route.server.on("error", (error) => {
+      event("inbox.error", { sessionId: logIdentity(session), ...errorFields(error) });
+      this.#log(`inbox error: ${safeError(error)}`);
+    });
     try {
       await new Promise((resolve, reject) => {
         route.server.once("error", reject);
@@ -152,6 +196,7 @@ export class HermesBridge {
       route.owner = lstatSync(socket);
       chmodSync(socket, 0o600);
       this.#routes.set(key, route);
+      event("inbox.bound", { sessionId: logIdentity(session), targetId: logIdentity(route.address) });
     } catch (error) {
       route.closed = true;
       for (const conn of route.connections) conn.destroy();
@@ -163,7 +208,30 @@ export class HermesBridge {
     return route;
   }
 
-  async #send(session, params) {
+  async #send(session, params, operationId) {
+    const started = performance.now(), messageId = randomUUID();
+    const fields = {
+      operationId, messageId: logIdentity(messageId), sessionId: logIdentity(session),
+      ...(typeof params.to === "string" ? { targetId: logIdentity(params.to) } : {}),
+      ...(typeof params.message === "string" ? { bytes: Buffer.byteLength(params.message) } : {}),
+    };
+    event("send.started", fields);
+    try {
+      const result = await this.#post(session, params, messageId, fields);
+      const status = result.status;
+      event("send.result", {
+        ...fields, durationMs: performance.now() - started,
+        outcome: status === "held" ? "held" : status === "delivered" ? "receipt_delivered" : status ? "rejected" : "inbox_written",
+        receipt: Boolean(status),
+      });
+      return result;
+    } catch (error) {
+      event("send.result", { ...fields, outcome: "error", durationMs: performance.now() - started, ...errorFields(error) });
+      throw error;
+    }
+  }
+
+  async #post(session, params, messageId, fields) {
     const name = requiredString(params.name, "name", 80);
     if (!/^hermes:[A-Za-z0-9:_-]+$/.test(name)) throw new Error("name must identify a Hermes profile as hermes:<profile>");
     const to = requiredString(params.to, "to", 512);
@@ -173,11 +241,12 @@ export class HermesBridge {
     if (!targetSocket) throw new Error("the peer registry contains an invalid inbox address; call list_peers again");
     const route = await this.#bind(session, name, dirname(targetSocket));
     if (target.address === route.address) throw new Error("that address is this conversation's own inbox");
-    // Claude labels every external envelope as another Claude session. Correct that frame.
-    const body = target.kind === "codex" ? message : `${message}\n\n` +
-      `(From ${name}, a Hermes profile with a private reply inbox. Use your peer messaging tool ` +
-      `to reply to the sender address. Claude's notify_when_idle is unavailable for this peer.)`;
-    const line = messageLine({ from: route.address, fromName: name, body });
+    // Claude labels every external envelope as another Claude session. Correct that frame once
+    // per conversation and recipient: the recipient keeps it in context.
+    const body = target.kind === "claude" && this.#firstContact(`${session}\0${target.address}`)
+      ? `${message}\n\n(Hermes profile; notify_when_idle unavailable.)`
+      : message;
+    const line = { ...messageLine({ from: route.address, fromName: name, body }), msg_id: messageId };
     let finish, timer;
     const receipt = new Promise((resolve) => {
       finish = resolve;
@@ -185,12 +254,14 @@ export class HermesBridge {
       timer = setTimeout(() => resolve(undefined), 1500);
     });
     try {
+      const started = performance.now();
       await post(targetSocket, line);
+      event("message.send", { ...fields, outcome: "inbox_written", durationMs: performance.now() - started });
       const status = await receipt;
       const text = status === "held"
         ? `Delivered to ${target.name}'s inbox; its session is holding it for its user's approval.`
         : status && status !== "delivered" ? `Not delivered to ${target.name}: ${status}.`
-          : `Delivered to ${target.name}'s inbox. Any reply arrives in this Hermes conversation.`;
+          : `Delivered to ${target.name}'s inbox.`;
       return { text, address: route.address, message_id: line.msg_id, ...(status ? { status } : {}) };
     } finally {
       clearTimeout(timer);
@@ -203,42 +274,60 @@ export class HermesBridge {
     const now = Date.now();
     for (const [key, bucket] of route.buckets) if (now - bucket.at > IDLE_MS) route.buckets.delete(key);
     for (const [key, time] of route.recent) if (now - time > DEDUP_MS) route.recent.delete(key);
-    if (!route.buckets.has(from) && route.buckets.size >= SOURCES_MAX) return false;
+    if (!route.buckets.has(from) && route.buckets.size >= SOURCES_MAX) return "rate_limit";
     const bucket = route.buckets.get(from) ?? { tokens: BUCKET, at: now };
     bucket.tokens = Math.min(BUCKET, bucket.tokens + (now - bucket.at) / 1000 * REFILL_PER_S);
     bucket.at = now;
     route.buckets.set(from, bucket);
     const bodyKey = createHash("sha256").update(from).update("\0").update(body).digest("hex");
     const idKey = `${from}\0${id}`;
-    if (bucket.tokens < 1 || route.recent.has(bodyKey) || route.recent.has(idKey) ||
-        route.queued >= QUEUE_MAX || this.#queued >= TOTAL_QUEUE_MAX) return false;
+    if (route.recent.has(bodyKey) || route.recent.has(idKey)) return "duplicate";
+    if (bucket.tokens < 1) return "rate_limit";
+    if (route.queued >= QUEUE_MAX || this.#queued >= TOTAL_QUEUE_MAX) return "queue_full";
     bucket.tokens--;
     route.recent.set(bodyKey, now);
     route.recent.set(idKey, now);
-    return true;
+    return undefined;
   }
 
   #receive(route, line) {
-    if (route.closed || !line || typeof line !== "object") return;
+    const sessionId = logIdentity(route.session);
+    const drop = (reason, fields = {}) => event("receive.dropped", { sessionId, reason, ...fields });
+    if (route.closed) return drop("closed");
+    if (!line || typeof line !== "object") return drop("malformed");
     if (line.type === "control" && line.action === "peer_message_status") {
-      if (typeof line.status === "string" && line.status.length <= 128) route.pending.get(line.orig_msg_id)?.(line.status);
+      if (typeof line.status !== "string" || !line.status.length || line.status.length > 128 ||
+          typeof line.orig_msg_id !== "string") return drop("malformed");
+      route.pending.get(line.orig_msg_id)?.(line.status);
       return;
     }
-    if (line.type !== "user" || typeof line.message?.content !== "string") return;
+    if (line.type !== "user" || typeof line.message?.content !== "string") return drop("malformed");
     const env = parseEnvelope(line.message.content);
-    if (!env || !peerSocket(env.from) || env.from === route.address || (line.from && line.from !== env.from)) return;
+    if (!env || !peerSocket(env.from) || env.from === route.address || (line.from && line.from !== env.from)) return drop("malformed");
     const id = typeof line.msg_id === "string" && line.msg_id.length <= 256 && line.msg_id ? line.msg_id : randomUUID();
-    if (!this.#admit(route, env.from, env.body, id)) return;
+    const fields = { sessionId, messageId: logIdentity(id), targetId: logIdentity(env.from), bytes: Buffer.byteLength(env.body) };
+    const notification = { method: "peer_message", params: {
+      session: route.session, message_id: id, from: env.from,
+      from_name: /^[A-Za-z0-9:_ .-]{1,80}$/.test(env.fromName ?? "") ? env.fromName : "an unnamed peer",
+      message: env.body,
+    } };
+    // The host reads at most MAX_LINE per line and restarts the bridge on a longer one; a frame
+    // that fits the inbox can exceed that once re-encoded with session and message IDs.
+    if (Buffer.byteLength(JSON.stringify(notification)) + 1 > MAX_LINE) return drop("message_too_large", fields);
+    const reason = this.#admit(route, env.from, env.body, id);
+    if (reason) return drop(reason, fields);
     route.queued++;
     this.#queued++;
+    event("receive.queued", { ...fields, queueDepth: route.queued });
+    const started = performance.now();
     route.chain = route.chain.then(async () => {
-      if (route.closed) return;
-      await this.#emit({ method: "peer_message", params: {
-        session: route.session, message_id: id, from: env.from,
-        from_name: /^[A-Za-z0-9:_ .-]{1,80}$/.test(env.fromName ?? "") ? env.fromName : "an unnamed peer",
-        message: env.body,
-      } });
-    }).catch((error) => this.#log(`incoming message delivery failed: ${error.message}`))
+      if (route.closed) return drop("closed", fields);
+      await this.#emit(notification);
+      event("delivery.result", { ...fields, outcome: "emitted_to_host", durationMs: performance.now() - started });
+    }).catch((error) => {
+      event("delivery.result", { ...fields, outcome: "error", durationMs: performance.now() - started, ...errorFields(error) });
+      this.#log(`incoming message delivery failed: ${safeError(error)}`);
+    })
       .finally(() => { route.queued--; this.#queued--; });
   }
 
@@ -253,7 +342,7 @@ export class HermesBridge {
       const current = lstatSync(route.socket);
       owned = current.dev === route.owner.dev && current.ino === route.owner.ino;
     } catch (error) {
-      if (error.code !== "ENOENT") this.#log(`cannot inspect inbox ownership: ${error.message}`);
+      if (error.code !== "ENOENT") this.#log(`cannot inspect inbox ownership: ${safeError(error)}`);
     }
     if (owned) {
       // Node closes and unlinks a Unix listener by pathname; do not close it if somebody
@@ -270,6 +359,7 @@ export class HermesBridge {
     }
     route.buckets.clear();
     route.recent.clear();
+    event("inbox.closed", { sessionId: logIdentity(route.session), targetId: logIdentity(route.address), queueDepth: route.queued });
   }
 
   close() {
@@ -292,6 +382,7 @@ export class HermesBridge {
 export function runHermesBridge() {
   const write = (message) => new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
+      event("bridge.error", { reason: "timeout" });
       reject(new Error("bridge output timed out"));
       void stop(1);
     }, IPC_WRITE_TIMEOUT_MS);
@@ -312,7 +403,8 @@ export function runHermesBridge() {
     try {
       await bridge.close();
     } catch (error) {
-      logger(`bridge shutdown failed: ${error.message}`);
+      event("bridge.error", errorFields(error));
+      logger(`bridge shutdown failed: ${safeError(error)}`);
       code = 1;
     }
     process.exit(code);
@@ -326,6 +418,7 @@ export function runHermesBridge() {
       const raw = buffer.slice(0, newline);
       buffer = buffer.slice(newline + 1);
       if (Buffer.byteLength(raw) + 1 > MAX_LINE || queued >= IPC_QUEUE_MAX) {
+        event("bridge.error", { reason: queued >= IPC_QUEUE_MAX ? "queue_full" : "message_too_large", queueDepth: queued });
         logger("bridge input limit exceeded");
         void stop(1);
         return;
@@ -352,25 +445,28 @@ export function runHermesBridge() {
           const result = await bridge.request(request.method, request.params);
           await write({ id, result });
         } catch (error) {
+          if (id === null) event("bridge.error", { reason: "malformed" });
           await write({ id, error: { message: error.message } });
         }
-      }).catch((error) => { logger(error.message); void stop(1); }).finally(() => queued--);
+      }).catch((error) => { event("bridge.error", errorFields(error)); logger(safeError(error)); void stop(1); }).finally(() => queued--);
     }
     if (Buffer.byteLength(buffer) >= MAX_LINE) {
+      event("bridge.error", { reason: "message_too_large" });
       logger("bridge input line too large");
       void stop(1);
     }
   });
   process.stdin.on("end", () => {
     if (buffer.trim()) {
+      event("bridge.error", { reason: "malformed" });
       logger("incomplete bridge input at EOF");
       void stop(1);
     } else void chain.finally(() => stop());
   });
-  process.stdin.on("error", () => { void stop(1); });
-  process.stdout.on("error", () => { void stop(1); });
+  process.stdin.on("error", (error) => { event("bridge.error", errorFields(error)); void stop(1); });
+  process.stdout.on("error", (error) => { event("bridge.error", errorFields(error)); void stop(1); });
   process.once("SIGINT", () => { void stop(); });
   process.once("SIGTERM", () => { void stop(); });
-  process.on("uncaughtException", (error) => { logger(error.message); void stop(1); });
+  process.on("uncaughtException", (error) => { event("bridge.error", errorFields(error)); logger(safeError(error)); void stop(1); });
   return bridge;
 }