@agent-team-foundation/first-tree-hub 0.9.10 → 0.10.0

package/dist/{core-BWaSYpXv.mjs → core-BgiFGT7Y.mjs}

@@ -1,15 +1,14 @@
 import { m as __toESM } from "./esm-CYu4tXXn.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$1, t as adapterAttrs, u as observabilityPlugin, v as withWsMessageSpan, y as FIRST_TREE_HUB_ATTR } from "./observability-DV_fQKqV-CuLWzBxQ.mjs";
-import { s as formatPrettyEntry$1, t as LOG_LEVELS$1, u as parseLogLevel$1 } from "./logger-core-BTmvdflj-DhdipBkV.mjs";
-import { C as serverConfigSchema, S as resolveConfigReadonly, _ 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, v as migrateLegacyHome, w as setConfigValue } from "./bootstrap-hh_PkTu6.mjs";
-import { $ as sessionStateMessageSchema, A as createMemberSchema, B as loginSchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as extractMentions, G as runtimeStateMessageSchema, H as notificationQuerySchema, I as imageInlineContentSchema, J as sendToAgentSchema, K as selfServiceFeishuBotSchema, L as inboxPollQuerySchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as sessionReconcileRequestSchema, R as isRedactedEnvValue, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as paginationQuerySchema, V as messageSourceSchema$1, W as refreshTokenSchema, X as sessionEventMessageSchema, Y as sessionCompletionMessageSchema, Z as sessionEventSchema$1, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as updateMemberSchema, b as agentBindRequestSchema, c as AGENT_TYPES, ct as updateTaskStatusSchema, d as SYSTEM_CONFIG_DEFAULTS, et as taskListQuerySchema, 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 updateChatSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, lt as wsAuthFrameSchema, m as TASK_STATUSES, nt as updateAgentRuntimeConfigSchema, o as AGENT_SOURCES, ot as updateOrganizationSchema, p as TASK_HEALTH_SIGNALS, q as sendMessageSchema, rt as updateAgentSchema, s as AGENT_STATUSES, st as updateSystemConfigSchema, tt as updateAdapterConfigSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as linkTaskChatSchema } from "./feishu-BJaN64iR.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$1, t as adapterAttrs, u as observabilityPlugin, v as withWsMessageSpan, y as FIRST_TREE_HUB_ATTR } from "./observability-DV_fQKqV-oxfXX6Z2.mjs";
+import { C as serverConfigSchema, S as resolveConfigReadonly, _ 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, v as migrateLegacyHome, w as setConfigValue } from "./bootstrap-CtVqQA8a.mjs";
+import { $ as sessionEventMessageSchema, A as createChatSchema, B as isReservedAgentName$1, C as agentRuntimeConfigPayloadSchema$1, D as createAdapterConfigSchema, E as connectTokenExchangeSchema, F as dryRunAgentRuntimeConfigSchema, G as paginationQuerySchema, H as loginSchema, I as extractMentions, J as scanMentionTokens, K as refreshTokenSchema, L as imageInlineContentSchema, M as createOrganizationSchema, N as createTaskSchema, O as createAdapterMappingSchema, P as delegateFeishuUserSchema, Q as sessionCompletionMessageSchema, R as inboxPollQuerySchema, S as agentPinnedMessageSchema$1, T as clientRegisterSchema, U as messageSourceSchema$1, V as linkTaskChatSchema, W as notificationQuerySchema, X as sendMessageSchema, Y as selfServiceFeishuBotSchema, Z as sendToAgentSchema, _ as WS_AUTH_FRAME_TIMEOUT_MS, a as AGENT_NAME_REGEX$1, at as updateAgentRuntimeConfigSchema, b as adminUpdateTaskSchema, c as AGENT_STATUSES, ct as updateMemberSchema, d as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, dt as updateTaskStatusSchema, et as sessionEventSchema$1, f as SYSTEM_CONFIG_DEFAULTS, ft as wsAuthFrameSchema, g as TASK_TERMINAL_STATUSES, h as TASK_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as updateAdapterConfigSchema, j as createMemberSchema, k as createAgentSchema, l as AGENT_TYPES, lt as updateOrganizationSchema, m as TASK_HEALTH_SIGNALS, nt as sessionStateMessageSchema, o as AGENT_SELECTOR_HEADER$1, ot as updateAgentSchema, p as TASK_CREATOR_TYPES, q as runtimeStateMessageSchema, rt as taskListQuerySchema, s as AGENT_SOURCES, st as updateChatSchema, tt as sessionReconcileRequestSchema, u as AGENT_VISIBILITY, ut as updateSystemConfigSchema, v as addParticipantSchema, w as agentTypeSchema$1, x as agentBindRequestSchema, y as adminCreateTaskSchema, z as isRedactedEnvValue } from "./feishu-DEmwoNn_.mjs";
 import { createRequire } from "node:module";
 import { ZodError, z } from "zod";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { Writable } from "node:stream";
 import { homedir, hostname, platform, tmpdir, userInfo } from "node:os";
 import { EventEmitter } from "node:events";
-import { closeSync, copyFileSync, createReadStream, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, unwatchFile, watch, watchFile, writeFileSync, writeSync } from "node:fs";
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import WebSocket from "ws";
 import { mkdir, writeFile } from "node:fs/promises";
@@ -32,7 +31,6 @@ 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";
-import { createInterface } from "node:readline";
 //#region ../client/dist/observability-B4kO005X.mjs
 var import_pino = /* @__PURE__ */ __toESM(require_pino(), 1);
 /**
@@ -430,10 +428,33 @@ const agentTypeSchema = z.enum([
 const agentVisibilitySchema = z.enum(["private", "organization"]);
 const agentSourceSchema = z.enum(["admin-api", "portal"]);
 z.enum(["active", "suspended"]);
+/**
+* Agent-name rules (see docs/agent-naming-design.md §3.1):
+*   - Lowercase ASCII slug, hyphens + underscores allowed.
+*   - Must start with alphanumeric: `-` / `_` as first char collide with
+*     CLI flag parsing and markdown list syntax.
+*   - 1–64 chars — aligned with `MENTION_REGEX` so any valid name can be
+*     @-mentioned in chat. Older rows created under the previous 1–100
+*     regex are grandfathered; the tight rule only gates new creates.
+*/
+const AGENT_NAME_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const RESERVED_AGENT_NAMES_SET = new Set([
+	"admin",
+	"agent",
+	"first-tree",
+	"hub",
+	"me",
+	"null",
+	"system",
+	"undefined"
+]);
+function isReservedAgentName(name) {
+	return RESERVED_AGENT_NAMES_SET.has(name);
+}
 z.object({
-	name: z.string().min(1).max(100).regex(/^[a-z0-9_-]+$/, "Only lowercase alphanumeric, hyphens, and underscores").optional(),
+	name: z.string().min(1).max(64).regex(AGENT_NAME_REGEX, "Must start with a letter or digit and contain only lowercase letters, digits, hyphens (-), and underscores (_). Max 64 chars.").refine((n) => !isReservedAgentName(n), { message: "That agent name is reserved — pick a different one." }).optional(),
 	type: agentTypeSchema,
-	displayName: z.string().max(200).optional(),
+	displayName: z.string().min(1).max(200).optional(),
 	delegateMention: z.string().max(100).optional(),
 	organizationId: z.string().max(100).optional(),
 	source: agentSourceSchema.optional(),
@@ -444,7 +465,7 @@ z.object({
 });
 z.object({
 	type: agentTypeSchema.optional(),
-	displayName: z.string().max(200).nullable().optional(),
+	displayName: z.string().min(1).max(200).optional(),
 	delegateMention: z.string().max(100).nullable().optional(),
 	visibility: agentVisibilitySchema.optional(),
 	metadata: z.record(z.string(), z.unknown()).optional(),
@@ -456,7 +477,7 @@ z.object({
 	name: z.string().nullable(),
 	organizationId: z.string(),
 	type: agentTypeSchema,
-	displayName: z.string().nullable(),
+	displayName: z.string(),
 	delegateMention: z.string().nullable(),
 	inboxId: z.string(),
 	status: z.string(),
@@ -483,7 +504,7 @@ const agentPinnedMessageSchema = z.object({
 	type: z.literal("agent:pinned"),
 	agentId: z.string(),
 	name: z.string().nullable(),
-	displayName: z.string().nullable(),
+	displayName: z.string(),
 	agentType: agentTypeSchema
 });
 /**
@@ -661,7 +682,7 @@ const chatParticipantSchema = z.object({
 });
 chatParticipantSchema.extend({
 	name: z.string().nullable(),
-	displayName: z.string().nullable(),
+	displayName: z.string(),
 	type: z.string()
 });
 z.object({
@@ -814,6 +835,23 @@ const inReplyToSnapshotSchema = z.object({
 /** Per-chat participation mode exposed to the recipient runtime. */
 const participantModeSchema = z.enum(["full", "mention_only"]);
 /**
+* Lightweight snapshot of an earlier message in the same chat that the
+* recipient missed (because it was `mention_only` + not @mentioned). Server
+* attaches a list of these to the next active delivery in the chat so the
+* agent's prompt carries enough context to reply meaningfully.
+*
+* Smaller than `messageSchema` on purpose — drops fields that don't help the
+* LLM (replyTo envelopes, source) and aren't safe to leak across recipients.
+*/
+const precedingMessageSchema = z.object({
+	id: z.string(),
+	senderId: z.string(),
+	format: z.string(),
+	content: z.unknown(),
+	metadata: z.record(z.string(), z.unknown()).default({}),
+	createdAt: z.string()
+});
+/**
 * Wire format for messages routed FROM the Hub TO a client runtime.
 *
 * Adds `configVersion` so the client can compare against its locally cached
@@ -829,11 +867,17 @@ const participantModeSchema = z.enum(["full", "mention_only"]);
 *
 * `inReplyToSnapshot` is populated when `inReplyTo` resolves to an existing
 * message; runtime uses it to suppress self-reply echo on direct chats.
+*
+* `precedingMessages` is a (possibly empty) list of older messages in the
+* same chat that this recipient did not previously receive (silent inbox
+* context). The runtime renders them as "earlier in chat" before the
+* triggering message — see proposals/group-chat-ux-improvements §1.
 */
 const clientMessageSchema = messageSchema.extend({
 	configVersion: z.number().int().positive(),
 	recipientMode: participantModeSchema.default("full"),
-	inReplyToSnapshot: inReplyToSnapshotSchema.default(null)
+	inReplyToSnapshot: inReplyToSnapshotSchema.default(null),
+	precedingMessages: z.array(precedingMessageSchema).default([])
 });
 z.enum([
 	"pending",
@@ -1875,7 +1919,7 @@ var ClientConnection = class extends EventEmitter {
 				});
 				const agent = {
 					agentId,
-					displayName: msg.displayName ?? null,
+					displayName: msg.displayName ?? agentId,
 					agentType: msg.agentType ?? "personal_assistant",
 					sdk
 				};
@@ -3659,13 +3703,32 @@ function resolveSenderLabel(senderId, participants) {
 * content is serialised to JSON — handlers that want to feed structured
 * content some other way should opt out and format themselves.
 *
+* If the server attached `precedingMessages` (silent group-chat history the
+* recipient missed because it was `mention_only` and not @mentioned), prepend
+* them under an `[Earlier in chat]` block so the LLM sees what came before
+* the @mention that woke this turn — see proposals/group-chat-ux-improvements §1.
+*
 * Async because the participant list may need a server round-trip on first
 * use; subsequent messages in the same session hit the cache.
 */
 async function formatInboundContent(message, participants) {
 	const rawContent = typeof message.content === "string" ? message.content : JSON.stringify(message.content);
-	if (!message.senderId) return rawContent;
-	return `[From: ${resolveSenderLabel(message.senderId, await participants.get())}]\n\n${rawContent}`;
+	const preceding = message.precedingMessages ?? [];
+	let header = "";
+	if (preceding.length > 0) {
+		const ps = await participants.get();
+		const lines = ["[Earlier in chat — context you missed]"];
+		for (const p of preceding) {
+			const label = resolveSenderLabel(p.senderId, ps);
+			const text = typeof p.content === "string" ? p.content : JSON.stringify(p.content);
+			lines.push(`[From: ${label}] ${text}`);
+		}
+		lines.push("", "[Now — message that woke you]");
+		header = `${lines.join("\n")}\n\n`;
+	}
+	if (!message.senderId) return `${header}${rawContent}`;
+	const label = resolveSenderLabel(message.senderId, await participants.get());
+	return `${header}[From: ${label}]\n\n${rawContent}`;
 }
 /**
 * Deduplicator — bounded set of recently seen IDs.
@@ -4295,7 +4358,8 @@ var SessionManager = class {
 			senderId: msg.senderId,
 			format: msg.format,
 			content: msg.content,
-			metadata: msg.metadata
+			metadata: msg.metadata,
+			precedingMessages: msg.precedingMessages ?? []
 		};
 	}
 	loadPersistedSessions() {
@@ -4386,7 +4450,7 @@ var AgentSlot = class {
 		const sdk = (await this.clientConnection.bindAgent(this.config.agentId, this.config.runtimeType ?? this.config.type, this.config.runtimeVersion)).sdk;
 		this.sdk = sdk;
 		const agent = await sdk.register();
-		this.logger.info({ displayName: agent.displayName ?? agent.agentId }, "agent bound");
+		this.logger.info({ displayName: agent.displayName }, "agent bound");
 		if (agent.type === "human") {
 			this.logger.info("server reports type=human — message processing disabled");
 			return agent;
@@ -5373,696 +5437,881 @@ function getContainerPassword() {
 	throw new Error("Cannot determine PostgreSQL password from container");
 }
 //#endregion
-//#region src/core/doctor.ts
-function getServerConfig() {
-	return resolveConfigReadonly({
-		schema: serverConfigSchema,
-		role: "server"
-	});
-}
-function getClientConfig() {
-	return resolveConfigReadonly({
-		schema: clientConfigSchema,
-		role: "client"
+//#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"
+		]
 	});
-}
-function get(obj, dotPath) {
-	const parts = dotPath.split(".");
-	let current = obj;
-	for (const part of parts) {
-		if (current === null || current === void 0 || typeof current !== "object") return void 0;
-		current = current[part];
-	}
-	return current;
-}
-function checkNodeVersion() {
-	const version = process.versions.node;
-	const [major] = version.split(".").map(Number);
-	const ok = major !== void 0 && major >= 22;
+	if (res.status === 0) return { ok: true };
 	return {
-		label: "Node.js",
-		ok,
-		detail: ok ? `v${version}` : `v${version} (requires >= 22.16)`
+		ok: false,
+		stderr: (res.stderr ?? "").trim(),
+		code: res.status
 	};
 }
-function checkDocker() {
+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");
+function whichBin(name) {
 	try {
+		return execFileSync(process.platform === "win32" ? "where" : "which", [name], {
+			encoding: "utf-8",
+			timeout: 3e3
+		}).split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Resolve how the service should launch the CLI.
+*
+* Prefers the installed `first-tree-hub` bin on PATH (usually a shim under
+* /usr/local/bin or ~/.npm-global/bin). Falls back to invoking the current
+* Node interpreter against the running script (handles `pnpm dev`, tsx, and
+* dev-only global installs).
+*/
+function resolveCliInvocation() {
+	const bin = whichBin("first-tree-hub");
+	if (bin && isAbsolute(bin)) try {
 		return {
-			label: "Docker",
-			ok: true,
-			detail: execFileSync("docker", ["--version"], {
-				encoding: "utf-8",
-				timeout: 5e3
-			}).trim().replace("Docker version ", "v").split(",")[0] ?? ""
+			kind: "bin",
+			program: realpathSync(bin)
 		};
 	} catch {
 		return {
-			label: "Docker",
-			ok: false,
-			detail: "not found (optional — needed for auto PG provisioning)"
+			kind: "bin",
+			program: bin
 		};
 	}
-}
-function checkServerConfig() {
-	const hasFile = existsSync(join(DEFAULT_CONFIG_DIR, "server.yaml"));
-	const hasEnv = !!process.env.FIRST_TREE_HUB_DATABASE_URL;
-	if (hasFile && hasEnv) return {
-		label: "Config",
-		ok: true,
-		detail: "config file + env vars"
-	};
-	if (hasFile) return {
-		label: "Config",
-		ok: true,
-		detail: join(DEFAULT_CONFIG_DIR, "server.yaml")
-	};
-	if (hasEnv) return {
-		label: "Config",
-		ok: true,
-		detail: "via environment variables"
-	};
+	const script = process.argv[1];
+	if (!script) throw new Error("Cannot resolve CLI entry point (process.argv[1] is empty).");
+	const scriptAbs = isAbsolute(script) ? script : join(process.cwd(), script);
 	return {
-		label: "Config",
-		ok: false,
-		detail: "no config file or env vars found"
+		kind: "node",
+		program: process.execPath,
+		args: [scriptAbs]
 	};
 }
-async function checkDatabase() {
-	const dbUrl = get(getServerConfig(), "database.url");
-	if (typeof dbUrl !== "string" || !dbUrl) return {
-		label: "Database",
-		ok: false,
-		detail: "not configured (FIRST_TREE_HUB_DATABASE_URL or config file)"
+function ensureLogDir() {
+	mkdirSync(LOG_DIR, {
+		recursive: true,
+		mode: 448
+	});
+}
+function launchdPlistPath() {
+	return join(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+}
+function renderPlist(invocation) {
+	const argsXml = (invocation.kind === "bin" ? [
+		invocation.program,
+		"client",
+		"start",
+		"--no-interactive"
+	] : [
+		invocation.program,
+		...invocation.args,
+		"client",
+		"start",
+		"--no-interactive"
+	]).map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
+	const stdoutFallback = join(LOG_DIR, "client.stdout.log");
+	const stderrFallback = join(LOG_DIR, "client.stderr.log");
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTD/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argsXml}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+    <key>FIRST_TREE_HUB_SERVICE_MODE</key>
+    <string>1</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(stdoutFallback)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(stderrFallback)}</string>
+</dict>
+</plist>
+`;
+}
+function escapeXml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function launchctlDomainTarget() {
+	return `gui/${userInfo().uid}`;
+}
+function launchdState() {
+	if (!existsSync(launchdPlistPath())) return { state: "not-installed" };
+	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"
 	};
-	try {
-		const { default: pg } = await import("postgres");
-		const sql = pg(dbUrl, {
-			max: 1,
-			connect_timeout: 5,
-			idle_timeout: 1
-		});
-		await sql.unsafe("SELECT 1");
-		await sql.end();
-		return {
-			label: "Database",
-			ok: true,
-			detail: "connected"
-		};
-	} catch (err) {
+	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 {
-			label: "Database",
-			ok: false,
-			detail: `unreachable — ${(err instanceof Error ? err.message : String(err)).slice(0, 80)}`
+			state: "active",
+			detail: pid ? `pid ${pid}` : "running"
 		};
 	}
+	return {
+		state: "inactive",
+		detail: stateLine?.trim() ?? "loaded"
+	};
 }
-async function checkServerHealth() {
-	const config = getServerConfig();
-	const host = get(config, "server.host") ?? "127.0.0.1";
-	const port = get(config, "server.port") ?? 8e3;
-	const url = `http://${host}:${port}/healthz`;
-	try {
-		const res = await fetch(url, { signal: AbortSignal.timeout(3e3) });
-		if (res.ok) return {
-			label: "Server Health",
-			ok: true,
-			detail: `running at ${host}:${port}`
-		};
-		return {
-			label: "Server Health",
-			ok: false,
-			detail: `unhealthy (HTTP ${res.status}) at ${host}:${port}`
-		};
-	} catch {
-		return {
-			label: "Server Health",
-			ok: false,
-			detail: `not running at ${host}:${port}`
-		};
+/**
+* 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 checkClientConfig() {
-	const hasFile = existsSync(join(DEFAULT_CONFIG_DIR, "client.yaml"));
-	const hasEnv = !!process.env.FIRST_TREE_HUB_SERVER_URL;
-	if (hasFile && hasEnv) return {
-		label: "Config",
-		ok: true,
-		detail: "config file + env vars"
-	};
-	if (hasFile) return {
-		label: "Config",
-		ok: true,
-		detail: join(DEFAULT_CONFIG_DIR, "client.yaml")
-	};
-	if (hasEnv) return {
-		label: "Config",
-		ok: true,
-		detail: "via environment variables"
-	};
-	return {
-		label: "Config",
-		ok: false,
-		detail: "no config file or env vars found"
-	};
-}
-async function checkServerReachable() {
-	const serverUrl = get(getClientConfig(), "server.url");
-	if (typeof serverUrl !== "string" || !serverUrl) return {
-		label: "Server URL",
-		ok: false,
-		detail: "not configured (FIRST_TREE_HUB_SERVER_URL or config file)"
-	};
-	try {
-		const res = await fetch(`${serverUrl}/healthz`, { signal: AbortSignal.timeout(5e3) });
-		if (res.ok) return {
-			label: "Server URL",
-			ok: true,
-			detail: serverUrl
-		};
-		return {
-			label: "Server URL",
-			ok: false,
-			detail: `unhealthy (HTTP ${res.status}) at ${serverUrl}`
-		};
-	} catch {
-		return {
-			label: "Server URL",
-			ok: false,
-			detail: `unreachable at ${serverUrl}`
-		};
+function installLaunchd() {
+	const invocation = resolveCliInvocation();
+	ensureLogDir();
+	const plistPath = launchdPlistPath();
+	mkdirSync(dirname(plistPath), { recursive: true });
+	writeFileSync(plistPath, renderPlist(invocation), { mode: 420 });
+	const target = launchctlDomainTarget();
+	const bootoutRes = runCapture("launchctl", ["bootout", `${target}/${LAUNCHD_LABEL}`], 15e3);
+	if (!bootoutRes.ok) {
+		if (!/not find|no such|not loaded/i.test(bootoutRes.stderr)) print.line(`    warning: launchctl bootout: ${bootoutRes.stderr || `exit ${bootoutRes.code ?? "unknown"}`}\n`);
 	}
-}
-function checkAgentConfigs() {
-	const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
-	if (!existsSync(agentsDir)) return {
-		label: "Agents",
-		ok: false,
-		detail: "no agents configured"
-	};
-	try {
-		const agents = loadAgents({
-			schema: agentConfigSchema,
-			agentsDir
-		});
-		if (agents.size === 0) return {
-			label: "Agents",
-			ok: false,
-			detail: "no agents configured"
-		};
-		const names = [...agents.keys()].join(", ");
-		return {
-			label: "Agents",
-			ok: true,
-			detail: `${agents.size} configured (${names})`
-		};
-	} catch {
-		return {
-			label: "Agents",
-			ok: false,
-			detail: "error reading agent configs"
-		};
+	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);
 	}
-}
-async function checkWebSocket() {
-	const serverUrl = get(getClientConfig(), "server.url");
-	if (typeof serverUrl !== "string" || !serverUrl) return {
-		label: "WebSocket",
-		ok: false,
-		detail: "cannot check (no server URL)"
+	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 client connect <server-url>\`.`);
+	const enableRes = runCapture("launchctl", ["enable", `${target}/${LAUNCHD_LABEL}`], 5e3);
+	if (!enableRes.ok) print.line(`    warning: launchctl enable: ${enableRes.stderr || `exit ${enableRes.code ?? "unknown"}`}\n`);
+	const { state, detail } = launchdState();
+	return {
+		platform: "launchd",
+		label: LAUNCHD_LABEL,
+		unitPath: plistPath,
+		logDir: LOG_DIR,
+		state,
+		detail
 	};
-	const wsUrl = serverUrl.replace(/^http/, "ws");
-	try {
-		if ((await fetch(`${serverUrl}/healthz`, { signal: AbortSignal.timeout(3e3) })).ok) return {
-			label: "WebSocket",
-			ok: true,
-			detail: `${wsUrl} (server reachable)`
-		};
-		return {
-			label: "WebSocket",
-			ok: false,
-			detail: "server not healthy"
-		};
-	} catch {
-		return {
-			label: "WebSocket",
-			ok: false,
-			detail: `server unreachable at ${serverUrl}`
-		};
-	}
 }
-function printResults(results) {
-	for (const r of results) {
-		const icon = r.ok ? "✓" : "✗";
-		print.line(`  ${icon} ${r.label.padEnd(22)} ${r.detail}\n`);
-	}
-	blank();
-	const failures = results.filter((r) => !r.ok);
-	if (failures.length === 0) print.line("  All checks passed.\n");
-	else print.line(`  ${failures.length} issue(s) found.\n`);
-	blank();
+function uninstallLaunchd() {
+	const plistPath = launchdPlistPath();
+	const res = runCapture("launchctl", ["bootout", `${launchctlDomainTarget()}/${LAUNCHD_LABEL}`], 15e3);
+	if (!res.ok && !/not find|no such|not loaded/i.test(res.stderr)) print.line(`    warning: bootout during uninstall: ${res.stderr || `exit ${res.code ?? "unknown"}`}\n`);
+	if (existsSync(plistPath)) rmSync(plistPath);
+	return {
+		platform: "launchd",
+		label: LAUNCHD_LABEL,
+		unitPath: plistPath,
+		logDir: LOG_DIR,
+		state: "not-installed"
+	};
 }
-//#endregion
-//#region src/core/migrate.ts
-/**
-* Resolve the drizzle migrations directory.
-* 1. npm install: embedded at dist/drizzle/ (relative to the built CLI)
-* 2. Monorepo dev: resolved from @first-tree-hub/server package
-*/
-function resolveMigrationsFolder() {
-	const embeddedPath = join(dirname(fileURLToPath(import.meta.url)), "..", "drizzle");
-	if (existsSync(embeddedPath)) return embeddedPath;
-	return join(dirname(fileURLToPath(import.meta.resolve("@first-tree-hub/server/package.json"))), "drizzle");
+function systemdUnitPath() {
+	return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "systemd", "user", SYSTEMD_UNIT);
 }
-/**
-* Validate that migration journal timestamps are strictly increasing.
-* Drizzle silently skips migrations whose `when` is <= the last applied
-* timestamp, which causes missing columns/tables with no error.
-*/
-function validateJournalOrder(migrationsFolder) {
-	const journalPath = join(migrationsFolder, "meta", "_journal.json");
-	if (!existsSync(journalPath)) return;
-	const journal = JSON.parse(readFileSync(journalPath, "utf-8"));
-	let prevWhen = 0;
-	let prevTag = "";
-	for (const entry of journal.entries) {
-		if (entry.when <= prevWhen) throw new Error(`Migration journal timestamps are not monotonically increasing:\n  "${prevTag}" (when: ${prevWhen}) >= "${entry.tag}" (when: ${entry.when})\n  Drizzle will silently skip "${entry.tag}". Fix the 'when' values in:\n  ${journalPath}`);
-		prevWhen = entry.when;
-		prevTag = entry.tag;
-	}
+function renderSystemdUnit(invocation) {
+	return `[Unit]
+Description=First Tree Hub Client
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${invocation.kind === "bin" ? `${shellQuote(invocation.program)} client start --no-interactive` : `${shellQuote(invocation.program)} ${invocation.args.map(shellQuote).join(" ")} client start --no-interactive`}
+Restart=always
+RestartSec=10
+StandardOutput=append:${join(LOG_DIR, "client.stdout.log")}
+StandardError=append:${join(LOG_DIR, "client.stderr.log")}
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+Environment=FIRST_TREE_HUB_SERVICE_MODE=1
+
+[Install]
+WantedBy=default.target
+`;
 }
-/**
-* Run Drizzle database migrations.
-*/
-async function runMigrations(databaseUrl) {
-	const migrationsFolder = resolveMigrationsFolder();
-	validateJournalOrder(migrationsFolder);
-	const client = postgres(databaseUrl, { max: 1 });
-	const db = drizzle(client);
-	try {
-		await migrate(db, { migrationsFolder });
-	} finally {
-		await client.end();
-	}
-	const countClient = postgres(databaseUrl, { max: 1 });
-	try {
-		return (await countClient`
-      SELECT count(*)::int AS count
-      FROM information_schema.tables
-      WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
-    `)[0].count;
-	} finally {
-		await countClient.end();
-	}
+function shellQuote(value) {
+	if (/^[A-Za-z0-9_\-./:=]+$/.test(value)) return value;
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
 }
-//#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, {
+function systemdState() {
+	if (!existsSync(systemdUnitPath())) return { state: "not-installed" };
+	const res = spawnSync("systemctl", [
+		"--user",
+		"is-active",
+		SYSTEMD_UNIT
+	], {
 		encoding: "utf-8",
-		timeout: timeoutMs,
+		timeout: 5e3,
 		stdio: [
 			"ignore",
 			"pipe",
 			"pipe"
 		]
 	});
-	if (res.status === 0) return { ok: true };
+	const out = (res.stdout ?? "").trim();
+	if (res.status === 0 && out === "active") return {
+		state: "active",
+		detail: "running"
+	};
 	return {
-		ok: false,
-		stderr: (res.stderr ?? "").trim(),
-		code: res.status
+		state: "inactive",
+		detail: out || "unit present but not active"
+	};
+}
+function installSystemd() {
+	const invocation = resolveCliInvocation();
+	ensureLogDir();
+	const unitPath = systemdUnitPath();
+	mkdirSync(dirname(unitPath), { recursive: true });
+	writeFileSync(unitPath, renderSystemdUnit(invocation), { mode: 420 });
+	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
+	], 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 client connect <server-url>\`.`);
+	const { state, detail } = systemdState();
+	return {
+		platform: "systemd",
+		label: SYSTEMD_UNIT,
+		unitPath,
+		logDir: LOG_DIR,
+		state,
+		detail
+	};
+}
+function uninstallSystemd() {
+	const unitPath = systemdUnitPath();
+	const disableRes = runCapture("systemctl", [
+		"--user",
+		"disable",
+		"--now",
+		SYSTEMD_UNIT
+	], 1e4);
+	if (!disableRes.ok && !/not found|no such|not loaded/i.test(disableRes.stderr)) print.line(`    warning: systemctl disable during uninstall: ${disableRes.stderr || `exit ${disableRes.code ?? "unknown"}`}\n`);
+	if (existsSync(unitPath)) rmSync(unitPath);
+	const reloadRes = runCapture("systemctl", ["--user", "daemon-reload"], 5e3);
+	if (!reloadRes.ok) print.line(`    warning: systemctl daemon-reload during uninstall: ${reloadRes.stderr || `exit ${reloadRes.code ?? "unknown"}`}\n`);
+	return {
+		platform: "systemd",
+		label: SYSTEMD_UNIT,
+		unitPath,
+		logDir: LOG_DIR,
+		state: "not-installed"
 	};
 }
-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$1 = join(DEFAULT_HOME_DIR$1, "logs");
-function whichBin(name) {
-	try {
-		return execFileSync(process.platform === "win32" ? "where" : "which", [name], {
-			encoding: "utf-8",
-			timeout: 3e3
-		}).split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0] ?? null;
-	} catch {
-		return null;
-	}
+/** Is background-service install supported on the current platform? */
+function isServiceSupported() {
+	return process.platform === "darwin" || process.platform === "linux";
 }
 /**
-* Resolve how the service should launch the CLI.
+* Install the background service for the current platform.
 *
-* Prefers the installed `first-tree-hub` bin on PATH (usually a shim under
-* /usr/local/bin or ~/.npm-global/bin). Falls back to invoking the current
-* Node interpreter against the running script (handles `pnpm dev`, tsx, and
-* dev-only global installs).
+* @throws {Error} if the platform is not supported or the service manager fails.
 */
-function resolveCliInvocation() {
-	const bin = whichBin("first-tree-hub");
-	if (bin && isAbsolute(bin)) try {
+function installClientService() {
+	if (process.platform === "darwin") return installLaunchd();
+	if (process.platform === "linux") return installSystemd();
+	throw new Error(`Background service install is not supported on ${process.platform}. Run \`first-tree-hub client start\` manually to keep the computer online.`);
+}
+/** Report the current service state without modifying anything. */
+function getClientServiceStatus() {
+	if (process.platform === "darwin") {
+		const { state, detail } = launchdState();
 		return {
-			kind: "bin",
-			program: realpathSync(bin)
+			platform: "launchd",
+			label: LAUNCHD_LABEL,
+			unitPath: launchdPlistPath(),
+			logDir: LOG_DIR,
+			state,
+			detail
 		};
-	} catch {
+	}
+	if (process.platform === "linux") {
+		const { state, detail } = systemdState();
 		return {
-			kind: "bin",
-			program: bin
+			platform: "systemd",
+			label: SYSTEMD_UNIT,
+			unitPath: systemdUnitPath(),
+			logDir: LOG_DIR,
+			state,
+			detail
 		};
 	}
-	const script = process.argv[1];
-	if (!script) throw new Error("Cannot resolve CLI entry point (process.argv[1] is empty).");
-	const scriptAbs = isAbsolute(script) ? script : join(process.cwd(), script);
 	return {
-		kind: "node",
-		program: process.execPath,
-		args: [scriptAbs]
+		platform: "unsupported",
+		label: "",
+		unitPath: "",
+		logDir: LOG_DIR,
+		state: "not-installed",
+		detail: `platform ${process.platform} not supported`
 	};
 }
-function ensureLogDir() {
-	mkdirSync(LOG_DIR$1, {
-		recursive: true,
-		mode: 448
+/** Uninstall the background service. No-op if not installed. */
+function uninstallClientService() {
+	if (process.platform === "darwin") return uninstallLaunchd();
+	if (process.platform === "linux") return uninstallSystemd();
+	return getClientServiceStatus();
+}
+//#endregion
+//#region src/core/doctor.ts
+function getServerConfig() {
+	return resolveConfigReadonly({
+		schema: serverConfigSchema,
+		role: "server"
 	});
 }
-function launchdPlistPath() {
-	return join(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+function getClientConfig() {
+	return resolveConfigReadonly({
+		schema: clientConfigSchema,
+		role: "client"
+	});
 }
-function renderPlist(invocation) {
-	const argsXml = (invocation.kind === "bin" ? [
-		invocation.program,
-		"client",
-		"start",
-		"--no-interactive"
-	] : [
-		invocation.program,
-		...invocation.args,
-		"client",
-		"start",
-		"--no-interactive"
-	]).map((a) => `    <string>${escapeXml(a)}</string>`).join("\n");
-	const stdoutFallback = join(LOG_DIR$1, "client.stdout.log");
-	const stderrFallback = join(LOG_DIR$1, "client.stderr.log");
-	return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTD/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>${LAUNCHD_LABEL}</string>
-  <key>ProgramArguments</key>
-  <array>
-${argsXml}
-  </array>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PATH</key>
-    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
-    <key>FIRST_TREE_HUB_SERVICE_MODE</key>
-    <string>1</string>
-  </dict>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <dict>
-    <key>SuccessfulExit</key>
-    <false/>
-  </dict>
-  <key>ThrottleInterval</key>
-  <integer>10</integer>
-  <key>StandardOutPath</key>
-  <string>${escapeXml(stdoutFallback)}</string>
-  <key>StandardErrorPath</key>
-  <string>${escapeXml(stderrFallback)}</string>
-</dict>
-</plist>
-`;
+function get(obj, dotPath) {
+	const parts = dotPath.split(".");
+	let current = obj;
+	for (const part of parts) {
+		if (current === null || current === void 0 || typeof current !== "object") return void 0;
+		current = current[part];
+	}
+	return current;
 }
-function escapeXml(value) {
-	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function checkNodeVersion() {
+	const version = process.versions.node;
+	const [major] = version.split(".").map(Number);
+	const ok = major !== void 0 && major >= 22;
+	return {
+		label: "Node.js",
+		ok,
+		detail: ok ? `v${version}` : `v${version} (requires >= 22.16)`
+	};
 }
-function launchctlDomainTarget() {
-	return `gui/${userInfo().uid}`;
+function checkDocker() {
+	try {
+		return {
+			label: "Docker",
+			ok: true,
+			detail: execFileSync("docker", ["--version"], {
+				encoding: "utf-8",
+				timeout: 5e3
+			}).trim().replace("Docker version ", "v").split(",")[0] ?? ""
+		};
+	} catch {
+		return {
+			label: "Docker",
+			ok: false,
+			detail: "not found (optional — needed for auto PG provisioning)"
+		};
+	}
 }
-function launchdState() {
-	if (!existsSync(launchdPlistPath())) return { state: "not-installed" };
-	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"
+function checkServerConfig() {
+	const hasFile = existsSync(join(DEFAULT_CONFIG_DIR, "server.yaml"));
+	const hasEnv = !!process.env.FIRST_TREE_HUB_DATABASE_URL;
+	if (hasFile && hasEnv) return {
+		label: "Config",
+		ok: true,
+		detail: "config file + env vars"
 	};
-	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();
+	if (hasFile) return {
+		label: "Config",
+		ok: true,
+		detail: join(DEFAULT_CONFIG_DIR, "server.yaml")
+	};
+	if (hasEnv) return {
+		label: "Config",
+		ok: true,
+		detail: "via environment variables"
+	};
+	return {
+		label: "Config",
+		ok: false,
+		detail: "no config file or env vars found"
+	};
+}
+async function checkDatabase() {
+	const dbUrl = get(getServerConfig(), "database.url");
+	if (typeof dbUrl !== "string" || !dbUrl) return {
+		label: "Database",
+		ok: false,
+		detail: "not configured (FIRST_TREE_HUB_DATABASE_URL or config file)"
+	};
+	try {
+		const { default: pg } = await import("postgres");
+		const sql = pg(dbUrl, {
+			max: 1,
+			connect_timeout: 5,
+			idle_timeout: 1
+		});
+		await sql.unsafe("SELECT 1");
+		await sql.end();
+		return {
+			label: "Database",
+			ok: true,
+			detail: "connected"
+		};
+	} catch (err) {
+		return {
+			label: "Database",
+			ok: false,
+			detail: `unreachable — ${(err instanceof Error ? err.message : String(err)).slice(0, 80)}`
+		};
+	}
+}
+async function checkServerHealth() {
+	const config = getServerConfig();
+	const host = get(config, "server.host") ?? "127.0.0.1";
+	const port = get(config, "server.port") ?? 8e3;
+	const url = `http://${host}:${port}/healthz`;
+	try {
+		const res = await fetch(url, { signal: AbortSignal.timeout(3e3) });
+		if (res.ok) return {
+			label: "Server Health",
+			ok: true,
+			detail: `running at ${host}:${port}`
+		};
 		return {
-			state: "active",
-			detail: pid ? `pid ${pid}` : "running"
+			label: "Server Health",
+			ok: false,
+			detail: `unhealthy (HTTP ${res.status}) at ${host}:${port}`
+		};
+	} catch {
+		return {
+			label: "Server Health",
+			ok: false,
+			detail: `not running at ${host}:${port}`
 		};
 	}
+}
+function checkClientConfig() {
+	const hasFile = existsSync(join(DEFAULT_CONFIG_DIR, "client.yaml"));
+	const hasEnv = !!process.env.FIRST_TREE_HUB_SERVER_URL;
+	if (hasFile && hasEnv) return {
+		label: "Config",
+		ok: true,
+		detail: "config file + env vars"
+	};
+	if (hasFile) return {
+		label: "Config",
+		ok: true,
+		detail: join(DEFAULT_CONFIG_DIR, "client.yaml")
+	};
+	if (hasEnv) return {
+		label: "Config",
+		ok: true,
+		detail: "via environment variables"
+	};
 	return {
-		state: "inactive",
-		detail: stateLine?.trim() ?? "loaded"
+		label: "Config",
+		ok: false,
+		detail: "no config file or env vars found"
 	};
 }
-/**
-* 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);
+async function checkServerReachable() {
+	const serverUrl = get(getClientConfig(), "server.url");
+	if (typeof serverUrl !== "string" || !serverUrl) return {
+		label: "Server URL",
+		ok: false,
+		detail: "not configured (FIRST_TREE_HUB_SERVER_URL or config file)"
+	};
+	try {
+		const res = await fetch(`${serverUrl}/healthz`, { signal: AbortSignal.timeout(5e3) });
+		if (res.ok) return {
+			label: "Server URL",
+			ok: true,
+			detail: serverUrl
+		};
+		return {
+			label: "Server URL",
+			ok: false,
+			detail: `unhealthy (HTTP ${res.status}) at ${serverUrl}`
+		};
+	} catch {
+		return {
+			label: "Server URL",
+			ok: false,
+			detail: `unreachable at ${serverUrl}`
+		};
 	}
-	return false;
 }
-function installLaunchd() {
-	const invocation = resolveCliInvocation();
-	ensureLogDir();
-	const plistPath = launchdPlistPath();
-	mkdirSync(dirname(plistPath), { recursive: true });
-	writeFileSync(plistPath, renderPlist(invocation), { mode: 420 });
-	const target = launchctlDomainTarget();
-	const bootoutRes = runCapture("launchctl", ["bootout", `${target}/${LAUNCHD_LABEL}`], 15e3);
-	if (!bootoutRes.ok) {
-		if (!/not find|no such|not loaded/i.test(bootoutRes.stderr)) print.line(`    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) print.line(`    warning: launchctl enable: ${enableRes.stderr || `exit ${enableRes.code ?? "unknown"}`}\n`);
-	const { state, detail } = launchdState();
-	return {
-		platform: "launchd",
-		label: LAUNCHD_LABEL,
-		unitPath: plistPath,
-		logDir: LOG_DIR$1,
-		state,
-		detail
+function checkAgentConfigs() {
+	const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
+	if (!existsSync(agentsDir)) return {
+		label: "Agents",
+		ok: false,
+		detail: "no agents configured"
 	};
+	try {
+		const agents = loadAgents({
+			schema: agentConfigSchema,
+			agentsDir
+		});
+		if (agents.size === 0) return {
+			label: "Agents",
+			ok: false,
+			detail: "no agents configured"
+		};
+		const names = [...agents.keys()].join(", ");
+		return {
+			label: "Agents",
+			ok: true,
+			detail: `${agents.size} configured (${names})`
+		};
+	} catch {
+		return {
+			label: "Agents",
+			ok: false,
+			detail: "error reading agent configs"
+		};
+	}
 }
-function uninstallLaunchd() {
-	const plistPath = launchdPlistPath();
-	const res = runCapture("launchctl", ["bootout", `${launchctlDomainTarget()}/${LAUNCHD_LABEL}`], 15e3);
-	if (!res.ok && !/not find|no such|not loaded/i.test(res.stderr)) print.line(`    warning: bootout during uninstall: ${res.stderr || `exit ${res.code ?? "unknown"}`}\n`);
-	if (existsSync(plistPath)) rmSync(plistPath);
+function checkBackgroundService() {
+	const info = getClientServiceStatus();
+	if (info.platform === "unsupported") return {
+		label: "Background service",
+		ok: true,
+		detail: `not supported on ${process.platform} — runs inline`
+	};
+	if (info.state === "active") return {
+		label: "Background service",
+		ok: true,
+		detail: `running (${info.platform}${info.detail ? `, ${info.detail}` : ""}); logs at ${info.logDir}`
+	};
+	if (info.state === "inactive") return {
+		label: "Background service",
+		ok: false,
+		detail: `installed but not running${info.detail ? ` — ${info.detail}` : ""}; unit at ${info.unitPath}`
+	};
 	return {
-		platform: "launchd",
-		label: LAUNCHD_LABEL,
-		unitPath: plistPath,
-		logDir: LOG_DIR$1,
-		state: "not-installed"
+		label: "Background service",
+		ok: false,
+		detail: "not installed — re-run `first-tree-hub client connect <url>` to install"
 	};
 }
-function systemdUnitPath() {
-	return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "systemd", "user", SYSTEMD_UNIT);
-}
-function renderSystemdUnit(invocation) {
-	return `[Unit]
-Description=First Tree Hub Client
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-ExecStart=${invocation.kind === "bin" ? `${shellQuote(invocation.program)} client start --no-interactive` : `${shellQuote(invocation.program)} ${invocation.args.map(shellQuote).join(" ")} client start --no-interactive`}
-Restart=always
-RestartSec=10
-StandardOutput=append:${join(LOG_DIR$1, "client.stdout.log")}
-StandardError=append:${join(LOG_DIR$1, "client.stderr.log")}
-Environment=PATH=/usr/local/bin:/usr/bin:/bin
-Environment=FIRST_TREE_HUB_SERVICE_MODE=1
-
-[Install]
-WantedBy=default.target
-`;
+async function checkWebSocket() {
+	const serverUrl = get(getClientConfig(), "server.url");
+	if (typeof serverUrl !== "string" || !serverUrl) return {
+		label: "WebSocket",
+		ok: false,
+		detail: "cannot check (no server URL)"
+	};
+	const wsUrl = serverUrl.replace(/^http/, "ws");
+	try {
+		if ((await fetch(`${serverUrl}/healthz`, { signal: AbortSignal.timeout(3e3) })).ok) return {
+			label: "WebSocket",
+			ok: true,
+			detail: `${wsUrl} (server reachable)`
+		};
+		return {
+			label: "WebSocket",
+			ok: false,
+			detail: "server not healthy"
+		};
+	} catch {
+		return {
+			label: "WebSocket",
+			ok: false,
+			detail: `server unreachable at ${serverUrl}`
+		};
+	}
 }
-function shellQuote(value) {
-	if (/^[A-Za-z0-9_\-./:=]+$/.test(value)) return value;
-	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+function printResults(results) {
+	for (const r of results) {
+		const icon = r.ok ? "✓" : "✗";
+		print.line(`  ${icon} ${r.label.padEnd(22)} ${r.detail}\n`);
+	}
+	blank();
+	const failures = results.filter((r) => !r.ok);
+	if (failures.length === 0) print.line("  All checks passed.\n");
+	else print.line(`  ${failures.length} issue(s) found.\n`);
+	blank();
 }
-function systemdState() {
-	if (!existsSync(systemdUnitPath())) return { state: "not-installed" };
-	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"
-	};
+//#endregion
+//#region src/core/migrate.ts
+/**
+* Resolve the drizzle migrations directory.
+* 1. npm install: embedded at dist/drizzle/ (relative to the built CLI)
+* 2. Monorepo dev: resolved from @first-tree-hub/server package
+*/
+function resolveMigrationsFolder() {
+	const embeddedPath = join(dirname(fileURLToPath(import.meta.url)), "..", "drizzle");
+	if (existsSync(embeddedPath)) return embeddedPath;
+	return join(dirname(fileURLToPath(import.meta.resolve("@first-tree-hub/server/package.json"))), "drizzle");
 }
-function installSystemd() {
-	const invocation = resolveCliInvocation();
-	ensureLogDir();
-	const unitPath = systemdUnitPath();
-	mkdirSync(dirname(unitPath), { recursive: true });
-	writeFileSync(unitPath, renderSystemdUnit(invocation), { mode: 420 });
-	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
-	], 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",
-		label: SYSTEMD_UNIT,
-		unitPath,
-		logDir: LOG_DIR$1,
-		state,
-		detail
-	};
+/**
+* Validate that migration journal timestamps are strictly increasing.
+* Drizzle silently skips migrations whose `when` is <= the last applied
+* timestamp, which causes missing columns/tables with no error.
+*/
+function validateJournalOrder(migrationsFolder) {
+	const journalPath = join(migrationsFolder, "meta", "_journal.json");
+	if (!existsSync(journalPath)) return;
+	const journal = JSON.parse(readFileSync(journalPath, "utf-8"));
+	let prevWhen = 0;
+	let prevTag = "";
+	for (const entry of journal.entries) {
+		if (entry.when <= prevWhen) throw new Error(`Migration journal timestamps are not monotonically increasing:\n  "${prevTag}" (when: ${prevWhen}) >= "${entry.tag}" (when: ${entry.when})\n  Drizzle will silently skip "${entry.tag}". Fix the 'when' values in:\n  ${journalPath}`);
+		prevWhen = entry.when;
+		prevTag = entry.tag;
+	}
 }
-function uninstallSystemd() {
-	const unitPath = systemdUnitPath();
-	const disableRes = runCapture("systemctl", [
-		"--user",
-		"disable",
-		"--now",
-		SYSTEMD_UNIT
-	], 1e4);
-	if (!disableRes.ok && !/not found|no such|not loaded/i.test(disableRes.stderr)) print.line(`    warning: systemctl disable during uninstall: ${disableRes.stderr || `exit ${disableRes.code ?? "unknown"}`}\n`);
-	if (existsSync(unitPath)) rmSync(unitPath);
-	const reloadRes = runCapture("systemctl", ["--user", "daemon-reload"], 5e3);
-	if (!reloadRes.ok) print.line(`    warning: systemctl daemon-reload during uninstall: ${reloadRes.stderr || `exit ${reloadRes.code ?? "unknown"}`}\n`);
-	return {
-		platform: "systemd",
-		label: SYSTEMD_UNIT,
-		unitPath,
-		logDir: LOG_DIR$1,
-		state: "not-installed"
-	};
+/**
+* Run Drizzle database migrations.
+*/
+async function runMigrations(databaseUrl) {
+	const migrationsFolder = resolveMigrationsFolder();
+	validateJournalOrder(migrationsFolder);
+	const client = postgres(databaseUrl, { max: 1 });
+	const db = drizzle(client);
+	try {
+		await migrate(db, { migrationsFolder });
+	} finally {
+		await client.end();
+	}
+	const countClient = postgres(databaseUrl, { max: 1 });
+	try {
+		return (await countClient`
+      SELECT count(*)::int AS count
+      FROM information_schema.tables
+      WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+    `)[0].count;
+	} finally {
+		await countClient.end();
+	}
 }
-/** Is background-service install supported on the current platform? */
-function isServiceSupported() {
-	return process.platform === "darwin" || process.platform === "linux";
+//#endregion
+//#region src/core/migrate-agent-dirs.ts
+function createApiNameResolver(serverUrl, getAccessToken) {
+	let cache = null;
+	const PAGE_SIZE = 100;
+	const MAX_PAGES = 50;
+	async function ensureCache() {
+		if (cache) return cache;
+		const token = await getAccessToken();
+		const map = /* @__PURE__ */ new Map();
+		let cursor = null;
+		for (let page = 0; page < MAX_PAGES; page++) {
+			const qs = new URLSearchParams({ limit: String(PAGE_SIZE) });
+			if (cursor) qs.set("cursor", cursor);
+			const res = await fetch(`${serverUrl}/api/v1/admin/agents?${qs.toString()}`, {
+				method: "GET",
+				headers: { Authorization: `Bearer ${token}` },
+				signal: AbortSignal.timeout(1e4)
+			});
+			if (!res.ok) throw new Error(`admin agents list returned HTTP ${res.status}`);
+			const body = await res.json();
+			for (const row of body.items) map.set(row.uuid, row.name);
+			if (!body.nextCursor) break;
+			cursor = body.nextCursor;
+		}
+		cache = map;
+		return map;
+	}
+	return { async resolveName(agentId) {
+		return (await ensureCache()).get(agentId) ?? null;
+	} };
 }
 /**
-* Install the background service for the current platform.
-*
-* @throws {Error} if the platform is not supported or the service manager fails.
+* Read the `agentId` field out of a single `agent.yaml` with minimal
+* parsing. Unlike `loadAgents`, which Zod-validates every entry and
+* throws on the first malformed file (aborting migration for *every*
+* other agent below it), this helper scopes failures per-dir: a broken
+* file returns `null` and the caller logs + skips that dir only.
 */
-function installClientService() {
-	if (process.platform === "darwin") return installLaunchd();
-	if (process.platform === "linux") return installSystemd();
-	throw new Error(`Background service install is not supported on ${process.platform}. Run \`first-tree-hub client start\` manually to keep the computer online.`);
+function readAgentId(agentYamlPath) {
+	try {
+		const parsed = parse(readFileSync(agentYamlPath, "utf-8"));
+		if (parsed && typeof parsed === "object" && "agentId" in parsed) {
+			const id = parsed.agentId;
+			if (typeof id === "string" && id.length > 0) return id;
+		}
+		return null;
+	} catch {
+		return null;
+	}
 }
-/** Report the current service state without modifying anything. */
-function getClientServiceStatus() {
-	if (process.platform === "darwin") {
-		const { state, detail } = launchdState();
+/**
+* Walk `agentsDir`, for each local agent compare the dir name to the
+* server's canonical `name`, and rename the dir + workspaces/sessions
+* entries when they differ. Returns a summary so the caller can decide
+* whether to print additional context.
+*/
+async function migrateLocalAgentDirs(opts) {
+	const { agentsDir, workspacesDir, sessionsDir, resolver } = opts;
+	const result = {
+		scanned: 0,
+		renamed: 0,
+		skipped: 0,
+		errors: 0
+	};
+	if (!existsSync(agentsDir)) return result;
+	let dirNames;
+	try {
+		dirNames = readdirSync(agentsDir).filter((name) => {
+			try {
+				return statSync(join(agentsDir, name)).isDirectory();
+			} catch {
+				return false;
+			}
+		});
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		print.status("⚠️", `agent-dir migration: unable to enumerate ${agentsDir}: ${msg}`);
 		return {
-			platform: "launchd",
-			label: LAUNCHD_LABEL,
-			unitPath: launchdPlistPath(),
-			logDir: LOG_DIR$1,
-			state,
-			detail
+			...result,
+			errors: result.errors + 1
 		};
 	}
-	if (process.platform === "linux") {
-		const { state, detail } = systemdState();
-		return {
-			platform: "systemd",
-			label: SYSTEMD_UNIT,
-			unitPath: systemdUnitPath(),
-			logDir: LOG_DIR$1,
-			state,
-			detail
-		};
+	const finalDirNames = new Set(dirNames);
+	for (const dirName of dirNames) {
+		const agentYamlPath = join(agentsDir, dirName, "agent.yaml");
+		const agentId = readAgentId(agentYamlPath);
+		if (!agentId) {
+			if (existsSync(agentYamlPath)) {
+				print.status("⚠️", `agent-dir migration: unreadable ${agentYamlPath}; skipping this dir.`);
+				result.errors += 1;
+			}
+			continue;
+		}
+		result.scanned += 1;
+		let serverName;
+		try {
+			serverName = await resolver.resolveName(agentId);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			const hint = msg.includes("403") ? " (likely a non-admin account — migration skipped)" : "";
+			print.status("⚠️", `agent-dir migration: failed to resolve "${dirName}" (${agentId}): ${msg}${hint}`);
+			result.errors += 1;
+			return result;
+		}
+		if (!serverName) {
+			result.skipped += 1;
+			continue;
+		}
+		if (serverName === dirName) continue;
+		const oldDir = join(agentsDir, dirName);
+		const newDir = join(agentsDir, serverName);
+		if (existsSync(newDir)) {
+			print.status("⚠️", `agent-dir migration: cannot rename "${dirName}" → "${serverName}" — target already exists. Skipping.`);
+			result.skipped += 1;
+			continue;
+		}
+		try {
+			renameSync(oldDir, newDir);
+			finalDirNames.delete(dirName);
+			finalDirNames.add(serverName);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			print.status("⚠️", `agent-dir migration: config dir rename failed for "${dirName}": ${msg}`);
+			result.errors += 1;
+			continue;
+		}
+		const oldWorkspace = join(workspacesDir, dirName);
+		const newWorkspace = join(workspacesDir, serverName);
+		if (existsSync(oldWorkspace)) try {
+			if (existsSync(newWorkspace)) print.status("⚠️", `agent-dir migration: workspace target "${serverName}" already exists; leaving old "${dirName}" in place for manual cleanup.`);
+			else if (statSync(oldWorkspace).isDirectory()) renameSync(oldWorkspace, newWorkspace);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			print.status("⚠️", `agent-dir migration: workspace rename failed for "${dirName}": ${msg}`);
+			result.errors += 1;
+		}
+		const oldSessions = join(sessionsDir, `${dirName}.json`);
+		const newSessions = join(sessionsDir, `${serverName}.json`);
+		if (existsSync(oldSessions)) try {
+			if (existsSync(newSessions)) print.status("⚠️", `agent-dir migration: sessions target "${serverName}.json" already exists; leaving old "${dirName}.json" in place for manual cleanup.`);
+			else renameSync(oldSessions, newSessions);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			print.status("⚠️", `agent-dir migration: sessions rename failed for "${dirName}": ${msg}`);
+			result.errors += 1;
+		}
+		print.status("", `agent "${dirName}" renamed to "${serverName}" to match hub`);
+		result.renamed += 1;
 	}
-	return {
-		platform: "unsupported",
-		label: "",
-		unitPath: "",
-		logDir: LOG_DIR$1,
-		state: "not-installed",
-		detail: `platform ${process.platform} not supported`
-	};
-}
-/** Uninstall the background service. No-op if not installed. */
-function uninstallClientService() {
-	if (process.platform === "darwin") return uninstallLaunchd();
-	if (process.platform === "linux") return uninstallSystemd();
-	return getClientServiceStatus();
+	try {
+		const orphanWs = existsSync(workspacesDir) ? readdirSync(workspacesDir).filter((d) => !finalDirNames.has(d)) : [];
+		const orphanSessions = existsSync(sessionsDir) ? readdirSync(sessionsDir).filter((f) => f.endsWith(".json") && !finalDirNames.has(f.slice(0, -5))) : [];
+		if (orphanWs.length > 0 || orphanSessions.length > 0) {
+			const parts = [];
+			if (orphanWs.length > 0) parts.push(`workspaces: ${orphanWs.join(", ")}`);
+			if (orphanSessions.length > 0) parts.push(`sessions: ${orphanSessions.join(", ")}`);
+			print.status("", `orphaned local state detected (${parts.join("; ")}). Run \`first-tree-hub agent workspace clean\` to reclaim disk.`);
+		}
+	} catch {}
+	return result;
 }
 //#endregion
 //#region src/core/migrate-home.ts
@@ -6098,7 +6347,7 @@ function runHomeMigration() {
 	}
 	print.line(`[first-tree-hub] Copied client home to new layout: ${result.from} → ${result.to}\n  (Legacy directory preserved as a backup — delete it manually once you've verified the new location works.)\n`);
 	if (process.argv.includes("--no-interactive")) {
-		print.line("[first-tree-hub] Note: running as background service — skipped auto re-register to avoid self-termination.\n  Run `first-tree-hub client service install` from a terminal to refresh log paths.\n");
+		print.line("[first-tree-hub] Note: running as background service — skipped auto re-register to avoid self-termination.\n  Service paths will refresh on the next `first-tree-hub client connect <url>`.\n");
 		return;
 	}
 	const status = getClientServiceStatus();
@@ -6108,7 +6357,7 @@ function runHomeMigration() {
 		print.line(`[first-tree-hub] Re-registered background service with new home paths.\n`);
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
-		print.line(`[first-tree-hub] WARNING: home migration succeeded but re-registering the background service failed: ${msg}\n  Run \`first-tree-hub client service install\` to refresh log paths.\n`);
+		print.line(`[first-tree-hub] WARNING: home migration succeeded but re-registering the background service failed: ${msg}\n  Re-run \`first-tree-hub client connect <url>\` to refresh service paths.\n`);
 	}
 }
 //#endregion
@@ -6253,8 +6502,9 @@ async function onboardCreate(args) {
 		metadata: Object.keys(metadata).length > 0 ? metadata : void 0,
 		clientId: args.type === "human" ? void 0 : args.clientId
 	});
-	print.line(`Agent "${args.id}" created (uuid ${primary.uuid}).\n`);
-	if (args.type !== "human") saveAgentConfig(args.id, primary.uuid, "claude-code");
+	const primaryLocalName = primary.name ?? args.id;
+	print.line(`Agent "${primaryLocalName}" created (uuid ${primary.uuid}).\n`);
+	if (args.type !== "human") saveAgentConfig(primaryLocalName, primary.uuid, "claude-code");
 	let assistantUuid = null;
 	if (args.assistant) {
 		print.line(`Creating assistant "${args.assistant}"...\n`);
@@ -6270,8 +6520,9 @@ async function onboardCreate(args) {
 				clientId: args.clientId
 			});
 			assistantUuid = assistant.uuid;
-			saveAgentConfig(args.assistant, assistant.uuid, "claude-code");
-			print.line(`Assistant "${args.assistant}" ready.\n`);
+			const assistantLocalName = assistant.name ?? args.assistant;
+			saveAgentConfig(assistantLocalName, assistant.uuid, "claude-code");
+			print.line(`Assistant "${assistantLocalName}" ready.\n`);
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			print.line(`Warning: Failed to create assistant "${args.assistant}": ${msg}\n`);
@@ -6279,7 +6530,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-BJaN64iR.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-DEmwoNn_.mjs").then((n) => n.r);
 		const targetAgentUuid = args.type === "human" ? assistantUuid : primary.uuid;
 		if (!targetAgentUuid) print.line(`Warning: Cannot bind Feishu bot — no runtime agent available for "${args.id}".\n`);
 		else {
@@ -6355,18 +6606,40 @@ async function promptMissingFields(options) {
 	return results;
 }
 /**
-* Interactive add agent — simple two-field prompt.
-*/
-async function promptAddAgent() {
+* Interactive / scripted "add this agent to the local client".
+*
+* Phase 3 of the agent-naming refactor removed the free-form local
+* alias — the local config dir is keyed by the server-authoritative
+* `agent.name` slug. This helper only asks the user for the agent UUID
+* (or takes it via `opts.agentId`), then fetches the canonical name
+* from the Hub. A `name` comes back null only if the agent was
+* tombstoned server-side, in which case the caller must refuse the
+* add (there's nothing sensible to key the local dir on).
+*/
+async function promptAddAgent(opts = {}) {
+	if (loadCredentials() === null) throw new Error("Not connected. Run `first-tree-hub client connect <server-url>` first.");
+	let serverUrl;
+	try {
+		serverUrl = resolveServerUrl(process.env.FIRST_TREE_HUB_SERVER_URL);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`${msg} Run \`first-tree-hub client connect\` or set FIRST_TREE_HUB_SERVER_URL.`);
+	}
+	const agentId = opts.agentId ?? await input({
+		message: "Agent UUID on the Hub:",
+		validate: (v) => v.length > 0 ? true : "Agent UUID is required"
+	});
+	const token = await ensureFreshAccessToken();
+	const res = await fetch(`${serverUrl}/api/v1/admin/agents/${encodeURIComponent(agentId)}`, {
+		headers: { Authorization: `Bearer ${token}` },
+		signal: AbortSignal.timeout(1e4)
+	});
+	if (!res.ok) throw new Error(`Failed to look up agent ${agentId}: HTTP ${res.status}`);
+	const body = await res.json();
+	if (!body.name) throw new Error(`Agent ${agentId} has no hub name (tombstoned or never named). Cannot add a local config without a name.`);
 	return {
-		name: await input({
-			message: "Local alias:",
-			validate: (v) => /^[a-z0-9][a-z0-9-]*$/.test(v) ? true : "Lowercase alphanumeric and hyphens only"
-		}),
-		agentId: await input({
-			message: "Agent UUID on the Hub:",
-			validate: (v) => v.length > 0 ? true : "Agent UUID is required"
-		})
+		name: body.name,
+		agentId
 	};
 }
 async function askPrompt(dotPath, prompt) {
@@ -7177,7 +7450,7 @@ function createFeedbackHandler(config) {
 	return { handle };
 }
 //#endregion
-//#region ../server/dist/app-RWQiJW6_.mjs
+//#region ../server/dist/app-DugUZNsw.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -7244,7 +7517,7 @@ const agents = pgTable("agents", {
 	name: text("name"),
 	organizationId: text("organization_id").notNull().references(() => organizations.id),
 	type: text("type").notNull(),
-	displayName: text("display_name"),
+	displayName: text("display_name").notNull(),
 	delegateMention: text("delegate_mention"),
 	inboxId: text("inbox_id").unique().notNull(),
 	status: text("status").notNull().default("active"),
@@ -8207,6 +8480,7 @@ async function createAgent(db, data) {
 	const uuid = uuidv7();
 	const name = data.name ?? null;
 	if (name?.startsWith(RESERVED_AGENT_NAME_PREFIX)) throw new BadRequestError(`Agent name "${name}" is reserved — names starting with "${RESERVED_AGENT_NAME_PREFIX}" are Hub-internal`);
+	if (name && isReservedAgentName$1(name)) throw new BadRequestError(`Agent name "${name}" is reserved — pick a different one.`);
 	const inboxId = `inbox_${uuid}`;
 	let orgId;
 	let managerId;
@@ -8234,13 +8508,14 @@ async function createAgent(db, data) {
 	if (org && org.maxAgents > 0) {
 		if (((await db.select({ value: count() }).from(agents).where(and(eq(agents.organizationId, orgId), ne(agents.status, AGENT_STATUSES.DELETED))))[0]?.value ?? 0) >= org.maxAgents) throw new ForbiddenError(`Organization "${orgId}" has reached its agent limit (${org.maxAgents}). Upgrade your plan or delete unused agents.`);
 	}
+	const resolvedDisplayName = data.displayName?.trim() || name || "Unnamed Agent";
 	try {
 		const [agent] = await db.insert(agents).values({
 			uuid,
 			name,
 			organizationId: orgId,
 			type: data.type,
-			displayName: data.displayName ?? null,
+			displayName: resolvedDisplayName,
 			delegateMention: data.delegateMention ?? null,
 			inboxId,
 			source: data.source ?? null,
@@ -8262,6 +8537,21 @@ async function createAgent(db, data) {
 		throw err;
 	}
 }
+async function checkAgentNameAvailability(db, orgId, name) {
+	if (!AGENT_NAME_REGEX$1.test(name)) return {
+		available: false,
+		reason: "invalid"
+	};
+	if (isReservedAgentName$1(name) || name.startsWith(RESERVED_AGENT_NAME_PREFIX)) return {
+		available: false,
+		reason: "reserved"
+	};
+	const [existing] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, orgId), eq(agents.name, name), ne(agents.status, AGENT_STATUSES.DELETED))).limit(1);
+	return existing ? {
+		available: false,
+		reason: "taken"
+	} : { available: true };
+}
 async function getAgent(db, uuid) {
 	const [agent] = await db.select().from(agents).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).limit(1);
 	if (!agent) throw new NotFoundError(`Agent "${uuid}" not found`);
@@ -9163,26 +9453,33 @@ const inboxEntries = pgTable("inbox_entries", {
 	messageId: text("message_id").notNull().references(() => messages.id),
 	chatId: text("chat_id"),
 	status: text("status").notNull().default("pending"),
+	notify: boolean("notify").notNull().default(true),
 	retryCount: integer("retry_count").notNull().default(0),
 	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
 	deliveredAt: timestamp("delivered_at", { withTimezone: true }),
 	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) {
+}, (table) => [
+	unique("uq_inbox_delivery").on(table.inboxId, table.messageId, table.chatId),
+	index("idx_inbox_pending").on(table.inboxId, table.createdAt),
+	index("idx_inbox_pending_notify").on(table.inboxId, table.createdAt).where(sql`status = 'pending' AND notify = true`),
+	index("idx_inbox_chat_silent").on(table.inboxId, table.chatId, table.notify, table.status)
+]);
+async function sendMessage(db, chatId, senderId, data, options = {}) {
 	return withSpan("inbox.enqueue", messageAttrs({
 		chatId,
 		senderAgentId: senderId,
 		source: data.source ?? void 0
-	}), () => sendMessageInner(db, chatId, senderId, data));
+	}), () => sendMessageInner(db, chatId, senderId, data, options));
 }
-async function sendMessageInner(db, chatId, senderId, data) {
+async function sendMessageInner(db, chatId, senderId, data, options) {
 	return db.transaction(async (tx) => {
-		const participants = await tx.select({
+		const [participants, [chatRow]] = await Promise.all([tx.select({
 			agentId: chatParticipants.agentId,
 			inboxId: agents.inboxId,
 			mode: chatParticipants.mode,
 			name: agents.name
-		}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId));
+		}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId)), tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1)]);
+		const chatType = chatRow?.type ?? null;
 		if (data.replyToInbox !== void 0 && data.replyToInbox !== null) {
 			const [senderRow] = await tx.select({ inboxId: agents.inboxId }).from(agents).where(eq(agents.uuid, senderId)).limit(1);
 			if (!senderRow || senderRow.inboxId !== data.replyToInbox) throw new BadRequestError("replyToInbox must reference the sender's own inbox");
@@ -9197,13 +9494,32 @@ async function sendMessageInner(db, chatId, senderId, data) {
 			...incomingMeta,
 			mentions: mergedMentions
 		} : incomingMeta;
+		if (options.enforceGroupMention && chatType === "group") {
+			if (mergedMentions.filter((id) => id !== senderId).length === 0) throw new BadRequestError("Sending to a group chat requires an explicit @mention. Use `agent send <name>` to message a single agent, or @<name> in the content to address one or more group members.");
+		}
+		let outboundContent = data.content;
+		if (options.normalizeMentionsInContent && typeof outboundContent === "string") {
+			const present = new Set(scanMentionTokens(outboundContent));
+			const missingNames = [];
+			for (const id of mergedMentions) {
+				if (id === senderId) continue;
+				const p = participants.find((q) => q.agentId === id);
+				if (!p?.name) continue;
+				if (present.has(p.name.toLowerCase())) continue;
+				missingNames.push(p.name);
+			}
+			if (missingNames.length > 0) {
+				const prefix = missingNames.map((n) => `@${n}`).join(" ");
+				outboundContent = outboundContent.length > 0 ? `${prefix} ${outboundContent}` : prefix;
+			}
+		}
 		const messageId = randomUUID();
 		const [msg] = await tx.insert(messages).values({
 			id: messageId,
 			chatId,
 			senderId,
 			format: data.format,
-			content: data.content,
+			content: outboundContent,
 			metadata: metadataToStore,
 			replyToInbox: data.replyToInbox ?? null,
 			replyToChat: data.replyToChat ?? null,
@@ -9211,13 +9527,14 @@ async function sendMessageInner(db, chatId, senderId, data) {
 			source: data.source ?? null
 		}).returning();
 		const mentionSet = new Set(mergedMentions);
-		const entries = participants.filter((p) => p.agentId !== senderId).filter((p) => p.mode !== "mention_only" || mentionSet.has(p.agentId)).map((p) => ({
+		const entries = participants.filter((p) => p.agentId !== senderId).map((p) => ({
 			inboxId: p.inboxId,
 			messageId,
-			chatId
+			chatId,
+			notify: p.mode !== "mention_only" || mentionSet.has(p.agentId)
 		}));
 		if (entries.length > 0) await tx.insert(inboxEntries).values(entries);
-		const recipients = entries.map((e) => e.inboxId);
+		const recipients = entries.filter((e) => e.notify).map((e) => e.inboxId);
 		if (data.inReplyTo) {
 			const [original] = await tx.select({
 				replyToInbox: messages.replyToInbox,
@@ -9248,14 +9565,23 @@ async function sendToAgent(db, senderUuid, targetName, data) {
 	if (!sender) throw new NotFoundError(`Agent "${senderUuid}" not found`);
 	const [target] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, sender.organizationId), eq(agents.name, targetName), ne(agents.status, "deleted"))).limit(1);
 	if (!target) throw new NotFoundError(`Agent "${targetName}" not found${/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(targetName) ? " — `agent send` expects an agent NAME, not a uuid. Run `first-tree-hub agent list` to see available names." : ""}`);
-	return sendMessage(db, (await findOrCreateDirectChat(db, senderUuid, target.uuid)).id, senderUuid, {
+	const chat = await findOrCreateDirectChat(db, senderUuid, target.uuid);
+	const incomingMeta = data.metadata ?? {};
+	const existingMentionsRaw = incomingMeta.mentions;
+	const existingMentions = Array.isArray(existingMentionsRaw) ? existingMentionsRaw.filter((m) => typeof m === "string") : [];
+	const mergedMentions = existingMentions.includes(target.uuid) ? existingMentions : [...existingMentions, target.uuid];
+	const metadata = {
+		...incomingMeta,
+		mentions: mergedMentions
+	};
+	return sendMessage(db, chat.id, senderUuid, {
 		format: data.format,
 		content: data.content,
-		metadata: data.metadata,
+		metadata,
 		replyToInbox: data.replyToInbox,
 		replyToChat: data.replyToChat,
 		source: data.source
-	});
+	}, { normalizeMentionsInContent: true });
 }
 async function editMessage(db, chatId, messageId, senderId, data) {
 	const [msg] = await db.select().from(messages).where(eq(messages.id, messageId)).limit(1);
@@ -9516,6 +9842,18 @@ async function adminAgentRoutes(app) {
 			nextCursor: result.nextCursor
 		};
 	});
+	/**
+	* Pre-create availability probe for the web creation form. The caller types
+	* an agent name; we answer whether the POST would succeed (`available: true`)
+	* or why it would fail (`invalid` / `reserved` / `taken`) without actually
+	* inserting a row. The regular POST still validates authoritatively — this is
+	* a pure UX convenience. Scoped to the caller's org, so two orgs can each
+	* have a `coder` without one blocking the other.
+	*/
+	app.get("/names/:name/availability", async (request) => {
+		const scope = memberScope(request);
+		return await checkAgentNameAvailability(app.db, scope.organizationId, request.params.name);
+	});
 	app.post("/", async (request, reply) => {
 		const scope = memberScope(request);
 		const body = createAgentSchema.parse(request.body);
@@ -9987,7 +10325,7 @@ async function adminChatRoutes(app) {
 			...body,
 			source: "hub_ui"
 		});
-		const result = await sendMessage(app.db, chatId, member.agentId, prepared);
+		const result = await sendMessage(app.db, chatId, member.agentId, prepared, { enforceGroupMention: true });
 		notifyRecipients(app.notifier, result.recipients, result.message.id);
 		return reply.status(201).send({
 			id: result.message.id,
@@ -11810,7 +12148,7 @@ async function buildClientMessagePayloadsForInbox(db, inboxId, items) {
 			replyToChat: o.replyToChat
 		});
 	}
-	return items.map(({ entryChatId, message: m }) => ({
+	return items.map(({ entryChatId, message: m, precedingMessages = [] }) => ({
 		id: m.id,
 		chatId: m.chatId,
 		senderId: m.senderId,
@@ -11824,7 +12162,8 @@ async function buildClientMessagePayloadsForInbox(db, inboxId, items) {
 		createdAt: m.createdAt,
 		configVersion: version,
 		recipientMode: modeByChat.get(entryChatId ?? m.chatId) ?? "full",
-		inReplyToSnapshot: m.inReplyTo ? snapshotById.get(m.inReplyTo) ?? null : null
+		inReplyToSnapshot: m.inReplyTo ? snapshotById.get(m.inReplyTo) ?? null : null,
+		precedingMessages
 	}));
 }
 async function resolveAgentId(db, source) {
@@ -11835,6 +12174,7 @@ async function resolveAgentId(db, source) {
 }
 const DEFAULT_INBOX_TIMEOUT_SECONDS = 300;
 const DEFAULT_MAX_RETRY_COUNT = 3;
+const PRECEDING_CONTEXT_WINDOW_SECONDS = 1440 * 60;
 async function pollInbox(db, inboxId, limit) {
 	return withSpan("inbox.deliver", {
 		"inbox.id": inboxId,
@@ -11848,7 +12188,7 @@ async function pollInboxInner(db, inboxId, limit) {
       SET status = 'delivered', delivered_at = NOW()
       WHERE id IN (
         SELECT id FROM inbox_entries
-        WHERE inbox_id = ${inboxId} AND status = 'pending'
+        WHERE inbox_id = ${inboxId} AND status = 'pending' AND notify = true
         ORDER BY created_at
         LIMIT ${limit}
         FOR UPDATE SKIP LOCKED
@@ -11856,6 +12196,8 @@ async function pollInboxInner(db, inboxId, limit) {
       RETURNING *
     `);
 		if (claimed.length === 0) return [];
+		claimed.sort((a, b) => a.created_at.localeCompare(b.created_at));
+		const precedingByEntryId = await collectPrecedingContext(tx, inboxId, claimed);
 		const messageIds = claimed.map((e) => e.message_id);
 		const msgs = await tx.select().from(messages).where(inArray(messages.id, messageIds));
 		const msgMap = new Map(msgs.map((m) => [m.id, m]));
@@ -11864,6 +12206,7 @@ async function pollInboxInner(db, inboxId, limit) {
 			if (!msg) throw new Error(`Unexpected: message ${entry.message_id} not found`);
 			return {
 				entryChatId: entry.chat_id,
+				precedingMessages: precedingByEntryId.get(entry.id) ?? [],
 				message: {
 					id: msg.id,
 					chatId: msg.chatId,
@@ -11897,6 +12240,69 @@ async function pollInboxInner(db, inboxId, limit) {
 		});
 	});
 }
+/**
+* Per claimed trigger: SELECT silent (notify=false) pending rows in the same
+* chat that occurred between the previous trigger in this batch (or beginning
+* of time) and this trigger, capped by `PRECEDING_CONTEXT_MAX_ENTRIES` and
+* `PRECEDING_CONTEXT_WINDOW_SECONDS`. Returned messages are oldest-first.
+*
+* Side effect: bulk-ack ALL silent pending rows in each chat with
+* created_at < latest_trigger.created_at — including ones that fell outside
+* the window/cap. Otherwise stale silent rows would accumulate and re-load
+* on every poll.
+*/
+async function collectPrecedingContext(tx, inboxId, triggers) {
+	const result = /* @__PURE__ */ new Map();
+	const byChat = /* @__PURE__ */ new Map();
+	for (const t of triggers) {
+		if (t.chat_id === null) continue;
+		const list = byChat.get(t.chat_id) ?? [];
+		list.push(t);
+		byChat.set(t.chat_id, list);
+	}
+	for (const [chatId, chatTriggers] of byChat) {
+		chatTriggers.sort((a, b) => a.created_at.localeCompare(b.created_at));
+		let prevCreatedAt = null;
+		for (const trigger of chatTriggers) {
+			const preceding = (await tx.execute(sql`
+        SELECT ie.id, m.id AS message_id, m.sender_id, m.format, m.content, m.metadata,
+               m.created_at
+        FROM inbox_entries ie
+        JOIN messages m ON m.id = ie.message_id
+        WHERE ie.inbox_id = ${inboxId}
+          AND ie.chat_id = ${chatId}
+          AND ie.status = 'pending'
+          AND ie.notify = false
+          AND ie.created_at < ${trigger.created_at}
+          ${prevCreatedAt === null ? sql`` : sql`AND ie.created_at > ${prevCreatedAt}`}
+          AND ie.created_at > NOW() - make_interval(secs => ${PRECEDING_CONTEXT_WINDOW_SECONDS})
+        ORDER BY ie.created_at DESC
+        LIMIT ${50}
+        FOR UPDATE OF ie SKIP LOCKED
+      `)).map((r) => ({
+				id: r.message_id,
+				senderId: r.sender_id,
+				format: r.format,
+				content: r.content,
+				metadata: r.metadata ?? {},
+				createdAt: r.created_at
+			})).reverse();
+			result.set(trigger.id, preceding);
+			prevCreatedAt = trigger.created_at;
+		}
+		const latestTrigger = chatTriggers[chatTriggers.length - 1];
+		if (latestTrigger) await tx.execute(sql`
+        UPDATE inbox_entries
+        SET status = 'acked', acked_at = NOW()
+        WHERE inbox_id = ${inboxId}
+          AND chat_id = ${chatId}
+          AND status = 'pending'
+          AND notify = false
+          AND created_at < ${latestTrigger.created_at}
+      `);
+	}
+	return result;
+}
 async function ackEntry$2(db, entryId, inboxId) {
 	return withSpan("inbox.ack", {
 		[FIRST_TREE_HUB_ATTR.INBOX_ENTRY_ID]: String(entryId),
@@ -11935,6 +12341,49 @@ async function resetTimedOutEntries(db, timeoutSeconds = DEFAULT_INBOX_TIMEOUT_S
 		failed: failedResult.length
 	};
 }
+/** Default age (30 days) past which silent rows that no notify-true delivery
+*  ever picked up are physically deleted. */
+const SILENT_ROW_GC_MAX_AGE_SECONDS = 720 * 60 * 60;
+/**
+* Garbage-collect silent inbox rows so the table doesn't grow forever in
+* chats where a `mention_only` agent is never @mentioned.
+*
+* Two cleanup paths:
+*
+*   1. `notify=false AND status='acked'` of any age — these are fully
+*      consumed (either bundled into a previous trigger or aged out via the
+*      bulk-ack in `collectPrecedingContext`); keep them only as long as
+*      the corresponding message rows we link to. The unique constraint
+*      `(inbox_id, message_id, chat_id)` means leaving them around blocks
+*      legitimate retries with the same key.
+*
+*   2. `notify=false AND status='pending' AND created_at < NOW() - maxAge` —
+*      stale silent rows that no trigger ever caught up with. After 30
+*      days they're useless as preceding context (the @mention almost
+*      certainly already happened or the chat went dormant).
+*
+* Returns the number of rows deleted in each bucket so the background task
+* can log meaningful counts.
+*/
+async function pruneStaleSilentEntries(db, maxAgeSeconds = SILENT_ROW_GC_MAX_AGE_SECONDS) {
+	const ackedResult = await db.execute(sql`
+    DELETE FROM inbox_entries
+    WHERE notify = false
+      AND status = 'acked'
+    RETURNING id
+  `);
+	const staleResult = await db.execute(sql`
+    DELETE FROM inbox_entries
+    WHERE notify = false
+      AND status = 'pending'
+      AND created_at < NOW() - make_interval(secs => ${maxAgeSeconds})
+    RETURNING id
+  `);
+	return {
+		ackedDeleted: ackedResult.length,
+		stalePendingDeleted: staleResult.length
+	};
+}
 async function agentInboxRoutes(app) {
 	app.get("/", async (request) => {
 		const identity = requireAgent(request);
@@ -11982,7 +12431,10 @@ async function agentMessageRoutes(app) {
 		await assertParticipant(app.db, request.params.chatId, identity.uuid);
 		const body = sendMessageSchema.parse(request.body);
 		const prepared = await prepareImageOutbound(app.db, app.notifier, request.params.chatId, body);
-		const { message: msg, recipients } = await sendMessage(app.db, request.params.chatId, identity.uuid, prepared);
+		const { message: msg, recipients } = await sendMessage(app.db, request.params.chatId, identity.uuid, prepared, {
+			enforceGroupMention: true,
+			normalizeMentionsInContent: true
+		});
 		notifyRecipients(app.notifier, recipients, msg.id);
 		return reply.status(201).send({
 			...msg,
@@ -14095,6 +14547,11 @@ function createBackgroundTasks(app, instanceId, adapterManager, kaelRuntime) {
 					const timeoutSeconds = configs.inbox_timeout_seconds ?? 300;
 					const maxRetries = configs.max_retry_count ?? 3;
 					await resetTimedOutEntries(app.db, timeoutSeconds, maxRetries);
+					const pruned = await pruneStaleSilentEntries(app.db);
+					if (pruned.ackedDeleted > 0 || pruned.stalePendingDeleted > 0) log.debug({
+						ackedDeleted: pruned.ackedDeleted,
+						stalePendingDeleted: pruned.stalePendingDeleted
+					}, "pruned silent inbox rows");
 				} catch (err) {
 					log.error({ err }, "failed to reset timed-out inbox entries");
 				}
@@ -15031,7 +15488,7 @@ async function startServer(options) {
 		instanceId: `srv_${randomUUID().slice(0, 8)}`,
 		commandVersion: COMMAND_VERSION
 	};
-	const { initTelemetry, shutdownTelemetry } = await import("./observability-hDEdrmMS.mjs");
+	const { initTelemetry, shutdownTelemetry } = await import("./observability-DDkJwSKv.mjs");
 	await initTelemetry(serverConfig.observability.tracing, config.instanceId);
 	const app = await buildApp(config);
 	const shutdown = async () => {
@@ -15081,175 +15538,6 @@ function resolveWebDist() {
 	} catch {}
 }
 //#endregion
-//#region src/core/service-logs.ts
-const LOG_DIR = join(DEFAULT_HOME_DIR$1, "logs");
-const PRIMARY_LOG = join(LOG_DIR, "client.log");
-const FALLBACK_STDOUT = join(LOG_DIR, "client.stdout.log");
-const FALLBACK_STDERR = join(LOG_DIR, "client.stderr.log");
-/**
-* Duration string → milliseconds. Accepts `10s`, `5m`, `2h`, `1d`; rejects
-* everything else. Keeps the parser tiny rather than pulling in a library —
-* the `--since` flag is the only consumer.
-*/
-function parseDuration(input) {
-	const match = /^(\d+)\s*(s|m|h|d)$/.exec(input.trim());
-	if (!match) throw new Error(`invalid duration "${input}" (expected e.g. 30s, 5m, 2h, 1d)`);
-	return Number(match[1]) * ({
-		s: 1e3,
-		m: 6e4,
-		h: 36e5,
-		d: 864e5
-	}[match[2]] ?? 0);
-}
-const LEVEL_RANK = {
-	trace: 10,
-	debug: 20,
-	info: 30,
-	warn: 40,
-	error: 50,
-	fatal: 60
-};
-/** Rotated log files, newest-first. Missing files are silently skipped. */
-function listLogFilesNewestFirst() {
-	const files = [];
-	if (existsSync(PRIMARY_LOG)) files.push(PRIMARY_LOG);
-	for (let i = 1;; i++) {
-		const p = `${PRIMARY_LOG}.${i}`;
-		if (!existsSync(p)) break;
-		files.push(p);
-	}
-	return files;
-}
-/** Supervisor fallback files (raw stdout/stderr, not NDJSON). Missing files skipped. */
-function listFallbackFiles() {
-	const files = [];
-	if (existsSync(FALLBACK_STDERR)) files.push(FALLBACK_STDERR);
-	if (existsSync(FALLBACK_STDOUT)) files.push(FALLBACK_STDOUT);
-	return files;
-}
-function matchesFilters(obj, minLevel, cutoffMs) {
-	if (minLevel !== void 0) {
-		const lvl = typeof obj.level === "number" ? obj.level : NaN;
-		if (!Number.isFinite(lvl) || lvl < minLevel) return false;
-	}
-	if (cutoffMs !== void 0) {
-		const t = parseLogTime(obj.time);
-		if (t === null || t < cutoffMs) return false;
-	}
-	return true;
-}
-/** Logger writes `time` as a local-ish string (`YYYY-MM-DD HH:mm:ss`). */
-function parseLogTime(value) {
-	if (typeof value === "number") return value;
-	if (typeof value !== "string") return null;
-	const iso = value.replace(" ", "T");
-	const ms = Date.parse(iso);
-	return Number.isFinite(ms) ? ms : null;
-}
-function renderLine(line, json) {
-	if (!line.trim()) return null;
-	if (json) return `${line}\n`;
-	try {
-		return formatPrettyEntry$1(line);
-	} catch {
-		return `${line}\n`;
-	}
-}
-function processLogLine(line, minLevel, cutoffMs, json) {
-	let obj;
-	try {
-		obj = JSON.parse(line);
-	} catch {
-		return json ? null : `${line}\n`;
-	}
-	if (!matchesFilters(obj, minLevel, cutoffMs)) return null;
-	return renderLine(line, json);
-}
-async function readFileLines(path, minLevel, cutoffMs, json) {
-	const rl = createInterface({ input: createReadStream(path, { encoding: "utf8" }) });
-	for await (const line of rl) {
-		const rendered = processLogLine(line, minLevel, cutoffMs, json);
-		if (rendered) process.stdout.write(rendered);
-	}
-}
-/**
-* Read a supervisor fallback file (launchd / systemd stdout/stderr capture).
-* These are plain text, not NDJSON: level and time filters don't apply, so we
-* honour `--since` by dropping the whole file when its mtime predates the
-* cutoff and otherwise pass every line through. In pretty mode each line is
-* tagged with the source so operators can tell it apart from pino output; in
-* `--json` mode we emit a synthetic record so NDJSON consumers keep one
-* object per line.
-*/
-async function readFallbackFile(path, cutoffMs, json) {
-	try {
-		const mtime = statSync(path).mtimeMs;
-		if (cutoffMs !== void 0 && mtime < cutoffMs) return;
-	} catch {
-		return;
-	}
-	const source = path.endsWith(".stderr.log") ? "supervisor:stderr" : "supervisor:stdout";
-	const rl = createInterface({ input: createReadStream(path, { encoding: "utf8" }) });
-	for await (const line of rl) {
-		if (!line.trim()) continue;
-		if (json) process.stdout.write(`${JSON.stringify({
-			source,
-			line
-		})}\n`);
-		else process.stdout.write(`[${source}] ${line}\n`);
-	}
-}
-/**
-* Print existing log history, applying filters. `--tail` then switches to
-* follow mode and keeps printing new lines as the active file grows; rotation
-* is not handled during the tail (a follow-up rotation will simply stop
-* emitting new lines — operator can re-run the command).
-*/
-async function showServiceLogs(options) {
-	if (!existsSync(LOG_DIR)) {
-		print.status("logs", `directory not found: ${LOG_DIR}`);
-		return;
-	}
-	const minLevel = options.level ? LEVEL_RANK[options.level] : void 0;
-	const cutoffMs = options.sinceMs !== void 0 ? Date.now() - options.sinceMs : void 0;
-	for (const f of listFallbackFiles()) await readFallbackFile(f, cutoffMs, options.json);
-	const files = listLogFilesNewestFirst().reverse();
-	for (const f of files) await readFileLines(f, minLevel, cutoffMs, options.json);
-	if (!options.tail) return;
-	if (!existsSync(PRIMARY_LOG)) print.status("tail", "waiting for client.log to appear...");
-	await new Promise((resolve) => {
-		let position = existsSync(PRIMARY_LOG) ? statSync(PRIMARY_LOG).size : 0;
-		const onChange = () => {
-			if (!existsSync(PRIMARY_LOG)) return;
-			const current = statSync(PRIMARY_LOG).size;
-			if (current < position) position = 0;
-			if (current <= position) return;
-			const stream = createReadStream(PRIMARY_LOG, {
-				start: position,
-				end: current - 1,
-				encoding: "utf8"
-			});
-			position = current;
-			createInterface({ input: stream }).on("line", (line) => {
-				const rendered = processLogLine(line, minLevel, cutoffMs, options.json);
-				if (rendered) process.stdout.write(rendered);
-			});
-		};
-		watchFile(PRIMARY_LOG, { interval: 500 }, onChange);
-		process.once("SIGINT", () => {
-			unwatchFile(PRIMARY_LOG, onChange);
-			resolve();
-		});
-	});
-}
-/** Validated flag parsers the CLI layer can reuse without re-doing the work. */
-function validateLevel(value) {
-	if (value === void 0) return void 0;
-	const parsed = parseLogLevel$1(value);
-	if (parsed.fellBack) throw new Error(`invalid --level "${value}" (expected one of ${LOG_LEVELS$1.join(", ")})`);
-	return parsed.level;
-}
-//#endregion
 //#region src/core/update.ts
 const PACKAGE_NAME = "@agent-team-foundation/first-tree-hub";
 /**
@@ -15426,4 +15714,4 @@ function createExecuteUpdate({ managed }) {
 	};
 }
 //#endregion
-export { configureClientLoggerForService as $, checkServerHealth as A, createOwner as B, runMigrations as C, checkDocker as D, checkDatabase as E, isDockerAvailable as F, setJsonMode as G, resolveReplyToFromEnv as H, stopPostgres as I, FirstTreeHubSDK as J, status as K, ClientRuntime as L, checkWebSocket as M, printResults as N, checkNodeVersion as O, ensurePostgres as P, applyClientLoggerConfig as Q, handleClientOrgMismatch as R, uninstallClientService as S, checkClientConfig as T, blank as U, hasUser as V, print as W, SessionRegistry as X, SdkError as Y, cleanWorkspaces as Z, runHomeMigration as _, showServiceLogs as a, isServiceSupported as b, COMMAND_VERSION as c, promptMissingFields as d, formatCheckReport as f, saveOnboardState as g, onboardCreate as h, parseDuration as i, checkServerReachable as j, checkServerConfig as k, isInteractive as l, onboardCheck as m, declineUpdate as n, validateLevel as o, loadOnboardState as p, ClientOrgMismatchError$1 as q, promptUpdate as r, startServer as s, createExecuteUpdate as t, promptAddAgent as u, getClientServiceStatus as v, checkAgentConfigs as w, resolveCliInvocation as x, installClientService as y, rotateClientIdWithBackup as z };
+export { configureClientLoggerForService as $, installClientService as A, createOwner as B, checkNodeVersion as C, checkWebSocket as D, checkServerReachable as E, isDockerAvailable as F, setJsonMode as G, resolveReplyToFromEnv as H, stopPostgres as I, FirstTreeHubSDK as J, status as K, ClientRuntime as L, resolveCliInvocation as M, uninstallClientService as N, printResults as O, ensurePostgres as P, applyClientLoggerConfig as Q, handleClientOrgMismatch as R, checkDocker as S, checkServerHealth as T, blank as U, hasUser as V, print as W, SessionRegistry as X, SdkError as Y, cleanWorkspaces as Z, runMigrations as _, COMMAND_VERSION as a, checkClientConfig as b, promptMissingFields as c, onboardCheck as d, onboardCreate as f, migrateLocalAgentDirs as g, createApiNameResolver as h, startServer as i, isServiceSupported as j, getClientServiceStatus as k, formatCheckReport as l, runHomeMigration as m, declineUpdate as n, isInteractive as o, saveOnboardState as p, ClientOrgMismatchError$1 as q, promptUpdate as r, promptAddAgent as s, createExecuteUpdate as t, loadOnboardState as u, checkAgentConfigs as v, checkServerConfig as w, checkDatabase as x, checkBackgroundService as y, rotateClientIdWithBackup as z };