@agent-team-foundation/first-tree-hub 0.8.1 → 0.8.3

package/dist/{core-BA5U1v9L.mjs → core-CxoH-s16.mjs}

@@ -1,15 +1,18 @@
-import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, x as resolveConfigReadonly } from "./bootstrap-8nCntTrK.mjs";
-import { $ as updateAgentRuntimeConfigSchema, A as createMemberSchema, B as notificationQuerySchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as inboxPollQuerySchema, G as sendMessageSchema, H as refreshTokenSchema, I as isRedactedEnvValue, J as sessionEventMessageSchema, K as sendToAgentSchema, L as linkTaskChatSchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as updateAdapterConfigSchema, R as loginSchema, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as runtimeStateMessageSchema, V as paginationQuerySchema, W as selfServiceFeishuBotSchema, X as sessionStateMessageSchema, Y as sessionEventSchema$1, Z as taskListQuerySchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as wsAuthFrameSchema, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateAgentSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as updateTaskStatusSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateOrganizationSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionCompletionMessageSchema, rt as updateSystemConfigSchema, s as AGENT_STATUSES, tt as updateMemberSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as messageSourceSchema$1 } from "./feishu-D9JkMZnU.mjs";
+import { m as __toESM } from "./esm-CYu4tXXn.mjs";
+import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, x as resolveConfigReadonly } from "./bootstrap-99vUYmLs.mjs";
+import { _ as withSpan, a as endWsConnectionSpan, b as require_pino, c as messageAttrs, d as rootLogger$1, g as startWsConnectionSpan, i as currentTraceId, n as applyLoggerConfig, o as getFastifyOtelPlugin, p as setWsConnectionAttrs, r as createLogger, t as adapterAttrs, u as observabilityPlugin, v as withWsMessageSpan, y as FIRST_TREE_HUB_ATTR } from "./observability-CJzDFY_G-CmvgUuzc.mjs";
+import { $ as updateAgentRuntimeConfigSchema, A as createMemberSchema, B as notificationQuerySchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as inboxPollQuerySchema, G as sendMessageSchema, H as refreshTokenSchema, I as isRedactedEnvValue, J as sessionEventMessageSchema, K as sendToAgentSchema, L as linkTaskChatSchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as updateAdapterConfigSchema, R as loginSchema, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as runtimeStateMessageSchema, V as paginationQuerySchema, W as selfServiceFeishuBotSchema, X as sessionStateMessageSchema, Y as sessionEventSchema$1, Z as taskListQuerySchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as wsAuthFrameSchema, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateAgentSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as updateTaskStatusSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateOrganizationSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionCompletionMessageSchema, rt as updateSystemConfigSchema, s as AGENT_STATUSES, tt as updateMemberSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as messageSourceSchema$1 } from "./feishu-BOISS0DK.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { ZodError, z } from "zod";
+import { Writable } from "node:stream";
 import { stringify } from "yaml";
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir, hostname, platform, userInfo } from "node:os";
 import { EventEmitter } from "node:events";
 import WebSocket from "ws";
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import { execFileSync, execSync, spawn } from "node:child_process";
+import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
 import bcrypt from "bcrypt";
 import { and, asc, count, desc, eq, gt, inArray, isNotNull, isNull, lt, ne, or, sql } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/postgres-js";
@@ -25,6 +28,136 @@ import Fastify from "fastify";
 import { bigserial, boolean, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique, uniqueIndex } from "drizzle-orm/pg-core";
 import { SignJWT, jwtVerify } from "jose";
 import { Client, EventDispatcher, LoggerLevel, WSClient } from "@larksuiteoapi/node-sdk";
+//#region ../client/dist/observability-BUvHY6T-.mjs
+var import_pino = /* @__PURE__ */ __toESM(require_pino(), 1);
+/**
+* Logger core — format / level primitives shared between server and client.
+*
+* This module intentionally has no dependency on `pino` so it can live in
+* `@agent-team-foundation/first-tree-hub-shared`. Consumers construct their
+* own pino instance and pass the output stream built here.
+*/
+const LOG_LEVELS = [
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+];
+const LOG_FORMATS = ["pretty", "json"];
+const logLevelSchema = z.enum(LOG_LEVELS);
+const logFormatSchema = z.enum(LOG_FORMATS);
+/**
+* Parse an env-var / config string into a LogLevel. Unknown values fall back
+* to `info` so the process never fails to boot on a typo — the caller is
+* responsible for emitting a warning when `fellBack` is true.
+*/
+function parseLogLevel(raw) {
+	if (!raw) return {
+		level: "info",
+		fellBack: false
+	};
+	const parsed = logLevelSchema.safeParse(raw);
+	if (parsed.success) return {
+		level: parsed.data,
+		fellBack: false
+	};
+	return {
+		level: "info",
+		fellBack: true
+	};
+}
+const LEVEL_LABELS = {
+	10: "TRACE",
+	20: "DEBUG",
+	30: "INFO",
+	40: "WARN",
+	50: "ERROR",
+	60: "FATAL"
+};
+const LEVEL_COLORS = {
+	10: "\x1B[90m",
+	20: "\x1B[36m",
+	30: "\x1B[32m",
+	40: "\x1B[33m",
+	50: "\x1B[31m",
+	60: "\x1B[35m"
+};
+const RESET = "\x1B[0m";
+const DIM = "\x1B[2m";
+const SKIP_KEYS = new Set([
+	"level",
+	"time",
+	"msg",
+	"module",
+	"pid",
+	"hostname",
+	"v"
+]);
+function formatPrettyEntry(json) {
+	const obj = JSON.parse(json);
+	const level = obj.level;
+	const label = LEVEL_LABELS[level] ?? "???";
+	const color = LEVEL_COLORS[level] ?? "";
+	const time = obj.time ?? (/* @__PURE__ */ new Date()).toISOString();
+	const module = obj.module ? `[${String(obj.module)}] ` : "";
+	const msg = obj.msg ?? "";
+	const extras = [];
+	let errStack = "";
+	for (const [k, v] of Object.entries(obj)) {
+		if (SKIP_KEYS.has(k)) continue;
+		if (k === "err" && v && typeof v === "object") {
+			const e = v;
+			if (e.message) extras.push(`err.message=${String(e.message)}`);
+			if (typeof e.stack === "string") errStack = `\n${DIM}${e.stack}${RESET}`;
+		} else extras.push(`${k}=${typeof v === "string" ? v : JSON.stringify(v)}`);
+	}
+	const extraStr = extras.length > 0 ? `  ${DIM}${extras.join(" ")}${RESET}` : "";
+	return `${DIM}${time}${RESET} ${color}${label.padEnd(5)}${RESET} ${module}${msg}${extraStr}${errStack}\n`;
+}
+function formatLocalTime() {
+	const d = /* @__PURE__ */ new Date();
+	return `${d.toLocaleDateString("sv-SE")} ${d.toLocaleTimeString("en-GB", { hour12: false })}`;
+}
+function createLoggerOutputStream(options) {
+	return new Writable({ write(chunk, _, callback) {
+		const text = chunk.toString();
+		try {
+			if (options.getFormat() === "pretty") process.stdout.write(formatPrettyEntry(text));
+			else process.stdout.write(text);
+			if (options.onJsonEntry) try {
+				const obj = JSON.parse(text);
+				options.onJsonEntry(obj);
+			} catch {}
+		} catch {
+			process.stdout.write(text);
+		}
+		callback();
+	} });
+}
+/**
+* Client-side logger. Same pretty / NDJSON formats as the server logger, but
+* intentionally lightweight — the client is deployed to agent user machines,
+* so we skip tracing, context propagation, and error sinks.
+*/
+const initialLevel = parseLogLevel(process.env.FIRST_TREE_HUB_LOG_LEVEL);
+let _format = process.env.NODE_ENV === "production" ? "json" : "pretty";
+let _level = initialLevel.level;
+function applyClientLoggerConfig(options = {}) {
+	if (options.level) {
+		_level = options.level;
+		rootLogger.level = options.level;
+	}
+	if (options.format) _format = options.format;
+}
+const outputStream = createLoggerOutputStream({ getFormat: () => _format });
+const rootLogger = (0, import_pino.default)({
+	level: _level,
+	timestamp: () => `,"time":"${formatLocalTime()}"`
+}, outputStream);
+if (initialLevel.fellBack) rootLogger.warn({ envValue: process.env.FIRST_TREE_HUB_LOG_LEVEL }, "invalid FIRST_TREE_HUB_LOG_LEVEL; falling back to info");
+//#endregion
 //#region ../client/dist/index.mjs
 const adapterPlatformSchema = z.enum([
 	"feishu",
@@ -1350,12 +1483,7 @@ defineConfig({
 		auto: "client-id",
 		env: "FIRST_TREE_HUB_CLIENT_ID"
 	}) },
-	logLevel: field(z.enum([
-		"debug",
-		"info",
-		"warn",
-		"error"
-	]).default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" })
+	logLevel: field(logLevelSchema.default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" })
 });
 const DEFAULT_HOME_DIR = process.env.FIRST_TREE_HUB_HOME ?? join(homedir(), ".first-tree-hub");
 join(DEFAULT_HOME_DIR, "config");
@@ -1422,7 +1550,29 @@ defineConfig({
 			secret: true
 		}),
 		hubPublicUrl: field(z.string(), { env: "FIRST_TREE_HUB_PUBLIC_URL" })
-	})
+	}),
+	observability: {
+		logging: {
+			level: field(logLevelSchema.default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" }),
+			format: field(logFormatSchema.default(process.env.NODE_ENV === "production" ? "json" : "pretty")),
+			bridgeToSpanLevel: field(z.enum([
+				"error",
+				"warn",
+				"off"
+			]).default("error"))
+		},
+		tracing: optional({
+			endpoint: field(z.string(), { env: "FIRST_TREE_HUB_OTEL_ENDPOINT" }),
+			headers: field(z.string().default(""), {
+				env: "FIRST_TREE_HUB_OTEL_HEADERS",
+				secret: true
+			}),
+			exporter: field(z.enum(["otlp-http", "otlp-grpc"]).default("otlp-http")),
+			serviceName: field(z.string().default("first-tree-hub")),
+			environment: field(z.string().default("development"), { env: "FIRST_TREE_HUB_OTEL_ENVIRONMENT" }),
+			sampleRate: field(z.number().min(0).max(1).default(1))
+		})
+	}
 });
 join(DEFAULT_DATA_DIR, "context-tree");
 /**
@@ -4371,7 +4521,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-D9JkMZnU.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-BOISS0DK.mjs").then((n) => n.r);
 		const targetAgentUuid = args.type === "human" ? assistantUuid : primary.uuid;
 		if (!targetAgentUuid) process.stderr.write(`Warning: Cannot bind Feishu bot — no runtime agent available for "${args.id}".\n`);
 		else {
@@ -4512,7 +4662,7 @@ function setNestedByDot(obj, dotPath, value) {
 	if (lastKey !== void 0) current[lastKey] = value;
 }
 //#endregion
-//#region ../server/dist/app-TMhTLXuz.mjs
+//#region ../server/dist/app-DJEePmWL.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -5275,6 +5425,7 @@ async function deleteAdapterConfig(db, id) {
 	const [row] = await db.delete(adapterConfigs).where(eq(adapterConfigs.id, id)).returning();
 	if (!row) throw new NotFoundError(`Adapter config "${id}" not found`);
 }
+const log$4 = createLogger("AdminAdapters");
 function parseId(raw) {
 	const id = Number(raw);
 	if (!Number.isInteger(id) || id <= 0) throw new BadRequestError(`Invalid adapter ID: "${raw}"`);
@@ -5293,7 +5444,7 @@ async function adminAdapterRoutes(app) {
 		const scope = memberScope(request);
 		await assertCanManage(app.db, scope, body.agentId);
 		const config = await createAdapterConfig(app.db, body, app.config.secrets.encryptionKey);
-		app.adapterManager.reload().catch((err) => app.log.error(err, "Adapter reload failed after create"));
+		app.adapterManager.reload().catch((err) => log$4.error({ err }, "adapter reload failed after create"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return reply.status(201).send({
 			...config,
@@ -5317,7 +5468,7 @@ async function adminAdapterRoutes(app) {
 		const existing = await getAdapterConfig(app.db, id);
 		await assertCanManage(app.db, scope, existing.agentId);
 		const config = await updateAdapterConfig(app.db, id, body, app.config.secrets.encryptionKey);
-		app.adapterManager.reload().catch((err) => app.log.error(err, "Adapter reload failed after update"));
+		app.adapterManager.reload().catch((err) => log$4.error({ err }, "adapter reload failed after update"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return {
 			...config,
@@ -5331,7 +5482,7 @@ async function adminAdapterRoutes(app) {
 		const existing = await getAdapterConfig(app.db, id);
 		await assertCanManage(app.db, scope, existing.agentId);
 		await deleteAdapterConfig(app.db, id);
-		app.adapterManager.reload().catch((err) => app.log.error(err, "Adapter reload failed after delete"));
+		app.adapterManager.reload().catch((err) => log$4.error({ err }, "adapter reload failed after delete"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return reply.status(204).send();
 	});
@@ -6310,6 +6461,13 @@ const inboxEntries = pgTable("inbox_entries", {
 	ackedAt: timestamp("acked_at", { withTimezone: true })
 }, (table) => [unique("uq_inbox_delivery").on(table.inboxId, table.messageId, table.chatId), index("idx_inbox_pending").on(table.inboxId, table.createdAt)]);
 async function sendMessage(db, chatId, senderId, data) {
+	return withSpan("inbox.enqueue", messageAttrs({
+		chatId,
+		senderAgentId: senderId,
+		source: data.source ?? void 0
+	}), () => sendMessageInner(db, chatId, senderId, data));
+}
+async function sendMessageInner(db, chatId, senderId, data) {
 	return db.transaction(async (tx) => {
 		const messageId = randomUUID();
 		const [msg] = await tx.insert(messages).values({
@@ -8315,7 +8473,11 @@ function adminWsRoutes(notifier, jwtSecret) {
 		});
 	});
 	return async (app) => {
-		app.get("/admin", { websocket: true }, async (socket, request) => {
+		app.get("/admin", {
+			websocket: true,
+			config: { otel: false }
+		}, async (socket, request) => {
+			startWsConnectionSpan(socket, { remoteIp: request.ip });
 			const token = request.query.token;
 			if (!token) {
 				socket.send(JSON.stringify({
@@ -8323,6 +8485,7 @@ function adminWsRoutes(notifier, jwtSecret) {
 					message: "Missing token query parameter"
 				}));
 				socket.close(4001, "Missing token");
+				endWsConnectionSpan(socket, 4001);
 				return;
 			}
 			let organizationId;
@@ -8335,6 +8498,7 @@ function adminWsRoutes(notifier, jwtSecret) {
 						message: "Invalid token type"
 					}));
 					socket.close(4001, "Invalid token");
+					endWsConnectionSpan(socket, 4001);
 					return;
 				}
 				organizationId = payload.organizationId;
@@ -8345,8 +8509,13 @@ function adminWsRoutes(notifier, jwtSecret) {
 					message: "Invalid or expired token"
 				}));
 				socket.close(4001, "Auth failed");
+				endWsConnectionSpan(socket, 4001);
 				return;
 			}
+			setWsConnectionAttrs(socket, {
+				organizationId,
+				memberId
+			});
 			const visibleAgentIds = await loadVisibleAgentIds(app.db, organizationId, memberId);
 			adminSockets.set(socket, {
 				organizationId,
@@ -8354,8 +8523,9 @@ function adminWsRoutes(notifier, jwtSecret) {
 				visibleAgentIds
 			});
 			socket.send(JSON.stringify({ type: "admin:connected" }));
-			socket.on("close", () => {
+			socket.on("close", (code) => {
 				adminSockets.delete(socket);
+				endWsConnectionSpan(socket, code);
 			});
 		});
 	};
@@ -8430,6 +8600,7 @@ async function agentConfigRoutes(app) {
 		return await app.configService.getDecrypted(identity.uuid);
 	});
 }
+const log$3 = createLogger("AgentFeishuBot");
 async function agentFeishuBotRoutes(app) {
 	/**
 	* PUT /agent/me/feishu-bot
@@ -8457,7 +8628,7 @@ async function agentFeishuBotRoutes(app) {
 			},
 			status: "active"
 		}, app.config.secrets.encryptionKey);
-		app.adapterManager.reload().catch((err) => app.log.error(err, "Adapter reload failed after self-service bind"));
+		app.adapterManager.reload().catch((err) => log$3.error({ err }, "adapter reload failed after self-service bind"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return reply.status(current ? 200 : 201).send({
 			...config,
@@ -8474,7 +8645,7 @@ async function agentFeishuBotRoutes(app) {
 		const current = (await listAdapterConfigs(app.db)).find((c) => c.agentId === identity.uuid && c.platform === "feishu");
 		if (!current) return reply.status(204).send();
 		await deleteAdapterConfig(app.db, current.id);
-		app.adapterManager.reload().catch((err) => app.log.error(err, "Adapter reload failed after self-service unbind"));
+		app.adapterManager.reload().catch((err) => log$3.error({ err }, "adapter reload failed after self-service unbind"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return reply.status(204).send();
 	});
@@ -8561,6 +8732,12 @@ async function resolveAgentId(db, source) {
 const DEFAULT_INBOX_TIMEOUT_SECONDS = 300;
 const DEFAULT_MAX_RETRY_COUNT = 3;
 async function pollInbox(db, inboxId, limit) {
+	return withSpan("inbox.deliver", {
+		"inbox.id": inboxId,
+		"inbox.poll.limit": limit
+	}, () => pollInboxInner(db, inboxId, limit));
+}
+async function pollInboxInner(db, inboxId, limit) {
 	return await db.transaction(async (tx) => {
 		const claimed = await tx.execute(sql`
       UPDATE inbox_entries
@@ -8615,12 +8792,17 @@ async function pollInbox(db, inboxId, limit) {
 	});
 }
 async function ackEntry$2(db, entryId, inboxId) {
-	const [entry] = await db.update(inboxEntries).set({
-		status: "acked",
-		ackedAt: /* @__PURE__ */ new Date()
-	}).where(and(eq(inboxEntries.id, entryId), eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.status, "delivered"))).returning();
-	if (!entry) throw new NotFoundError("Inbox entry not found or not in delivered status");
-	return entry;
+	return withSpan("inbox.ack", {
+		[FIRST_TREE_HUB_ATTR.INBOX_ENTRY_ID]: String(entryId),
+		"inbox.id": inboxId
+	}, async () => {
+		const [entry] = await db.update(inboxEntries).set({
+			status: "acked",
+			ackedAt: /* @__PURE__ */ new Date()
+		}).where(and(eq(inboxEntries.id, entryId), eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.status, "delivered"))).returning();
+		if (!entry) throw new NotFoundError("Inbox entry not found or not in delivered status");
+		return entry;
+	});
 }
 async function renewEntry(db, entryId, inboxId) {
 	const [entry] = await db.update(inboxEntries).set({ deliveredAt: /* @__PURE__ */ new Date() }).where(and(eq(inboxEntries.id, entryId), eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.status, "delivered"))).returning();
@@ -8683,6 +8865,7 @@ async function agentMeRoutes(app) {
 		};
 	});
 }
+const log$2 = createLogger("AgentMessages");
 const editMessageSchema = z.object({
 	format: z.string().optional(),
 	content: z.unknown()
@@ -8704,10 +8887,10 @@ async function agentMessageRoutes(app) {
 		await assertParticipant(app.db, request.params.chatId, identity.uuid);
 		const body = editMessageSchema.parse(request.body);
 		const msg = await editMessage(app.db, request.params.chatId, request.params.messageId, identity.uuid, body);
-		app.adapterManager.editOutboundMessage(msg.id, msg.format, msg.content).catch((err) => app.log.error({
+		app.adapterManager.editOutboundMessage(msg.id, msg.format, msg.content).catch((err) => log$2.error({
 			err,
 			messageId: msg.id
-		}, "Failed to edit outbound message"));
+		}, "failed to edit outbound message"));
 		return {
 			...msg,
 			createdAt: msg.createdAt.toISOString()
@@ -8866,7 +9049,11 @@ function sendRejected(socket, ref, reason) {
 function clientWsRoutes(notifier, instanceId) {
 	return async (app) => {
 		const jwtSecretBytes = new TextEncoder().encode(app.config.secrets.jwtSecret);
-		app.get("/client", { websocket: true }, async (socket) => {
+		app.get("/client", {
+			websocket: true,
+			config: { otel: false }
+		}, async (socket) => {
+			startWsConnectionSpan(socket);
 			let session = null;
 			let clientId = null;
 			let authExpiryTimer = null;
@@ -8965,6 +9152,10 @@ function clientWsRoutes(notifier, instanceId) {
 							organizationId: member.organizationId,
 							role: member.role
 						};
+						setWsConnectionAttrs(socket, {
+							"organization.id": member.organizationId,
+							"member.id": member.id
+						});
 						clearTimeout(authTimeout);
 						scheduleAuthExpiry(claims.exp);
 						socket.send(JSON.stringify({ type: "auth:ok" }));
@@ -8978,223 +9169,228 @@ function clientWsRoutes(notifier, instanceId) {
 					}
 					return;
 				}
-				try {
-					if (type === "client:register") {
-						const data = clientRegisterSchema.parse(msg);
-						try {
-							await registerClient(app.db, {
-								clientId: data.clientId,
-								userId: session.userId,
-								instanceId,
-								hostname: data.hostname,
-								os: data.os,
-								sdkVersion: data.sdkVersion
-							});
-						} catch (err) {
-							const message = err instanceof Error ? err.message : "client register failed";
+				await withWsMessageSpan(socket, type, ref !== void 0 ? { "ws.message.ref": String(ref) } : {}, async () => {
+					if (!session) return;
+					try {
+						if (type === "client:register") {
+							const data = clientRegisterSchema.parse(msg);
+							try {
+								await registerClient(app.db, {
+									clientId: data.clientId,
+									userId: session.userId,
+									instanceId,
+									hostname: data.hostname,
+									os: data.os,
+									sdkVersion: data.sdkVersion
+								});
+							} catch (err) {
+								const message = err instanceof Error ? err.message : "client register failed";
+								socket.send(JSON.stringify({
+									type: "client:register:rejected",
+									message
+								}));
+								socket.close(4403, "client register rejected");
+								return;
+							}
+							clientId = data.clientId;
+							setWsConnectionAttrs(socket, { "client.id": data.clientId });
+							setClientConnection(data.clientId, socket);
 							socket.send(JSON.stringify({
-								type: "client:register:rejected",
-								message
+								type: "client:registered",
+								clientId: data.clientId
 							}));
-							socket.close(4403, "client register rejected");
-							return;
-						}
-						clientId = data.clientId;
-						setClientConnection(data.clientId, socket);
-						socket.send(JSON.stringify({
-							type: "client:registered",
-							clientId: data.clientId
-						}));
-						try {
-							const pinned = await listActiveAgentsPinnedToClient(app.db, data.clientId);
-							for (const agent of pinned) {
-								const parsed = agentPinnedMessageSchema$1.safeParse({
-									type: "agent:pinned",
-									agentId: agent.uuid,
-									name: agent.name,
-									displayName: agent.displayName,
-									agentType: agent.type
-								});
-								if (!parsed.success) {
-									app.log.warn({
-										err: parsed.error.flatten(),
+							try {
+								const pinned = await listActiveAgentsPinnedToClient(app.db, data.clientId);
+								for (const agent of pinned) {
+									const parsed = agentPinnedMessageSchema$1.safeParse({
+										type: "agent:pinned",
 										agentId: agent.uuid,
-										clientId: data.clientId
-									}, "agent:pinned backfill frame failed schema validation — skipping");
-									continue;
+										name: agent.name,
+										displayName: agent.displayName,
+										agentType: agent.type
+									});
+									if (!parsed.success) {
+										app.log.warn({
+											err: parsed.error.flatten(),
+											agentId: agent.uuid,
+											clientId: data.clientId
+										}, "agent:pinned backfill frame failed schema validation — skipping");
+										continue;
+									}
+									socket.send(JSON.stringify(parsed.data));
 								}
-								socket.send(JSON.stringify(parsed.data));
+							} catch (err) {
+								app.log.error({
+									err,
+									clientId: data.clientId
+								}, "agent:pinned backfill on client:register failed — client may need manual `agent add`");
 							}
-						} catch (err) {
-							app.log.error({
-								err,
-								clientId: data.clientId
-							}, "agent:pinned backfill on client:register failed — client may need manual `agent add`");
-						}
-					} else if (type === "agent:bind") {
-						if (!clientId) {
-							socket.send(JSON.stringify({
-								type: "error",
-								ref,
-								message: "Must register client first"
-							}));
-							return;
-						}
-						const bindRequest = agentBindRequestSchema.parse(msg);
-						const [agent] = await app.db.select({
-							id: agents.uuid,
-							displayName: agents.displayName,
-							type: agents.type,
-							organizationId: agents.organizationId,
-							inboxId: agents.inboxId,
-							status: agents.status,
-							clientId: agents.clientId,
-							clientUserId: clients.userId,
-							managerUserId: members.userId
-						}).from(agents).leftJoin(clients, eq(agents.clientId, clients.id)).leftJoin(members, eq(agents.managerId, members.id)).where(and(eq(agents.uuid, bindRequest.agentId))).limit(1);
-						if (!agent) {
-							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.UNKNOWN_AGENT);
-							return;
-						}
-						if (agent.organizationId !== session.organizationId) {
-							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.WRONG_ORG);
-							return;
-						}
-						if (agent.status !== "active") {
-							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.AGENT_SUSPENDED);
-							return;
-						}
-						if (agent.clientId === null) {
-							if (!agent.managerUserId || agent.managerUserId !== session.userId) {
-								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.NOT_OWNED);
+						} else if (type === "agent:bind") {
+							if (!clientId) {
+								socket.send(JSON.stringify({
+									type: "error",
+									ref,
+									message: "Must register client first"
+								}));
 								return;
 							}
-							if ((await app.db.update(agents).set({
-								clientId,
-								updatedAt: /* @__PURE__ */ new Date()
-							}).where(and(eq(agents.uuid, agent.id), isNull(agents.clientId))).returning({ uuid: agents.uuid })).length === 0) {
+							const bindRequest = agentBindRequestSchema.parse(msg);
+							const [agent] = await app.db.select({
+								id: agents.uuid,
+								displayName: agents.displayName,
+								type: agents.type,
+								organizationId: agents.organizationId,
+								inboxId: agents.inboxId,
+								status: agents.status,
+								clientId: agents.clientId,
+								clientUserId: clients.userId,
+								managerUserId: members.userId
+							}).from(agents).leftJoin(clients, eq(agents.clientId, clients.id)).leftJoin(members, eq(agents.managerId, members.id)).where(and(eq(agents.uuid, bindRequest.agentId))).limit(1);
+							if (!agent) {
+								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.UNKNOWN_AGENT);
+								return;
+							}
+							if (agent.organizationId !== session.organizationId) {
+								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.WRONG_ORG);
+								return;
+							}
+							if (agent.status !== "active") {
+								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.AGENT_SUSPENDED);
+								return;
+							}
+							if (agent.clientId === null) {
+								if (!agent.managerUserId || agent.managerUserId !== session.userId) {
+									sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.NOT_OWNED);
+									return;
+								}
+								if ((await app.db.update(agents).set({
+									clientId,
+									updatedAt: /* @__PURE__ */ new Date()
+								}).where(and(eq(agents.uuid, agent.id), isNull(agents.clientId))).returning({ uuid: agents.uuid })).length === 0) {
+									sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.WRONG_CLIENT);
+									return;
+								}
+							} else if (agent.clientId !== clientId) {
 								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.WRONG_CLIENT);
 								return;
+							} else if (!agent.clientUserId || agent.clientUserId !== session.userId) {
+								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.NOT_OWNED);
+								return;
 							}
-						} else if (agent.clientId !== clientId) {
-							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.WRONG_CLIENT);
-							return;
-						} else if (!agent.clientUserId || agent.clientUserId !== session.userId) {
-							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.NOT_OWNED);
-							return;
-						}
-						await bindAgent(app.db, agent.id, {
-							clientId,
-							instanceId,
-							runtimeType: bindRequest.runtimeType,
-							runtimeVersion: bindRequest.runtimeVersion
-						});
-						bindAgentToClient(clientId, agent.id);
-						boundAgents.set(agent.id, {
-							agentId: agent.id,
-							inboxId: agent.inboxId
-						});
-						notifier.subscribe(agent.inboxId, socket);
-						socket.send(JSON.stringify({
-							type: "agent:bound",
-							ref,
-							agentId: agent.id,
-							displayName: agent.displayName,
-							agentType: agent.type
-						}));
-					} else if (type === "agent:unbind") {
-						const agentId = parsed.data.agentId;
-						if (!agentId || !boundAgents.has(agentId)) {
-							socket.send(JSON.stringify({
-								type: "error",
-								message: "Agent not bound"
-							}));
-							return;
-						}
-						const info = boundAgents.get(agentId);
-						if (info) notifier.unsubscribe(info.inboxId, socket);
-						await unbindAgent(app.db, agentId);
-						unbindAgentFromClient(agentId);
-						boundAgents.delete(agentId);
-						socket.send(JSON.stringify({
-							type: "agent:unbound",
-							agentId
-						}));
-					} else if (type === "session:state") {
-						const agentId = parsed.data.agentId;
-						if (!agentId || !boundAgents.has(agentId)) {
-							socket.send(JSON.stringify({
-								type: "error",
-								message: "Agent not bound"
-							}));
-							return;
-						}
-						const payload = sessionStateMessageSchema.parse(msg);
-						if (payload.state === "evicted") chainSessionOp(agentId, payload.chatId, () => clearEvents(app.db, agentId, payload.chatId).catch(() => {}));
-						await upsertSessionState(app.db, agentId, payload.chatId, payload.state, session.organizationId, notifier);
-					} else if (type === "runtime:state") {
-						const agentId = parsed.data.agentId;
-						if (!agentId || !boundAgents.has(agentId)) {
-							socket.send(JSON.stringify({
-								type: "error",
-								message: "Agent not bound"
-							}));
-							return;
-						}
-						const payload = runtimeStateMessageSchema.parse(msg);
-						await setRuntimeState(app.db, agentId, payload.runtimeState, {
-							organizationId: session.organizationId,
-							notifier
-						});
-						if (payload.runtimeState === "error" && shouldNotify(agentId, "agent_error")) notifyAgentEvent(app.db, agentId, "agent_error", "high", `Agent ${agentId} entered error state`).catch(() => {});
-						else if (payload.runtimeState === "blocked" && shouldNotify(agentId, "agent_blocked")) notifyAgentEvent(app.db, agentId, "agent_blocked", "medium", `Agent ${agentId} is blocked`).catch(() => {});
-					} else if (type === "session:event") {
-						const agentId = parsed.data.agentId;
-						if (!agentId || !boundAgents.has(agentId)) {
+							await bindAgent(app.db, agent.id, {
+								clientId,
+								instanceId,
+								runtimeType: bindRequest.runtimeType,
+								runtimeVersion: bindRequest.runtimeVersion
+							});
+							bindAgentToClient(clientId, agent.id);
+							boundAgents.set(agent.id, {
+								agentId: agent.id,
+								inboxId: agent.inboxId
+							});
+							notifier.subscribe(agent.inboxId, socket);
 							socket.send(JSON.stringify({
-								type: "error",
-								message: "Agent not bound"
+								type: "agent:bound",
+								ref,
+								agentId: agent.id,
+								displayName: agent.displayName,
+								agentType: agent.type
 							}));
-							return;
-						}
-						const payload = sessionEventMessageSchema.parse(msg);
-						chainSessionOp(agentId, payload.chatId, async () => {
-							try {
-								await appendEvent(app.db, agentId, payload.chatId, payload.event);
-							} catch (err) {
+						} else if (type === "agent:unbind") {
+							const agentId = parsed.data.agentId;
+							if (!agentId || !boundAgents.has(agentId)) {
 								socket.send(JSON.stringify({
 									type: "error",
-									message: `Failed to persist session event: ${err instanceof Error ? err.message : String(err)}`
+									message: "Agent not bound"
 								}));
+								return;
 							}
-						});
-					} else if (type === "session:completion") {
-						const agentId = parsed.data.agentId;
-						if (!agentId || !boundAgents.has(agentId)) {
+							const info = boundAgents.get(agentId);
+							if (info) notifier.unsubscribe(info.inboxId, socket);
+							await unbindAgent(app.db, agentId);
+							unbindAgentFromClient(agentId);
+							boundAgents.delete(agentId);
 							socket.send(JSON.stringify({
-								type: "error",
-								message: "Agent not bound"
+								type: "agent:unbound",
+								agentId
 							}));
-							return;
-						}
-						const payload = sessionCompletionMessageSchema.parse(msg);
-						if (shouldNotify(agentId, `session_completed:${payload.chatId}`)) notifyAgentEvent(app.db, agentId, "session_completed", "low", `Agent ${agentId} completed a task`, payload.chatId).catch(() => {});
-					} else if (type === "heartbeat") {
-						if (clientId) {
-							await heartbeatClient(app.db, clientId);
-							await Promise.all([...boundAgents.keys()].map((id) => touchAgent(app.db, id)));
+						} else if (type === "session:state") {
+							const agentId = parsed.data.agentId;
+							if (!agentId || !boundAgents.has(agentId)) {
+								socket.send(JSON.stringify({
+									type: "error",
+									message: "Agent not bound"
+								}));
+								return;
+							}
+							const payload = sessionStateMessageSchema.parse(msg);
+							if (payload.state === "evicted") chainSessionOp(agentId, payload.chatId, () => clearEvents(app.db, agentId, payload.chatId).catch(() => {}));
+							await upsertSessionState(app.db, agentId, payload.chatId, payload.state, session.organizationId, notifier);
+						} else if (type === "runtime:state") {
+							const agentId = parsed.data.agentId;
+							if (!agentId || !boundAgents.has(agentId)) {
+								socket.send(JSON.stringify({
+									type: "error",
+									message: "Agent not bound"
+								}));
+								return;
+							}
+							const payload = runtimeStateMessageSchema.parse(msg);
+							await setRuntimeState(app.db, agentId, payload.runtimeState, {
+								organizationId: session.organizationId,
+								notifier
+							});
+							if (payload.runtimeState === "error" && shouldNotify(agentId, "agent_error")) notifyAgentEvent(app.db, agentId, "agent_error", "high", `Agent ${agentId} entered error state`).catch(() => {});
+							else if (payload.runtimeState === "blocked" && shouldNotify(agentId, "agent_blocked")) notifyAgentEvent(app.db, agentId, "agent_blocked", "medium", `Agent ${agentId} is blocked`).catch(() => {});
+						} else if (type === "session:event") {
+							const agentId = parsed.data.agentId;
+							if (!agentId || !boundAgents.has(agentId)) {
+								socket.send(JSON.stringify({
+									type: "error",
+									message: "Agent not bound"
+								}));
+								return;
+							}
+							const payload = sessionEventMessageSchema.parse(msg);
+							chainSessionOp(agentId, payload.chatId, async () => {
+								try {
+									await appendEvent(app.db, agentId, payload.chatId, payload.event);
+								} catch (err) {
+									socket.send(JSON.stringify({
+										type: "error",
+										message: `Failed to persist session event: ${err instanceof Error ? err.message : String(err)}`
+									}));
+								}
+							});
+						} else if (type === "session:completion") {
+							const agentId = parsed.data.agentId;
+							if (!agentId || !boundAgents.has(agentId)) {
+								socket.send(JSON.stringify({
+									type: "error",
+									message: "Agent not bound"
+								}));
+								return;
+							}
+							const payload = sessionCompletionMessageSchema.parse(msg);
+							if (shouldNotify(agentId, `session_completed:${payload.chatId}`)) notifyAgentEvent(app.db, agentId, "session_completed", "low", `Agent ${agentId} completed a task`, payload.chatId).catch(() => {});
+						} else if (type === "heartbeat") {
+							if (clientId) {
+								await heartbeatClient(app.db, clientId);
+								await Promise.all([...boundAgents.keys()].map((id) => touchAgent(app.db, id)));
+							}
+							socket.send(JSON.stringify({ type: "heartbeat:ack" }));
 						}
-						socket.send(JSON.stringify({ type: "heartbeat:ack" }));
+					} catch (err) {
+						const message = err instanceof Error ? err.message : "Internal error";
+						socket.send(JSON.stringify({
+							type: "error",
+							message
+						}));
 					}
-				} catch (err) {
-					const message = err instanceof Error ? err.message : "Internal error";
-					socket.send(JSON.stringify({
-						type: "error",
-						message
-					}));
-				}
+				});
 			});
-			socket.on("close", async () => {
+			socket.on("close", async (closeCode) => {
+				endWsConnectionSpan(socket, closeCode);
 				clearTimeout(authTimeout);
 				if (authExpiryTimer) clearTimeout(authExpiryTimer);
 				for (const [agentId, info] of boundAgents) {
@@ -9601,6 +9797,7 @@ async function memberRoutes(app) {
 		return reply.status(204).send();
 	});
 }
+const log$1 = createLogger("GithubWebhook");
 const GITHUB_ADAPTER_ID = "github-adapter";
 function verifySignature(secret, rawBody, signatureHeader) {
 	const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
@@ -9687,7 +9884,10 @@ async function routeMentionDelegations(app, mentionedNames, ctx) {
 			status: agents.status
 		}).from(agents).where(eq(agents.uuid, agent.delegateMention)).limit(1);
 		if (!target || target.status !== "active") {
-			app.log.warn(`delegate_mention target "${agent.delegateMention}" for "${agent.name}" is not active, skipping`);
+			log$1.warn({
+				targetAgent: agent.delegateMention,
+				sourceAgent: agent.name
+			}, "delegate_mention target not active, skipping");
 			continue;
 		}
 		try {
@@ -9713,7 +9913,11 @@ async function routeMentionDelegations(app, mentionedNames, ctx) {
 			notifyRecipients(app.notifier, recipients, msg.id);
 			routed++;
 		} catch (err) {
-			app.log.error(err, `Failed to route mention delegation from "${agent.name}" to "${agent.delegateMention}"`);
+			log$1.error({
+				err,
+				sourceAgent: agent.name,
+				targetAgent: agent.delegateMention
+			}, "failed to route mention delegation");
 		}
 	}
 	return routed;
@@ -9974,7 +10178,10 @@ async function handleIssuesEvent(app, eventType, payload, reply) {
 	});
 	const [senderId, targetAgentId] = await Promise.all([ensureGitHubAdapterAgent(app.db), findTargetAgent(app.db, data.repository.full_name)]);
 	if (!targetAgentId) {
-		app.log.warn(`No target agent found for GitHub issue event on ${data.repository.full_name}`);
+		log$1.warn({
+			repo: data.repository.full_name,
+			event: "issue"
+		}, "no target agent found for GitHub event");
 		return reply.status(200).send({
 			ok: true,
 			event: "issues",
@@ -10026,7 +10233,10 @@ async function handleIssueCommentEvent(app, eventType, payload, reply) {
 	});
 	const [senderId, targetAgentId] = await Promise.all([ensureGitHubAdapterAgent(app.db), findTargetAgent(app.db, data.repository.full_name)]);
 	if (!targetAgentId) {
-		app.log.warn(`No target agent found for GitHub issue_comment event on ${data.repository.full_name}`);
+		log$1.warn({
+			repo: data.repository.full_name,
+			event: "issue_comment"
+		}, "no target agent found for GitHub event");
 		return reply.status(200).send({
 			ok: true,
 			event: "issue_comment",
@@ -10202,7 +10412,11 @@ function createAdapterManager(db, encryptionKey, log, notifier) {
 			const bot = bots.get(appId);
 			if (!bot) return;
 			try {
-				await processInboundMessage(db, event, bot, log, notifier);
+				await withSpan("adapter.inbound feishu", adapterAttrs({
+					platform: "feishu",
+					externalChatId: event.externalChannelId,
+					agentId: bot.agentId
+				}), () => processInboundMessage(db, event, bot, log, notifier));
 				bot.lastActiveAt = /* @__PURE__ */ new Date();
 			} catch (err) {
 				await unclaimEvent(db, event.eventId, "feishu");
@@ -10290,15 +10504,17 @@ function createAdapterManager(db, encryptionKey, log, notifier) {
 				sent: 0,
 				errors: 0
 			};
-			try {
-				return await processFeishuOutbound(db, findBotByAgentId, log);
-			} catch (err) {
-				log.error({ err }, "Feishu outbound processing error");
-				return {
-					sent: 0,
-					errors: 1
-				};
-			}
+			return withSpan("adapter.outbound feishu", adapterAttrs({ platform: "feishu" }), async () => {
+				try {
+					return await processFeishuOutbound(db, findBotByAgentId, log);
+				} catch (err) {
+					log.error({ err }, "Feishu outbound processing error");
+					return {
+						sent: 0,
+						errors: 1
+					};
+				}
+			});
 		},
 		async editOutboundMessage(messageId, format, content) {
 			const ref = await findExternalMessageByInternalId(db, "feishu", messageId);
@@ -10648,6 +10864,7 @@ function formatForFeishu(format, content) {
 		content: JSON.stringify({ text })
 	};
 }
+const log = createLogger("BackgroundTasks");
 function createBackgroundTasks(app, instanceId, adapterManager, kaelRuntime) {
 	let inboxTimer = null;
 	let heartbeatTimer = null;
@@ -10663,7 +10880,7 @@ function createBackgroundTasks(app, instanceId, adapterManager, kaelRuntime) {
 					const maxRetries = configs.max_retry_count ?? 3;
 					await resetTimedOutEntries(app.db, timeoutSeconds, maxRetries);
 				} catch (err) {
-					app.log.error(err, "Failed to reset timed-out inbox entries");
+					log.error({ err }, "failed to reset timed-out inbox entries");
 				}
 			}, 6e4);
 			heartbeatTimer = setInterval(async () => {
@@ -10674,37 +10891,40 @@ function createBackgroundTasks(app, instanceId, adapterManager, kaelRuntime) {
 					await cleanupStaleClients(app.db, staleSeconds);
 					const staleAgents = await markStaleAgents(app.db, staleSeconds);
 					if (staleAgents.length > 0) {
-						app.log.info(`Marked ${staleAgents.length} agent(s) as stale: ${staleAgents.join(", ")}`);
+						log.info({
+							count: staleAgents.length,
+							agentIds: staleAgents
+						}, "marked agents as stale");
 						for (const agentId of staleAgents) notifyAgentEvent(app.db, agentId, "agent_stale", "medium", `Agent ${agentId} is unresponsive`).catch(() => {});
 					}
 				} catch (err) {
-					app.log.error(err, "Failed to heartbeat / cleanup presence");
+					log.error({ err }, "failed to heartbeat / cleanup presence");
 				}
 			}, 3e4);
 			adapterOutboundTimer = setInterval(async () => {
 				try {
 					await adapterManager.processOutbound();
 				} catch (err) {
-					app.log.error(err, "Adapter outbound processing failed");
+					log.error({ err }, "adapter outbound processing failed");
 				}
 			}, 5e3);
 			if (kaelRuntime) kaelOutboundTimer = setInterval(async () => {
 				try {
 					await kaelRuntime.processOutbound();
 				} catch (err) {
-					app.log.error(err, "Kael outbound processing failed");
+					log.error({ err }, "kael outbound processing failed");
 				}
 			}, 5e3);
 			sessionCleanupTimer = setInterval(async () => {
 				try {
 					const deleted = await cleanupStaleSessions(app.db);
-					if (deleted > 0) app.log.info(`Cleaned up ${deleted} stale session(s)`);
+					if (deleted > 0) log.info({ count: deleted }, "cleaned up stale sessions");
 				} catch (err) {
-					app.log.error(err, "Failed to clean up stale sessions");
+					log.error({ err }, "failed to clean up stale sessions");
 				}
 			}, 36e5);
 			heartbeatInstance(app.db, instanceId).catch((err) => {
-				app.log.error(err, "Failed initial heartbeat");
+				log.error({ err }, "failed initial heartbeat");
 			});
 		},
 		stop() {
@@ -11064,11 +11284,15 @@ function createKaelRuntime(db, encryptionKey, kaelEndpoint, kaelApiKey, serverUr
 				sent: 0,
 				errors: 0
 			};
-			let sent = 0;
-			let errorCount = 0;
-			try {
-				const agentIds = [...agentConfigs.keys()];
-				const claimed = await db.execute(sql`
+			return withSpan("kael.forward", {
+				"kael.endpoint": kaelEndpoint,
+				"kael.agent_count": agentConfigs.size
+			}, async () => {
+				let sent = 0;
+				let errorCount = 0;
+				try {
+					const agentIds = [...agentConfigs.keys()];
+					const claimed = await db.execute(sql`
           UPDATE inbox_entries
           SET status = 'delivered', delivered_at = NOW()
           WHERE id IN (
@@ -11084,75 +11308,76 @@ function createKaelRuntime(db, encryptionKey, kaelEndpoint, kaelApiKey, serverUr
           )
           RETURNING id, inbox_id, message_id, chat_id
         `);
-				for (const entry of claimed) try {
-					const [msg] = await db.select().from(messages).where(eq(messages.id, entry.message_id)).limit(1);
-					if (!msg) {
-						await ackEntry(db, entry.id);
-						continue;
-					}
-					const config = inboxToConfig.get(entry.inbox_id);
-					if (!config) {
+					for (const entry of claimed) try {
+						const [msg] = await db.select().from(messages).where(eq(messages.id, entry.message_id)).limit(1);
+						if (!msg) {
+							await ackEntry(db, entry.id);
+							continue;
+						}
+						const config = inboxToConfig.get(entry.inbox_id);
+						if (!config) {
+							await ackEntry(db, entry.id);
+							continue;
+						}
+						const messageContent = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+						const payload = {
+							hub_chat_id: entry.chat_id ?? msg.chatId,
+							hub_agent_id: config.agentId,
+							hub_server_url: serverUrl,
+							hub_agent_token: config.agentToken,
+							user_id: config.kaelUserId,
+							project_id: config.kaelProjectId,
+							message: messageContent,
+							sender_id: msg.senderId,
+							format: msg.format
+						};
+						if (agentsMd) payload.agents_md = agentsMd;
+						const response = await fetch(`${kaelEndpoint}/api/v1/hub/messages`, {
+							method: "POST",
+							headers: {
+								"Content-Type": "application/json",
+								...kaelApiKey ? { "X-Internal-API-Key": kaelApiKey } : {}
+							},
+							body: JSON.stringify(payload)
+						});
+						if (!response.ok) {
+							const body = await response.text().catch(() => "");
+							log.error({
+								entryId: entry.id,
+								status: response.status,
+								body
+							}, "Kael API rejected outbound message");
+							await nackEntry(db, entry.id);
+							errorCount++;
+							continue;
+						}
 						await ackEntry(db, entry.id);
-						continue;
-					}
-					const messageContent = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
-					const payload = {
-						hub_chat_id: entry.chat_id ?? msg.chatId,
-						hub_agent_id: config.agentId,
-						hub_server_url: serverUrl,
-						hub_agent_token: config.agentToken,
-						user_id: config.kaelUserId,
-						project_id: config.kaelProjectId,
-						message: messageContent,
-						sender_id: msg.senderId,
-						format: msg.format
-					};
-					if (agentsMd) payload.agents_md = agentsMd;
-					const response = await fetch(`${kaelEndpoint}/api/v1/hub/messages`, {
-						method: "POST",
-						headers: {
-							"Content-Type": "application/json",
-							...kaelApiKey ? { "X-Internal-API-Key": kaelApiKey } : {}
-						},
-						body: JSON.stringify(payload)
-					});
-					if (!response.ok) {
-						const body = await response.text().catch(() => "");
+						sent++;
+					} catch (err) {
 						log.error({
 							entryId: entry.id,
-							status: response.status,
-							body
-						}, "Kael API rejected outbound message");
-						await nackEntry(db, entry.id);
+							err
+						}, "Failed to send outbound Kael message");
+						await nackEntry(db, entry.id).catch((nackErr) => {
+							log.error({
+								entryId: entry.id,
+								err: nackErr
+							}, "Failed to NACK entry");
+						});
 						errorCount++;
-						continue;
 					}
-					await ackEntry(db, entry.id);
-					sent++;
 				} catch (err) {
-					log.error({
-						entryId: entry.id,
-						err
-					}, "Failed to send outbound Kael message");
-					await nackEntry(db, entry.id).catch((nackErr) => {
-						log.error({
-							entryId: entry.id,
-							err: nackErr
-						}, "Failed to NACK entry");
-					});
-					errorCount++;
+					log.error({ err }, "Kael outbound processing error");
+					return {
+						sent: 0,
+						errors: 1
+					};
 				}
-			} catch (err) {
-				log.error({ err }, "Kael outbound processing error");
 				return {
-					sent: 0,
-					errors: 1
+					sent,
+					errors: errorCount
 				};
-			}
-			return {
-				sent,
-				errors: errorCount
-			};
+			});
 		},
 		shutdown() {
 			aborted = true;
@@ -11262,7 +11487,15 @@ function createPulseAggregator(options) {
 	};
 }
 async function buildApp(config) {
-	const app = Fastify({ logger: config.logger ?? true });
+	applyLoggerConfig({
+		level: config.observability.logging.level,
+		format: config.observability.logging.format,
+		bridgeToSpanLevel: config.observability.logging.bridgeToSpanLevel
+	});
+	const app = Fastify({ loggerInstance: rootLogger$1 });
+	const otelPlugin = getFastifyOtelPlugin();
+	if (otelPlugin) await app.register(otelPlugin);
+	await app.register(observabilityPlugin);
 	const db = connectDatabase(config.database.url);
 	app.decorate("db", db);
 	app.decorate("config", config);
@@ -11282,14 +11515,23 @@ async function buildApp(config) {
 	const memberAuth = memberAuthHook(db, config.secrets.jwtSecret);
 	const adminOnly = requireAdminRoleHook();
 	const agentSelector = agentSelectorHook(db);
-	app.setErrorHandler((error, _request, reply) => {
-		if (error instanceof AppError) return reply.status(error.statusCode).send({ error: error.message });
+	app.setErrorHandler((error, request, reply) => {
+		const traceId = currentTraceId();
+		const traceField = traceId ? { traceId } : {};
+		if (error instanceof AppError) return reply.status(error.statusCode).send({
+			error: error.message,
+			...traceField
+		});
 		if (error instanceof ZodError) return reply.status(400).send({
 			error: "Validation error",
-			details: error.issues
+			details: error.issues,
+			...traceField
+		});
+		request.log.error({ err: error }, "unhandled request error");
+		return reply.status(500).send({
+			error: "Internal server error",
+			...traceField
 		});
-		app.log.error(error);
-		return reply.status(500).send({ error: "Internal server error" });
 	});
 	await app.register(healthzRoutes);
 	await app.register(async (api) => {
@@ -11423,10 +11665,11 @@ async function buildApp(config) {
 		notifier,
 		broadcast: broadcastToAdmins
 	});
+	const hotReloadLog = createLogger("HotReload");
 	notifier.onConfigChange((configType) => {
 		if (configType === "adapter_configs") {
-			adapterManager.reload().catch((err) => app.log.error(err, "Adapter hot-reload failed (PG NOTIFY)"));
-			kaelRuntime?.reload().catch((err) => app.log.error(err, "Kael hot-reload failed (PG NOTIFY)"));
+			adapterManager.reload().catch((err) => hotReloadLog.error({ err }, "adapter hot-reload failed (PG NOTIFY)"));
+			kaelRuntime?.reload().catch((err) => hotReloadLog.error({ err }, "kael hot-reload failed (PG NOTIFY)"));
 		}
 	});
 	app.addHook("onReady", async () => {
@@ -11500,13 +11743,18 @@ async function startServer(options) {
 	const config = {
 		...serverConfig,
 		webDistPath: webDistPath ?? void 0,
-		instanceId: `srv_${randomUUID().slice(0, 8)}`,
-		logger: true
+		instanceId: `srv_${randomUUID().slice(0, 8)}`
 	};
+	const { initTelemetry, shutdownTelemetry } = await import("./observability-Xi-sEZI7.mjs");
+	await initTelemetry(serverConfig.observability.tracing, config.instanceId);
 	const app = await buildApp(config);
 	const shutdown = async () => {
 		process.stderr.write("\n  Shutting down...\n");
-		await app.close();
+		try {
+			await app.close();
+		} finally {
+			await shutdownTelemetry();
+		}
 		process.exit(0);
 	};
 	process.on("SIGINT", () => void shutdown());
@@ -11548,6 +11796,32 @@ function resolveWebDist() {
 }
 //#endregion
 //#region src/core/service-install.ts
+/**
+* Run a subprocess capturing stderr so failures surface a meaningful error
+* instead of Node's opaque "Command failed". Used for launchctl/systemctl —
+* anywhere the stderr message is diagnostically crucial.
+*/
+function runCapture(program, args, timeoutMs) {
+	const res = spawnSync(program, args, {
+		encoding: "utf-8",
+		timeout: timeoutMs,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (res.status === 0) return { ok: true };
+	return {
+		ok: false,
+		stderr: (res.stderr ?? "").trim(),
+		code: res.status
+	};
+}
+function sleepSync(ms) {
+	const shared = new Int32Array(new SharedArrayBuffer(4));
+	Atomics.wait(shared, 0, 0, ms);
+}
 const LAUNCHD_LABEL = "dev.first-tree-hub.client";
 const SYSTEMD_UNIT = "first-tree-hub-client.service";
 const LOG_DIR = join(DEFAULT_HOME_DIR$1, "logs");
@@ -11655,30 +11929,56 @@ function launchctlDomainTarget() {
 }
 function launchdState() {
 	if (!existsSync(launchdPlistPath())) return { state: "not-installed" };
-	try {
-		const out = execFileSync("launchctl", ["print", `${launchctlDomainTarget()}/${LAUNCHD_LABEL}`], {
-			encoding: "utf-8",
-			timeout: 5e3
-		});
-		const stateLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("state ="));
-		const pidLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("pid ="));
-		if (stateLine?.includes("running")) {
-			const pid = pidLine?.split("=")[1]?.trim();
-			return {
-				state: "active",
-				detail: pid ? `pid ${pid}` : "running"
-			};
-		}
-		return {
-			state: "inactive",
-			detail: stateLine?.trim() ?? "loaded"
-		};
-	} catch {
+	const res = spawnSync("launchctl", ["print", `${launchctlDomainTarget()}/${LAUNCHD_LABEL}`], {
+		encoding: "utf-8",
+		timeout: 5e3,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (res.status !== 0) return {
+		state: "inactive",
+		detail: "plist present but not loaded"
+	};
+	const out = res.stdout ?? "";
+	const stateLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("state ="));
+	const pidLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("pid ="));
+	if (stateLine?.includes("running")) {
+		const pid = pidLine?.split("=")[1]?.trim();
 		return {
-			state: "inactive",
-			detail: "plist present but not loaded"
+			state: "active",
+			detail: pid ? `pid ${pid}` : "running"
 		};
 	}
+	return {
+		state: "inactive",
+		detail: stateLine?.trim() ?? "loaded"
+	};
+}
+/**
+* Poll `launchctl print` until the label disappears, confirming launchd has
+* finished the async eviction kicked off by `bootout`. Required because
+* `bootout` returns before the actual unload completes when the service has
+* active WebSocket connections — a follow-up `bootstrap` against a still-
+* registered label fails with `Bootstrap failed: 5: Input/output error`.
+*/
+function waitForLabelEvicted(target, label, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (spawnSync("launchctl", ["print", `${target}/${label}`], {
+			encoding: "utf-8",
+			timeout: 2e3,
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			]
+		}).status !== 0) return true;
+		sleepSync(200);
+	}
+	return false;
 }
 function installLaunchd() {
 	const invocation = resolveCliInvocation();
@@ -11687,24 +11987,28 @@ function installLaunchd() {
 	mkdirSync(dirname(plistPath), { recursive: true });
 	writeFileSync(plistPath, renderPlist(invocation), { mode: 420 });
 	const target = launchctlDomainTarget();
-	try {
-		execFileSync("launchctl", ["bootout", `${target}/${LAUNCHD_LABEL}`], {
-			stdio: "ignore",
-			timeout: 5e3
-		});
-	} catch {}
-	execFileSync("launchctl", [
-		"bootstrap",
-		target,
-		plistPath
-	], {
-		stdio: "ignore",
-		timeout: 5e3
-	});
-	execFileSync("launchctl", ["enable", `${target}/${LAUNCHD_LABEL}`], {
-		stdio: "ignore",
-		timeout: 5e3
-	});
+	const bootoutRes = runCapture("launchctl", ["bootout", `${target}/${LAUNCHD_LABEL}`], 15e3);
+	if (!bootoutRes.ok) {
+		if (!/not find|no such|not loaded/i.test(bootoutRes.stderr)) process.stderr.write(`    warning: launchctl bootout: ${bootoutRes.stderr || `exit ${bootoutRes.code ?? "unknown"}`}\n`);
+	}
+	waitForLabelEvicted(target, LAUNCHD_LABEL, 1e4);
+	let lastBootstrapErr = null;
+	for (let attempt = 1; attempt <= 2; attempt++) {
+		const res = runCapture("launchctl", [
+			"bootstrap",
+			target,
+			plistPath
+		], 1e4);
+		if (res.ok) {
+			lastBootstrapErr = null;
+			break;
+		}
+		lastBootstrapErr = res;
+		if (attempt < 2) sleepSync(1e3);
+	}
+	if (lastBootstrapErr) throw new Error(`launchctl bootstrap failed: ${lastBootstrapErr.stderr || `exit ${lastBootstrapErr.code ?? "unknown"}`}\n    Command: launchctl bootstrap ${target} ${plistPath}\n    Recovery: \`launchctl bootout ${target}/${LAUNCHD_LABEL}\` then \`first-tree-hub service install\`.`);
+	const enableRes = runCapture("launchctl", ["enable", `${target}/${LAUNCHD_LABEL}`], 5e3);
+	if (!enableRes.ok) process.stderr.write(`    warning: launchctl enable: ${enableRes.stderr || `exit ${enableRes.code ?? "unknown"}`}\n`);
 	const { state, detail } = launchdState();
 	return {
 		platform: "launchd",
@@ -11717,13 +12021,8 @@ function installLaunchd() {
 }
 function uninstallLaunchd() {
 	const plistPath = launchdPlistPath();
-	const target = launchctlDomainTarget();
-	try {
-		execFileSync("launchctl", ["bootout", `${target}/${LAUNCHD_LABEL}`], {
-			stdio: "ignore",
-			timeout: 5e3
-		});
-	} catch {}
+	const res = runCapture("launchctl", ["bootout", `${launchctlDomainTarget()}/${LAUNCHD_LABEL}`], 15e3);
+	if (!res.ok && !/not find|no such|not loaded/i.test(res.stderr)) process.stderr.write(`    warning: bootout during uninstall: ${res.stderr || `exit ${res.code ?? "unknown"}`}\n`);
 	if (existsSync(plistPath)) rmSync(plistPath);
 	return {
 		platform: "launchd",
@@ -11761,29 +12060,28 @@ function shellQuote(value) {
 }
 function systemdState() {
 	if (!existsSync(systemdUnitPath())) return { state: "not-installed" };
-	try {
-		const out = execFileSync("systemctl", [
-			"--user",
-			"is-active",
-			SYSTEMD_UNIT
-		], {
-			encoding: "utf-8",
-			timeout: 5e3
-		}).trim();
-		if (out === "active") return {
-			state: "active",
-			detail: "running"
-		};
-		return {
-			state: "inactive",
-			detail: out
-		};
-	} catch (err) {
-		return {
-			state: "inactive",
-			detail: (typeof err.stdout === "string" ? (err.stdout ?? "").trim() : "") || "unit present but not active"
-		};
-	}
+	const res = spawnSync("systemctl", [
+		"--user",
+		"is-active",
+		SYSTEMD_UNIT
+	], {
+		encoding: "utf-8",
+		timeout: 5e3,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	const out = (res.stdout ?? "").trim();
+	if (res.status === 0 && out === "active") return {
+		state: "active",
+		detail: "running"
+	};
+	return {
+		state: "inactive",
+		detail: out || "unit present but not active"
+	};
 }
 function installSystemd() {
 	const invocation = resolveCliInvocation();
@@ -11791,19 +12089,15 @@ function installSystemd() {
 	const unitPath = systemdUnitPath();
 	mkdirSync(dirname(unitPath), { recursive: true });
 	writeFileSync(unitPath, renderSystemdUnit(invocation), { mode: 420 });
-	execFileSync("systemctl", ["--user", "daemon-reload"], {
-		stdio: "ignore",
-		timeout: 5e3
-	});
-	execFileSync("systemctl", [
+	const reloadRes = runCapture("systemctl", ["--user", "daemon-reload"], 5e3);
+	if (!reloadRes.ok) throw new Error(`systemctl --user daemon-reload failed: ${reloadRes.stderr || `exit ${reloadRes.code ?? "unknown"}`}`);
+	const enableRes = runCapture("systemctl", [
 		"--user",
 		"enable",
 		"--now",
 		SYSTEMD_UNIT
-	], {
-		stdio: "ignore",
-		timeout: 1e4
-	});
+	], 1e4);
+	if (!enableRes.ok) throw new Error(`systemctl --user enable --now ${SYSTEMD_UNIT} failed: ${enableRes.stderr || `exit ${enableRes.code ?? "unknown"}`}\n    Recovery: \`systemctl --user stop ${SYSTEMD_UNIT}\` then \`first-tree-hub service install\`.`);
 	const { state, detail } = systemdState();
 	return {
 		platform: "systemd",
@@ -11816,24 +12110,16 @@ function installSystemd() {
 }
 function uninstallSystemd() {
 	const unitPath = systemdUnitPath();
-	try {
-		execFileSync("systemctl", [
-			"--user",
-			"disable",
-			"--now",
-			SYSTEMD_UNIT
-		], {
-			stdio: "ignore",
-			timeout: 1e4
-		});
-	} catch {}
+	const disableRes = runCapture("systemctl", [
+		"--user",
+		"disable",
+		"--now",
+		SYSTEMD_UNIT
+	], 1e4);
+	if (!disableRes.ok && !/not found|no such|not loaded/i.test(disableRes.stderr)) process.stderr.write(`    warning: systemctl disable during uninstall: ${disableRes.stderr || `exit ${disableRes.code ?? "unknown"}`}\n`);
 	if (existsSync(unitPath)) rmSync(unitPath);
-	try {
-		execFileSync("systemctl", ["--user", "daemon-reload"], {
-			stdio: "ignore",
-			timeout: 5e3
-		});
-	} catch {}
+	const reloadRes = runCapture("systemctl", ["--user", "daemon-reload"], 5e3);
+	if (!reloadRes.ok) process.stderr.write(`    warning: systemctl daemon-reload during uninstall: ${reloadRes.stderr || `exit ${reloadRes.code ?? "unknown"}`}\n`);
 	return {
 		platform: "systemd",
 		label: SYSTEMD_UNIT,
@@ -11896,4 +12182,4 @@ function uninstallClientService() {
 	return getClientServiceStatus();
 }
 //#endregion
-export { stopPostgres as A, checkServerReachable as C, status as D, blank as E, SdkError as F, SessionRegistry as I, cleanWorkspaces as L, createOwner as M, hasUser as N, ensurePostgres as O, FirstTreeHubSDK as P, checkServerHealth as S, printResults as T, checkClientConfig as _, uninstallClientService as a, checkNodeVersion as b, promptAddAgent as c, loadOnboardState as d, onboardCheck as f, checkAgentConfigs as g, runMigrations as h, resolveCliInvocation as i, ClientRuntime as j, isDockerAvailable as k, promptMissingFields as l, saveOnboardState as m, installClientService as n, startServer as o, onboardCreate as p, isServiceSupported as r, isInteractive as s, getClientServiceStatus as t, formatCheckReport as u, checkDatabase as v, checkWebSocket as w, checkServerConfig as x, checkDocker as y };
+export { stopPostgres as A, checkServerReachable as C, status as D, blank as E, SdkError as F, SessionRegistry as I, cleanWorkspaces as L, createOwner as M, hasUser as N, ensurePostgres as O, FirstTreeHubSDK as P, applyClientLoggerConfig as R, checkServerHealth as S, printResults as T, checkClientConfig as _, uninstallClientService as a, checkNodeVersion as b, promptAddAgent as c, loadOnboardState as d, onboardCheck as f, checkAgentConfigs as g, runMigrations as h, resolveCliInvocation as i, ClientRuntime as j, isDockerAvailable as k, promptMissingFields as l, saveOnboardState as m, installClientService as n, startServer as o, onboardCreate as p, isServiceSupported as r, isInteractive as s, getClientServiceStatus as t, formatCheckReport as u, checkDatabase as v, checkWebSocket as w, checkServerConfig as x, checkDocker as y };