@agent-team-foundation/first-tree-hub 0.8.6 → 0.9.1

package/dist/{core-e1-NPfEC.mjs → core-DzuW7b5v.mjs}

@@ -1,7 +1,8 @@
 import { f as __require, l as __commonJSMin, m as __toESM } from "./esm-CYu4tXXn.mjs";
-import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, x as resolveConfigReadonly } from "./bootstrap-99vUYmLs.mjs";
+import { 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-CWcBzk6C.mjs";
 import { _ as withSpan, a as endWsConnectionSpan, b as require_pino, c as messageAttrs, d as rootLogger$1, g as startWsConnectionSpan, i as currentTraceId, n as applyLoggerConfig, o as getFastifyOtelPlugin, p as setWsConnectionAttrs, r as createLogger, t as adapterAttrs, u as observabilityPlugin, v as withWsMessageSpan, y as FIRST_TREE_HUB_ATTR } from "./observability-CJzDFY_G-CmvgUuzc.mjs";
-import { $ as updateAdapterConfigSchema, A as createMemberSchema, B as notificationQuerySchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as inboxPollQuerySchema, G as sendMessageSchema, H as refreshTokenSchema, I as isRedactedEnvValue, J as sessionEventMessageSchema, K as sendToAgentSchema, L as linkTaskChatSchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as taskListQuerySchema, R as loginSchema, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as runtimeStateMessageSchema, V as paginationQuerySchema, W as selfServiceFeishuBotSchema, X as sessionReconcileRequestSchema, Y as sessionEventSchema$1, Z as sessionStateMessageSchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as updateSystemConfigSchema, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateAgentRuntimeConfigSchema, 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 updateOrganizationSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateChatSchema, o as AGENT_SOURCES, ot as updateTaskStatusSchema, p as TASK_HEALTH_SIGNALS, q as sessionCompletionMessageSchema, rt as updateMemberSchema, s as AGENT_STATUSES, st as wsAuthFrameSchema, tt as updateAgentSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as messageSourceSchema$1 } from "./feishu-n9Y2yGTT.mjs";
+import { $ as updateAdapterConfigSchema, A as createMemberSchema, B as notificationQuerySchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as inboxPollQuerySchema, G as sendMessageSchema, H as refreshTokenSchema, I as isRedactedEnvValue, J as sessionEventMessageSchema, K as sendToAgentSchema, L as linkTaskChatSchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as taskListQuerySchema, R as loginSchema, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as runtimeStateMessageSchema, V as paginationQuerySchema, W as selfServiceFeishuBotSchema, X as sessionReconcileRequestSchema, Y as sessionEventSchema$1, Z as sessionStateMessageSchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as updateSystemConfigSchema, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateAgentRuntimeConfigSchema, 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 updateOrganizationSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateChatSchema, o as AGENT_SOURCES, ot as updateTaskStatusSchema, p as TASK_HEALTH_SIGNALS, q as sessionCompletionMessageSchema, rt as updateMemberSchema, s as AGENT_STATUSES, st as wsAuthFrameSchema, tt as updateAgentSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as messageSourceSchema$1 } from "./feishu-GlaczcVf.mjs";
+import { createRequire } from "node:module";
 import { copyFileSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync } from "node:fs";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { ZodError, z } from "zod";
@@ -13,13 +14,14 @@ import { EventEmitter } from "node:events";
 import WebSocket from "ws";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
+import * as semver from "semver";
 import bcrypt from "bcrypt";
 import { and, asc, count, desc, eq, gt, inArray, isNotNull, isNull, lt, ne, or, sql } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import { fileURLToPath } from "node:url";
 import { migrate } from "drizzle-orm/postgres-js/migrator";
-import { input, password, select } from "@inquirer/prompts";
+import { confirm, input, password, select } from "@inquirer/prompts";
 import cors from "@fastify/cors";
 import rateLimit from "@fastify/rate-limit";
 import fastifyStatic from "@fastify/static";
@@ -959,6 +961,18 @@ z.object({
 	type: z.literal("auth"),
 	token: z.string().min(1)
 });
+/**
+* Advisory frame sent server → client immediately after `auth:ok`. It carries
+* the Command-package version the server was bundled with, so the client can
+* detect version drift on startup and on each reconnect. `.passthrough()` so
+* future server versions may add fields without breaking older clients that
+* validate this frame.
+*/
+const serverWelcomeFrameSchema = z.object({
+	type: z.literal("server:welcome"),
+	serverCommandVersion: z.string().min(1),
+	serverTimeMs: z.number().int().nonnegative()
+}).passthrough();
 const FETCH_TIMEOUT_MS = 15e3;
 var FirstTreeHubSDK = class {
 	_baseUrl;
@@ -1132,6 +1146,8 @@ var ClientConnection = class extends EventEmitter {
 	reconnectAttempt = 0;
 	closing = false;
 	registered = false;
+	/** Count of `server:welcome` frames received; drives `isReconnect` flag. */
+	welcomeFramesReceived = 0;
 	boundAgents = /* @__PURE__ */ new Map();
 	/** Agents scheduled to rebind automatically on every reconnect. */
 	desiredBindings = /* @__PURE__ */ new Map();
@@ -1324,6 +1340,20 @@ var ClientConnection = class extends EventEmitter {
 			}));
 			return;
 		}
+		if (type === "server:welcome") {
+			const parsed = serverWelcomeFrameSchema.safeParse(msg);
+			if (!parsed.success) {
+				process.stderr.write(`[ClientConnection] Ignoring malformed server:welcome frame: ${parsed.error.issues.map((i) => i.message).join(", ")}\n`);
+				return;
+			}
+			const isReconnect = this.welcomeFramesReceived > 0;
+			this.welcomeFramesReceived++;
+			this.emit("server:welcome", {
+				frame: parsed.data,
+				isReconnect
+			});
+			return;
+		}
 		if (type === "auth:rejected" || type === "auth:expired") {
 			if (type === "auth:expired") this.emit("auth:expired");
 			this.ws?.close(4401, type);
@@ -1552,6 +1582,24 @@ defineConfig({
 		max_sessions: field(z.number().int().positive().default(10))
 	}
 });
+/**
+* Phase-dependent defaults that flip with release milestones. Kept as a plain
+* module-level constant so reviews of the beta→GA transition are a one-line
+* diff, and so tests can mock this module to exercise both branches.
+*/
+const UPDATE_POLICIES = [
+	"auto",
+	"prompt",
+	"off"
+];
+/**
+* Default value of `update.policy` on the Client config. During the beta this
+* is `"auto"` — operators rarely know to `npm i -g` weekly and we chase the
+* latest published Command by default. The GA PR flips it to `"prompt"` and
+* bumps Command to `1.0.0`.
+*/
+const UPDATE_POLICY_DEFAULT = "auto";
+const updatePolicySchema = z.enum(UPDATE_POLICIES);
 defineConfig({
 	server: { url: field(z.string(), {
 		env: "FIRST_TREE_HUB_SERVER_URL",
@@ -1564,11 +1612,18 @@ defineConfig({
 		auto: "client-id",
 		env: "FIRST_TREE_HUB_CLIENT_ID"
 	}) },
+	update: {
+		policy: field(updatePolicySchema.default(UPDATE_POLICY_DEFAULT), { env: "FIRST_TREE_HUB_UPDATE_POLICY" }),
+		restart_quiet_seconds: field(z.number().int().min(1).max(3600).default(30), { env: "FIRST_TREE_HUB_UPDATE_RESTART_QUIET_SECONDS" }),
+		restart_check_interval_seconds: field(z.number().int().min(5).max(300).default(10), { env: "FIRST_TREE_HUB_UPDATE_RESTART_CHECK_INTERVAL_SECONDS" }),
+		prompt_timeout_seconds: field(z.number().int().min(10).max(600).default(60), { env: "FIRST_TREE_HUB_UPDATE_PROMPT_TIMEOUT_SECONDS" })
+	},
 	logLevel: field(logLevelSchema.default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" })
 });
-const DEFAULT_HOME_DIR = process.env.FIRST_TREE_HUB_HOME ?? join(homedir(), ".first-tree-hub");
+const DEFAULT_HOME_DIR = process.env.FIRST_TREE_HUB_HOME ?? join(homedir(), ".first-tree", "hub");
 join(DEFAULT_HOME_DIR, "config");
 const DEFAULT_DATA_DIR = join(DEFAULT_HOME_DIR, "data");
+join(homedir(), ".first-tree-hub");
 defineConfig({
 	database: {
 		url: field(z.string(), {
@@ -3235,6 +3290,20 @@ var SessionManager = class {
 	get totalCount() {
 		return this.sessions.size;
 	}
+	/**
+	* Snapshot used by the UpdateManager's quiet gate to decide whether it is
+	* safe to exit the process for a self-update. `activeCount` is the number of
+	* sessions currently handling a message; `lastActivityMs` is the most recent
+	* activity timestamp across all tracked sessions (0 when there are none).
+	*/
+	getQuietGateSnapshot() {
+		let lastActivityMs = 0;
+		for (const entry of this.sessions.values()) if (entry.lastActivity > lastActivityMs) lastActivityMs = entry.lastActivity;
+		return {
+			activeCount: this._activeCount,
+			lastActivityMs
+		};
+	}
 	/** Return the current aggregate runtime state, or null if no sessions have reported. */
 	getAggregateRuntimeState() {
 		return this.lastReportedRuntimeState;
@@ -3558,6 +3627,17 @@ var AgentSlot = class {
 	get clientConnection() {
 		return this.config.clientConnection;
 	}
+	/**
+	* Snapshot of this slot's busy/idle state used by the UpdateManager's
+	* quiet gate. Returns zeros before `start()` has built the session manager,
+	* which is the same semantics: idle.
+	*/
+	getQuietGateSnapshot() {
+		return this.sessionManager?.getQuietGateSnapshot() ?? {
+			activeCount: 0,
+			lastActivityMs: 0
+		};
+	}
 	async start(contextTreePath) {
 		const sdk = (await this.clientConnection.bindAgent(this.config.agentId, this.config.runtimeType ?? this.config.type, this.config.runtimeVersion)).sdk;
 		this.sdk = sdk;
@@ -3741,6 +3821,147 @@ z.object({
 	server: z.url().default("http://localhost:8000"),
 	agents: z.record(z.string(), agentSlotConfigSchema).refine((agents) => Object.keys(agents).length > 0, "At least one agent must be defined")
 });
+/**
+* Version-drift decision flow. Install, prompt, and exit are delegated to
+* command-layer callbacks so the Client package stays free of CLI /
+* filesystem knowledge.
+*/
+var UpdateManager = class UpdateManager {
+	options;
+	connection;
+	welcomeListener;
+	updateInFlight = false;
+	quietGateTimer = null;
+	disposed = false;
+	/**
+	* Set when a standalone (unmanaged) executeUpdate reports `installed: true`
+	* without exiting. The new bits are on disk; subsequent welcome frames must
+	* not re-invoke npm since a restart is the only way to pick them up.
+	*/
+	pendingRestart = false;
+	constructor(connection, options) {
+		this.connection = connection;
+		this.options = options;
+		this.welcomeListener = (welcome) => {
+			this.onWelcome(welcome).catch((err) => {
+				const msg = err instanceof Error ? err.message : String(err);
+				this.options.log("warn", `update decision failed: ${msg}`);
+			});
+		};
+	}
+	/** Attach a manager to a connection. Returns the instance so callers can dispose. */
+	static attach(connection, options) {
+		const mgr = new UpdateManager(connection, options);
+		connection.on("server:welcome", mgr.welcomeListener);
+		return mgr;
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.connection.off("server:welcome", this.welcomeListener);
+		if (this.quietGateTimer) {
+			clearTimeout(this.quietGateTimer);
+			this.quietGateTimer = null;
+		}
+	}
+	async onWelcome(welcome) {
+		if (this.disposed || this.updateInFlight || this.pendingRestart) return;
+		this.updateInFlight = true;
+		try {
+			await this.decide(welcome);
+		} finally {
+			this.updateInFlight = false;
+		}
+	}
+	async decide(welcome) {
+		const { serverCommandVersion: target } = welcome.frame;
+		const current = this.options.currentVersion;
+		if (!semver.valid(target)) {
+			this.options.log("warn", `Server advertised invalid version "${target}"; skipping drift check`);
+			return;
+		}
+		if (!semver.valid(current)) {
+			this.options.log("warn", `Own version "${current}" is not valid SemVer; skipping drift check`);
+			return;
+		}
+		if (semver.eq(target, current)) {
+			this.options.log("debug", `Server advertises ${target}, matching running version`);
+			return;
+		}
+		if (semver.lt(target, current)) {
+			this.options.log("info", `Server advertises ${target}, running ${current} (ahead)`);
+			return;
+		}
+		const policy = this.options.updateConfig.policy;
+		if (policy === "off") {
+			this.options.log("info", `Server advertises ${target}, running ${current}; self-update disabled (policy=off)`);
+			return;
+		}
+		if (policy === "prompt") {
+			if (!this.options.isTTY) {
+				this.options.log("warn", `Update available (${current} → ${target}) but policy=prompt requires a terminal; operator action required`);
+				return;
+			}
+			if (!await this.options.prompt({
+				currentVersion: current,
+				targetVersion: target,
+				timeoutSeconds: this.options.updateConfig.prompt_timeout_seconds
+			})) {
+				this.options.log("info", `Update declined by operator (still running ${current})`);
+				return;
+			}
+			await this.runUpdate(current, target);
+			return;
+		}
+		this.options.log("info", `Server advertises ${target}, running ${current}; policy=auto`);
+		if (this.options.isTTY) {
+			this.options.log("info", "Auto-update starting in 5s");
+			await sleep(5e3);
+			if (this.disposed) return;
+		}
+		if (welcome.isReconnect) {
+			await this.waitForQuietGate();
+			if (this.disposed) return;
+		}
+		await this.runUpdate(current, target);
+	}
+	async waitForQuietGate() {
+		const quietMs = this.options.updateConfig.restart_quiet_seconds * 1e3;
+		const intervalMs = this.options.updateConfig.restart_check_interval_seconds * 1e3;
+		while (!this.disposed) {
+			const snapshot = this.options.getQuietGateSnapshot();
+			const now = Date.now();
+			const idleFor = snapshot.lastActivityMs === 0 ? Number.POSITIVE_INFINITY : now - snapshot.lastActivityMs;
+			if (snapshot.activeCount === 0 && idleFor >= quietMs) return;
+			this.options.log("debug", `Quiet gate: activeCount=${snapshot.activeCount}, idleFor=${Math.round(idleFor)}ms; re-checking in ${intervalMs}ms`);
+			await new Promise((resolve) => {
+				this.quietGateTimer = setTimeout(() => {
+					this.quietGateTimer = null;
+					resolve();
+				}, intervalMs);
+			});
+		}
+	}
+	async runUpdate(current, target) {
+		try {
+			if ((await this.options.executeUpdate({
+				currentVersion: current,
+				targetVersion: target
+			})).installed) {
+				this.pendingRestart = true;
+				this.options.log("info", `Update ${target} installed; restart required to pick it up (no further self-update attempts until restart)`);
+				return;
+			}
+			this.options.log("warn", "Self-update did not complete; will retry on next welcome frame");
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			this.options.log("warn", `Self-update threw: ${msg}`);
+		}
+	}
+};
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
 //#endregion
 //#region src/core/admin.ts
 /**
@@ -3841,6 +4062,8 @@ var ClientRuntime = class {
 	agents = [];
 	agentNames = /* @__PURE__ */ new Set();
 	agentIds = /* @__PURE__ */ new Set();
+	options;
+	updateManager = null;
 	watcher = null;
 	debounceTimer = null;
 	/**
@@ -3849,11 +4072,13 @@ var ClientRuntime = class {
 	* `agent:pinned` handler knows where to materialise new configs.
 	*/
 	agentsDir = null;
-	constructor(serverUrl, clientId) {
+	constructor(serverUrl, clientId, options = {}) {
 		this.serverUrl = serverUrl;
+		this.options = options;
 		this.connection = new ClientConnection({
 			serverUrl,
 			clientId,
+			sdkVersion: options.currentVersion,
 			getAccessToken: () => ensureFreshAccessToken()
 		});
 		registerBuiltinHandlers();
@@ -3892,6 +4117,13 @@ var ClientRuntime = class {
 		this.agentIds.add(config.agentId);
 	}
 	async start() {
+		if (this.options.currentVersion && this.options.update) this.updateManager = UpdateManager.attach(this.connection, {
+			currentVersion: this.options.currentVersion,
+			...this.options.update,
+			isTTY: Boolean(process.stdout.isTTY),
+			log: (level, msg) => process.stderr.write(`  [update/${level}] ${msg}\n`),
+			getQuietGateSnapshot: () => this.aggregateQuietGate()
+		});
 		await this.connection.connect();
 		process.stderr.write(`  \u2713 Client registered: ${this.connection.clientId}\n`);
 		if (this.agents.length === 0) {
@@ -3935,9 +4167,24 @@ var ClientRuntime = class {
 	}
 	async stop() {
 		this.unwatchAgentsDir();
+		this.updateManager?.dispose();
+		this.updateManager = null;
 		await Promise.allSettled(this.agents.map((a) => a.slot.stop()));
 		await this.connection.disconnect();
 	}
+	aggregateQuietGate() {
+		let activeCount = 0;
+		let lastActivityMs = 0;
+		for (const entry of this.agents) {
+			const snap = entry.slot.getQuietGateSnapshot();
+			activeCount += snap.activeCount;
+			if (snap.lastActivityMs > lastActivityMs) lastActivityMs = snap.lastActivityMs;
+		}
+		return {
+			activeCount,
+			lastActivityMs
+		};
+	}
 	scanForNewAgents(agentsDir) {
 		try {
 			const all = loadAgents({
@@ -4506,136 +4753,570 @@ async function runMigrations(databaseUrl) {
 	}
 }
 //#endregion
-//#region src/core/onboard.ts
-const STATE_FILE = join(DEFAULT_HOME_DIR$1, ".onboard-state.json");
-/** Save current onboard args to state file for resume. */
-function saveOnboardState(args) {
-	mkdirSync(DEFAULT_HOME_DIR$1, { recursive: true });
-	writeFileSync(STATE_FILE, JSON.stringify({ args }, null, 2));
+//#region src/core/service-install.ts
+/**
+* Run a subprocess capturing stderr so failures surface a meaningful error
+* instead of Node's opaque "Command failed". Used for launchctl/systemctl —
+* anywhere the stderr message is diagnostically crucial.
+*/
+function runCapture(program, args, timeoutMs) {
+	const res = spawnSync(program, args, {
+		encoding: "utf-8",
+		timeout: timeoutMs,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (res.status === 0) return { ok: true };
+	return {
+		ok: false,
+		stderr: (res.stderr ?? "").trim(),
+		code: res.status
+	};
 }
-/** Load saved onboard args from state file. */
-function loadOnboardState() {
+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 JSON.parse(readFileSync(STATE_FILE, "utf-8")).args;
+		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;
 	}
 }
-async function onboardCheck(args) {
-	const items = [];
-	const creds = loadCredentials();
-	if (creds) items.push({
-		key: "connect",
-		label: "Signed in",
-		status: "ok",
-		value: creds.serverUrl
-	});
-	else items.push({
-		key: "connect",
-		label: "Signed in",
-		status: "missing_required",
-		hint: "Run `first-tree-hub client connect <server-url>` first"
-	});
-	try {
-		const serverUrl = resolveServerUrl(args.server);
-		items.push({
-			key: "server",
-			label: "Server URL",
-			status: "ok",
-			value: serverUrl
-		});
-		try {
-			const res = await fetch(`${serverUrl}/api/v1/health`);
-			items.push({
-				key: "server_reachable",
-				label: "Server reachable",
-				status: res.ok ? "ok" : "error",
-				value: res.ok ? "healthy" : `HTTP ${res.status}`
-			});
-		} catch {
-			items.push({
-				key: "server_reachable",
-				label: "Server reachable",
-				status: "error",
-				hint: "Cannot connect to server"
-			});
-		}
+/**
+* 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 {
+			kind: "bin",
+			program: realpathSync(bin)
+		};
 	} catch {
-		items.push({
-			key: "server",
-			label: "Server URL",
-			status: "missing_required",
-			hint: "Provide via --server, FIRST_TREE_HUB_SERVER_URL, or config"
-		});
-	}
-	if (args.id) items.push({
-		key: "id",
-		label: "Agent ID",
-		status: "ok",
-		value: args.id
-	});
-	else items.push({
-		key: "id",
-		label: "Agent ID",
-		status: "missing_required",
-		hint: "Provide via --id"
-	});
-	if (args.type) items.push({
-		key: "type",
-		label: "Agent type",
-		status: "ok",
-		value: args.type
-	});
-	else items.push({
-		key: "type",
-		label: "Agent type",
-		status: "missing_required",
-		hint: "Provide via --type"
-	});
-	if (args.type && args.type !== "human") if (args.clientId) items.push({
-		key: "client",
-		label: "Target client",
-		status: "ok",
-		value: args.clientId
-	});
-	else items.push({
-		key: "client",
-		label: "Target client",
-		status: "ok",
-		value: "(unbound — claimed on first WS connect)"
-	});
-	return items;
-}
-function formatCheckReport(items) {
-	const lines = [];
-	for (const item of items) {
-		const icon = item.status === "ok" ? "✅" : item.status === "missing_required" ? "❌" : item.status === "error" ? "❌" : item.status === "warning" ? "⚠️" : "⬜";
-		const valueStr = item.value ? `  ${item.value}` : "";
-		const hintStr = item.hint ? `  (${item.hint})` : "";
-		lines.push(`  ${icon} ${item.label.padEnd(20)}${valueStr}${hintStr}`);
+		return {
+			kind: "bin",
+			program: bin
+		};
 	}
-	return lines.join("\n");
+	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]
+	};
 }
-async function createAgentViaAdmin(serverUrl, accessToken, body) {
-	const res = await fetch(`${serverUrl}/api/v1/admin/agents`, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${accessToken}`,
-			"Content-Type": "application/json"
-		},
-		body: JSON.stringify(body),
-		signal: AbortSignal.timeout(1e4)
+function ensureLogDir() {
+	mkdirSync(LOG_DIR, {
+		recursive: true,
+		mode: 448
 	});
-	if (!res.ok) {
-		const errBody = await res.json().catch(() => ({}));
-		throw new Error(errBody.error ?? `Failed to create agent (HTTP ${res.status})`);
-	}
-	return await res.json();
 }
-async function onboardCreate(args) {
-	const serverUrl = resolveServerUrl(args.server).replace(/\/+$/, "");
-	const accessToken = await ensureFreshAccessToken();
-	const metadata = {};
+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 outLog = join(LOG_DIR, "client.out.log");
+	const errLog = join(LOG_DIR, "client.err.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>
+  </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(outLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(errLog)}</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"
+	};
+	const out = res.stdout ?? "";
+	const stateLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("state ="));
+	const pidLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("pid ="));
+	if (stateLine?.includes("running")) {
+		const pid = pidLine?.split("=")[1]?.trim();
+		return {
+			state: "active",
+			detail: pid ? `pid ${pid}` : "running"
+		};
+	}
+	return {
+		state: "inactive",
+		detail: stateLine?.trim() ?? "loaded"
+	};
+}
+/**
+* Poll `launchctl print` until the label disappears, confirming launchd has
+* finished the async eviction kicked off by `bootout`. Required because
+* `bootout` returns before the actual unload completes when the service has
+* active WebSocket connections — a follow-up `bootstrap` against a still-
+* registered label fails with `Bootstrap failed: 5: Input/output error`.
+*/
+function waitForLabelEvicted(target, label, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (spawnSync("launchctl", ["print", `${target}/${label}`], {
+			encoding: "utf-8",
+			timeout: 2e3,
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			]
+		}).status !== 0) return true;
+		sleepSync(200);
+	}
+	return false;
+}
+function installLaunchd() {
+	const invocation = resolveCliInvocation();
+	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)) process.stderr.write(`    warning: launchctl bootout: ${bootoutRes.stderr || `exit ${bootoutRes.code ?? "unknown"}`}\n`);
+	}
+	waitForLabelEvicted(target, LAUNCHD_LABEL, 1e4);
+	let lastBootstrapErr = null;
+	for (let attempt = 1; attempt <= 2; attempt++) {
+		const res = runCapture("launchctl", [
+			"bootstrap",
+			target,
+			plistPath
+		], 1e4);
+		if (res.ok) {
+			lastBootstrapErr = null;
+			break;
+		}
+		lastBootstrapErr = res;
+		if (attempt < 2) sleepSync(1e3);
+	}
+	if (lastBootstrapErr) throw new Error(`launchctl bootstrap failed: ${lastBootstrapErr.stderr || `exit ${lastBootstrapErr.code ?? "unknown"}`}\n    Command: launchctl bootstrap ${target} ${plistPath}\n    Recovery: \`launchctl bootout ${target}/${LAUNCHD_LABEL}\` then \`first-tree-hub service install\`.`);
+	const enableRes = runCapture("launchctl", ["enable", `${target}/${LAUNCHD_LABEL}`], 5e3);
+	if (!enableRes.ok) process.stderr.write(`    warning: launchctl enable: ${enableRes.stderr || `exit ${enableRes.code ?? "unknown"}`}\n`);
+	const { state, detail } = launchdState();
+	return {
+		platform: "launchd",
+		label: LAUNCHD_LABEL,
+		unitPath: plistPath,
+		logDir: LOG_DIR,
+		state,
+		detail
+	};
+}
+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)) process.stderr.write(`    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"
+	};
+}
+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, "client.out.log")}
+StandardError=append:${join(LOG_DIR, "client.err.log")}
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+
+[Install]
+WantedBy=default.target
+`;
+}
+function shellQuote(value) {
+	if (/^[A-Za-z0-9_\-./:=]+$/.test(value)) return value;
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+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"
+	};
+}
+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,
+		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)) process.stderr.write(`    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) process.stderr.write(`    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"
+	};
+}
+/** Is background-service install supported on the current platform? */
+function isServiceSupported() {
+	return process.platform === "darwin" || process.platform === "linux";
+}
+/**
+* Install the background service for the current platform.
+*
+* @throws {Error} if the platform is not supported or the service manager fails.
+*/
+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 {
+			platform: "launchd",
+			label: LAUNCHD_LABEL,
+			unitPath: launchdPlistPath(),
+			logDir: LOG_DIR,
+			state,
+			detail
+		};
+	}
+	if (process.platform === "linux") {
+		const { state, detail } = systemdState();
+		return {
+			platform: "systemd",
+			label: SYSTEMD_UNIT,
+			unitPath: systemdUnitPath(),
+			logDir: LOG_DIR,
+			state,
+			detail
+		};
+	}
+	return {
+		platform: "unsupported",
+		label: "",
+		unitPath: "",
+		logDir: LOG_DIR,
+		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();
+}
+//#endregion
+//#region src/core/migrate-home.ts
+/**
+* Run the one-shot legacy home migration at CLI startup and, if it succeeds,
+* re-register the background service so launchd/systemd pick up the new
+* `StandardOutPath` / `StandardErrorPath` / `ExecStart` log paths (those are
+* baked into the plist/unit file at install time — when we populate the new
+* home, those paths would otherwise still point at the old location).
+*
+* Copy-only semantics: the legacy `~/.first-tree-hub/` tree is preserved
+* as a safety net. The user can inspect/fall-back to it, and can delete it
+* manually once they've confirmed the new layout is healthy.
+*
+* Contract:
+*   - Synchronous and cheap when there's nothing to do (most runs — the
+*     steady state is "new dir populated", which short-circuits the copy).
+*   - Never throws — migration failures and service re-register failures
+*     both fall through to a stderr warning so the CLI command still runs.
+*   - Idempotent — safe to call on every CLI invocation.
+*   - Skips service re-register when we are already running AS the service
+*     (launchd/systemd invoke the CLI with `--no-interactive`), because the
+*     re-register would bootout our own process mid-execution.
+*/
+function runHomeMigration() {
+	const result = migrateLegacyHome({
+		newHome: DEFAULT_HOME_DIR$1,
+		envOverride: process.env.FIRST_TREE_HUB_HOME ?? null
+	});
+	if (!result.migrated) {
+		if (result.reason === "failed") process.stderr.write(`[first-tree-hub] WARNING: failed to auto-migrate legacy home ${result.from} → ${result.to}: ${result.error ?? "unknown error"}\n  Resolve manually: cp -R "${result.from}" "${result.to}"\n`);
+		return;
+	}
+	process.stderr.write(`[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")) {
+		process.stderr.write("[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");
+		return;
+	}
+	const status = getClientServiceStatus();
+	if (status.platform === "unsupported" || status.state === "not-installed") return;
+	try {
+		installClientService();
+		process.stderr.write(`[first-tree-hub] Re-registered background service with new home paths.\n`);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[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`);
+	}
+}
+//#endregion
+//#region src/core/onboard.ts
+const STATE_FILE = join(DEFAULT_HOME_DIR$1, ".onboard-state.json");
+/** Save current onboard args to state file for resume. */
+function saveOnboardState(args) {
+	mkdirSync(DEFAULT_HOME_DIR$1, { recursive: true });
+	writeFileSync(STATE_FILE, JSON.stringify({ args }, null, 2));
+}
+/** Load saved onboard args from state file. */
+function loadOnboardState() {
+	try {
+		return JSON.parse(readFileSync(STATE_FILE, "utf-8")).args;
+	} catch {
+		return null;
+	}
+}
+async function onboardCheck(args) {
+	const items = [];
+	const creds = loadCredentials();
+	if (creds) items.push({
+		key: "connect",
+		label: "Signed in",
+		status: "ok",
+		value: creds.serverUrl
+	});
+	else items.push({
+		key: "connect",
+		label: "Signed in",
+		status: "missing_required",
+		hint: "Run `first-tree-hub client connect <server-url>` first"
+	});
+	try {
+		const serverUrl = resolveServerUrl(args.server);
+		items.push({
+			key: "server",
+			label: "Server URL",
+			status: "ok",
+			value: serverUrl
+		});
+		try {
+			const res = await fetch(`${serverUrl}/api/v1/health`);
+			items.push({
+				key: "server_reachable",
+				label: "Server reachable",
+				status: res.ok ? "ok" : "error",
+				value: res.ok ? "healthy" : `HTTP ${res.status}`
+			});
+		} catch {
+			items.push({
+				key: "server_reachable",
+				label: "Server reachable",
+				status: "error",
+				hint: "Cannot connect to server"
+			});
+		}
+	} catch {
+		items.push({
+			key: "server",
+			label: "Server URL",
+			status: "missing_required",
+			hint: "Provide via --server, FIRST_TREE_HUB_SERVER_URL, or config"
+		});
+	}
+	if (args.id) items.push({
+		key: "id",
+		label: "Agent ID",
+		status: "ok",
+		value: args.id
+	});
+	else items.push({
+		key: "id",
+		label: "Agent ID",
+		status: "missing_required",
+		hint: "Provide via --id"
+	});
+	if (args.type) items.push({
+		key: "type",
+		label: "Agent type",
+		status: "ok",
+		value: args.type
+	});
+	else items.push({
+		key: "type",
+		label: "Agent type",
+		status: "missing_required",
+		hint: "Provide via --type"
+	});
+	if (args.type && args.type !== "human") if (args.clientId) items.push({
+		key: "client",
+		label: "Target client",
+		status: "ok",
+		value: args.clientId
+	});
+	else items.push({
+		key: "client",
+		label: "Target client",
+		status: "ok",
+		value: "(unbound — claimed on first WS connect)"
+	});
+	return items;
+}
+function formatCheckReport(items) {
+	const lines = [];
+	for (const item of items) {
+		const icon = item.status === "ok" ? "✅" : item.status === "missing_required" ? "❌" : item.status === "error" ? "❌" : item.status === "warning" ? "⚠️" : "⬜";
+		const valueStr = item.value ? `  ${item.value}` : "";
+		const hintStr = item.hint ? `  (${item.hint})` : "";
+		lines.push(`  ${icon} ${item.label.padEnd(20)}${valueStr}${hintStr}`);
+	}
+	return lines.join("\n");
+}
+async function createAgentViaAdmin(serverUrl, accessToken, body) {
+	const res = await fetch(`${serverUrl}/api/v1/admin/agents`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${accessToken}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(1e4)
+	});
+	if (!res.ok) {
+		const errBody = await res.json().catch(() => ({}));
+		throw new Error(errBody.error ?? `Failed to create agent (HTTP ${res.status})`);
+	}
+	return await res.json();
+}
+async function onboardCreate(args) {
+	const serverUrl = resolveServerUrl(args.server).replace(/\/+$/, "");
+	const accessToken = await ensureFreshAccessToken();
+	const metadata = {};
 	if (args.role) metadata.role = args.role;
 	if (args.domains) metadata.domains = args.domains.split(",").map((d) => d.trim());
 	process.stderr.write(`Creating agent "${args.id}"...\n`);
@@ -4673,7 +5354,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-n9Y2yGTT.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-GlaczcVf.mjs").then((n) => n.r);
 		const targetAgentUuid = args.type === "human" ? assistantUuid : primary.uuid;
 		if (!targetAgentUuid) process.stderr.write(`Warning: Cannot bind Feishu bot — no runtime agent available for "${args.id}".\n`);
 		else {
@@ -7126,7 +7807,7 @@ var require_secure_json_parse = /* @__PURE__ */ __commonJSMin(((exports, module)
 	module.exports.scan = filter;
 }));
 //#endregion
-//#region ../server/dist/app-Dlx5GuFi.mjs
+//#region ../server/dist/app-BcKNAbK-.mjs
 var import_multipart = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const Busboy = require_main();
 	const os = __require("node:os");
@@ -10430,17 +11111,35 @@ async function createNotification(db, data) {
 	pushToWebhook(db, notification).catch(() => {});
 	return notification;
 }
-/** List notifications with pagination and optional filters. */
-async function listNotifications(db, orgId, query) {
+/**
+* List notifications with pagination and optional filters, scoped to the
+* caller's visible agents.
+*
+* Rule: a member sees a notification iff
+*   - it carries an `agentId` the member can see
+*     (`agents.visibility = organization` OR `agents.managerId = self`), OR
+*   - it has no `agentId` (org-wide system notification)
+*
+* Private agents owned by other members never surface.
+*/
+async function listNotifications(db, orgId, memberId, query) {
+	const visibleAgents = await loadVisibleAgentIds$1(db, orgId, memberId);
+	if (query.agentId && !visibleAgents.has(query.agentId)) return {
+		items: [],
+		nextCursor: null
+	};
 	const conditions = [eq(notifications.organizationId, orgId)];
 	if (query.cursor) conditions.push(lt(notifications.createdAt, new Date(query.cursor)));
 	if (query.severity) conditions.push(eq(notifications.severity, query.severity));
 	if (query.read !== void 0) conditions.push(eq(notifications.read, query.read));
 	if (query.agentId) conditions.push(eq(notifications.agentId, query.agentId));
 	const where = and(...conditions);
-	const rows = await db.select().from(notifications).where(where).orderBy(desc(notifications.createdAt)).limit(query.limit + 1);
-	const hasMore = rows.length > query.limit;
-	const items = hasMore ? rows.slice(0, query.limit) : rows;
+	const overscanFactor = 4;
+	const targetLimit = query.limit;
+	const rawLimit = Math.min(targetLimit * overscanFactor + 1, 400);
+	const visible = (await db.select().from(notifications).where(where).orderBy(desc(notifications.createdAt)).limit(rawLimit)).filter((n) => n.agentId === null || visibleAgents.has(n.agentId));
+	const hasMore = visible.length > targetLimit;
+	const items = hasMore ? visible.slice(0, targetLimit) : visible;
 	const last = items[items.length - 1];
 	const nextCursor = hasMore && last ? last.createdAt.toISOString() : null;
 	return {
@@ -10451,36 +11150,116 @@ async function listNotifications(db, orgId, query) {
 		nextCursor
 	};
 }
-/** Mark a single notification as read, scoped to organization. */
-async function markRead(db, notificationId, organizationId) {
-	const [updated] = await db.update(notifications).set({ read: true }).where(and(eq(notifications.id, notificationId), eq(notifications.organizationId, organizationId))).returning();
+/** Mark a single notification as read, scoped to organization + visible agents. */
+async function markRead(db, notificationId, orgId, memberId) {
+	const [existing] = await db.select({
+		id: notifications.id,
+		agentId: notifications.agentId
+	}).from(notifications).where(and(eq(notifications.id, notificationId), eq(notifications.organizationId, orgId))).limit(1);
+	if (!existing) return null;
+	if (existing.agentId) {
+		if (!(await loadVisibleAgentIds$1(db, orgId, memberId)).has(existing.agentId)) return null;
+	}
+	const [updated] = await db.update(notifications).set({ read: true }).where(and(eq(notifications.id, notificationId), eq(notifications.organizationId, orgId))).returning();
 	return updated ?? null;
 }
-/** Mark all notifications as read for an organization. */
-async function markAllRead(db, orgId) {
-	await db.update(notifications).set({ read: true }).where(and(eq(notifications.organizationId, orgId), eq(notifications.read, false)));
+/** Mark all notifications visible to this member as read. */
+async function markAllRead(db, orgId, memberId) {
+	const visible = await loadVisibleAgentIds$1(db, orgId, memberId);
+	const idsToMark = (await db.select({
+		id: notifications.id,
+		agentId: notifications.agentId
+	}).from(notifications).where(and(eq(notifications.organizationId, orgId), eq(notifications.read, false))).limit(1e3)).filter((n) => n.agentId === null || visible.has(n.agentId)).map((n) => n.id);
+	if (idsToMark.length === 0) return;
+	const batchSize = 200;
+	for (let i = 0; i < idsToMark.length; i += batchSize) {
+		const batch = idsToMark.slice(i, i + batchSize);
+		await db.update(notifications).set({ read: true }).where(and(eq(notifications.organizationId, orgId), eq(notifications.read, false), inArray(notifications.id, batch)));
+	}
+}
+/**
+* Shared visibility predicate. Mirrors
+* {@link packages/server/src/services/access-control.ts#agentVisibilityCondition}
+* but returns a Set because the notification query joins are mostly in Node.
+*/
+async function loadVisibleAgentIds$1(db, orgId, memberId) {
+	const rows = await db.select({ id: agents.uuid }).from(agents).where(and(eq(agents.organizationId, orgId), ne(agents.status, AGENT_STATUSES.DELETED), or(eq(agents.visibility, AGENT_VISIBILITY.ORGANIZATION), eq(agents.managerId, memberId))));
+	return new Set(rows.map((r) => r.id));
+}
+async function resolveAgentContext(db, agentId) {
+	const [agent] = await db.select({
+		organizationId: agents.organizationId,
+		name: agents.name,
+		displayName: agents.displayName,
+		clientId: agents.clientId
+	}).from(agents).where(eq(agents.uuid, agentId)).limit(1);
+	if (!agent) return null;
+	let clientLabel = null;
+	if (agent.clientId) {
+		const [client] = await db.select({
+			hostname: clients.hostname,
+			id: clients.id
+		}).from(clients).where(eq(clients.id, agent.clientId)).limit(1);
+		clientLabel = client?.hostname ?? agent.clientId;
+	}
+	return {
+		organizationId: agent.organizationId,
+		agentName: agent.displayName ?? agent.name ?? agentId,
+		clientId: agent.clientId,
+		clientLabel
+	};
+}
+async function resolveChatContext(db, chatId) {
+	const [chat] = await db.select({ topic: chats.topic }).from(chats).where(eq(chats.id, chatId)).limit(1);
+	const shortId = chatId.slice(0, 8);
+	return { chatLabel: chat?.topic && chat.topic.trim().length > 0 ? chat.topic.trim() : `Chat ${shortId}` };
+}
+/**
+* Compose a human-readable message for each notification type.
+*
+* Keep subjects consistent with what the dashboard shows the member:
+*   - Session-scoped events → subject is the chat (topic / "Chat xxxxxxxx")
+*   - Client-scoped events  → subject is the computer (hostname / clientId)
+*   - Agent-scoped events   → subject is the agent display name
+*/
+function composeMessage(type, agentCtx, chatCtx) {
+	const agent = agentCtx.agentName;
+	const computer = agentCtx.clientLabel ?? "Unknown computer";
+	const chat = chatCtx?.chatLabel ?? null;
+	switch (type) {
+		case "session_completed": return chat ? `${chat} completed` : `${agent} completed a task`;
+		case "session_error": return chat ? `${chat} hit an error` : `${agent} hit a session error`;
+		case "agent_disconnected": return `Computer ${computer} disconnected`;
+		case "agent_connected": return `Computer ${computer} reconnected`;
+		case "agent_stale": return `Computer ${computer} is unresponsive`;
+		case "agent_error": return `${agent} entered error state`;
+		case "agent_blocked": return `${agent} is blocked`;
+		case "agent_needs_decision": return chat ? `${agent} needs a decision in ${chat}` : `${agent} needs a decision`;
+		default: return `${agent} event`;
+	}
 }
 /**
-* Convenience: create a notification for an agent event, resolving org automatically.
-* Fire-and-forget — errors are swallowed.
+* Convenience: create a notification for an agent event, resolving org,
+* agent display name, computer hostname, and chat topic automatically.
+* Callers supply the event type and severity; the message text is generated
+* here so language/phrasing is centralized (see {@link composeMessage}).
+*
+* Fire-and-forget — errors are swallowed so event producers never fail just
+* because the notification pipeline is unhealthy.
 */
-async function notifyAgentEvent(db, agentId, type, severity, message, chatId) {
+async function notifyAgentEvent(db, agentId, type, severity, chatId) {
 	try {
-		const [agent] = await db.select({
-			organizationId: agents.organizationId,
-			name: agents.name,
-			displayName: agents.displayName
-		}).from(agents).where(eq(agents.uuid, agentId)).limit(1);
-		if (!agent) return;
-		const name = agent.displayName ?? agent.name ?? agentId;
-		const resolvedMessage = message.replace(agentId, name);
+		const agentCtx = await resolveAgentContext(db, agentId);
+		if (!agentCtx) return;
+		const message = composeMessage(type, agentCtx, chatId ? await resolveChatContext(db, chatId) : null);
 		await createNotification(db, {
-			organizationId: agent.organizationId,
+			organizationId: agentCtx.organizationId,
 			type,
 			severity,
 			agentId,
 			chatId: chatId ?? null,
-			message: resolvedMessage
+			clientId: agentCtx.clientId,
+			message
 		});
 	} catch {}
 }
@@ -10488,6 +11267,7 @@ function pushToAdminWs(notification) {
 	broadcastToAdmins({
 		type: "notification",
 		organizationId: notification.organizationId,
+		agentId: notification.agentId ?? null,
 		data: notification
 	});
 }
@@ -10504,26 +11284,34 @@ async function pushToWebhook(db, notification) {
 	} catch {}
 }
 async function adminNotificationRoutes(app) {
-	/** GET /admin/notifications — list notifications scoped to caller's org */
+	/**
+	* GET /admin/notifications — list notifications visible to the caller.
+	*
+	* Scoped by (a) organization (via JWT) and (b) per-agent visibility: the
+	* member only sees notifications whose agentId is visible to them
+	* (organization-visible agents or agents they manage), plus org-wide
+	* system notifications with no agentId. This mirrors the rule the admin
+	* WebSocket route enforces on live pushes — REST and WS stay in sync.
+	*/
 	app.get("/", async (request) => {
 		const member = requireMember(request);
 		const query = notificationQuerySchema.parse(request.query);
-		return listNotifications(app.db, member.organizationId, query);
+		return listNotifications(app.db, member.organizationId, member.memberId, query);
 	});
 	/** POST /admin/notifications/:id/read — mark a single notification as read */
 	app.post("/:id/read", async (request) => {
 		const member = requireMember(request);
-		const result = await markRead(app.db, request.params.id, member.organizationId);
+		const result = await markRead(app.db, request.params.id, member.organizationId, member.memberId);
 		if (!result) throw new NotFoundError(`Notification "${request.params.id}" not found`);
 		return {
 			...result,
 			createdAt: result.createdAt.toISOString()
 		};
 	});
-	/** POST /admin/notifications/read-all — mark all notifications as read */
+	/** POST /admin/notifications/read-all — mark all visible notifications as read */
 	app.post("/read-all", async (request) => {
 		const member = requireMember(request);
-		await markAllRead(app.db, member.organizationId);
+		await markAllRead(app.db, member.organizationId, member.memberId);
 		return { status: "ok" };
 	});
 }
@@ -11634,6 +12422,8 @@ function adminWsRoutes(notifier, jwtSecret) {
 		const orgId = payload.organizationId;
 		if (typeof orgId !== "string" || orgId.length === 0) return;
 		const isPulseTick = payload.type === "pulse:tick" && typeof payload.agents === "object" && payload.agents !== null;
+		const isNotification = payload.type === "notification";
+		const notificationAgentId = isNotification && typeof payload.agentId === "string" && payload.agentId.length > 0 ? payload.agentId : null;
 		const sharedData = isPulseTick ? null : JSON.stringify(payload);
 		for (const [ws, meta] of adminSockets) {
 			if (ws.readyState !== 1 || meta.organizationId !== orgId) continue;
@@ -11643,7 +12433,10 @@ function adminWsRoutes(notifier, jwtSecret) {
 					...payload,
 					agents: filtered
 				}));
-			} else ws.send(sharedData);
+			} else {
+				if (isNotification && notificationAgentId && !meta.visibleAgentIds.has(notificationAgentId)) continue;
+				ws.send(sharedData);
+			}
 		}
 	}
 	registerAdminBroadcaster(broadcastOrgScoped);
@@ -12340,6 +13133,11 @@ function clientWsRoutes(notifier, instanceId) {
 						clearTimeout(authTimeout);
 						scheduleAuthExpiry(claims.exp);
 						socket.send(JSON.stringify({ type: "auth:ok" }));
+						socket.send(JSON.stringify({
+							type: "server:welcome",
+							serverCommandVersion: app.commandVersion,
+							serverTimeMs: Date.now()
+						}));
 					} catch (err) {
 						const message = err instanceof Error ? err.message : "auth failure";
 						socket.send(JSON.stringify({
@@ -12559,8 +13357,8 @@ function clientWsRoutes(notifier, instanceId) {
 								organizationId: session.organizationId,
 								notifier
 							});
-							if (payload.runtimeState === "error" && shouldNotify(agentId, "agent_error")) notifyAgentEvent(app.db, agentId, "agent_error", "high", `Agent ${agentId} entered error state`).catch(() => {});
-							else if (payload.runtimeState === "blocked" && shouldNotify(agentId, "agent_blocked")) notifyAgentEvent(app.db, agentId, "agent_blocked", "medium", `Agent ${agentId} is blocked`).catch(() => {});
+							if (payload.runtimeState === "error" && shouldNotify(agentId, "agent_error")) notifyAgentEvent(app.db, agentId, "agent_error", "high").catch(() => {});
+							else if (payload.runtimeState === "blocked" && shouldNotify(agentId, "agent_blocked")) notifyAgentEvent(app.db, agentId, "agent_blocked", "medium").catch(() => {});
 						} else if (type === "session:event") {
 							const agentId = parsed.data.agentId;
 							if (!agentId || !boundAgents.has(agentId)) {
@@ -12591,7 +13389,7 @@ function clientWsRoutes(notifier, instanceId) {
 								return;
 							}
 							const payload = sessionCompletionMessageSchema.parse(msg);
-							if (shouldNotify(agentId, `session_completed:${payload.chatId}`)) notifyAgentEvent(app.db, agentId, "session_completed", "low", `Agent ${agentId} completed a task`, payload.chatId).catch(() => {});
+							if (shouldNotify(agentId, `session_completed:${payload.chatId}`)) notifyAgentEvent(app.db, agentId, "session_completed", "low", payload.chatId).catch(() => {});
 						} else if (type === "heartbeat") {
 							if (clientId) {
 								await heartbeatClient(app.db, clientId);
@@ -12616,7 +13414,7 @@ function clientWsRoutes(notifier, instanceId) {
 					notifier.unsubscribe(info.inboxId, socket);
 					if (getAgentClientId(agentId) === clientId) try {
 						await unbindAgent(app.db, agentId);
-						if (shouldNotify(agentId, "agent_disconnected")) notifyAgentEvent(app.db, agentId, "agent_disconnected", "medium", `Agent ${agentId} disconnected`).catch(() => {});
+						if (shouldNotify(agentId, "agent_disconnected")) notifyAgentEvent(app.db, agentId, "agent_disconnected", "medium").catch(() => {});
 					} catch {}
 				}
 				boundAgents.clear();
@@ -14118,7 +14916,7 @@ function createBackgroundTasks(app, instanceId, adapterManager, kaelRuntime) {
 							count: staleAgents.length,
 							agentIds: staleAgents
 						}, "marked agents as stale");
-						for (const agentId of staleAgents) notifyAgentEvent(app.db, agentId, "agent_stale", "medium", `Agent ${agentId} is unresponsive`).catch(() => {});
+						for (const agentId of staleAgents) notifyAgentEvent(app.db, agentId, "agent_stale", "medium").catch(() => {});
 					}
 				} catch (err) {
 					log.error({ err }, "failed to heartbeat / cleanup presence");
@@ -14697,6 +15495,21 @@ function createPulseAggregator(options) {
 		ingest
 	};
 }
+/**
+* Resolve the Command-package version advertised to clients. Prefers the
+* value the Command CLI explicitly injected; otherwise falls back to the
+* server workspace's own package.json (dev mode, `pnpm --filter … dev`).
+* Returning a string (rather than undefined) keeps the welcome frame well-
+* formed — the client treats the value advisorily.
+*/
+function resolveCommandVersion(injected) {
+	if (injected && injected.trim().length > 0) return injected;
+	try {
+		const pkg = createRequire(import.meta.url)("../package.json");
+		if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+	} catch {}
+	return "0.0.0";
+}
 async function buildApp(config) {
 	applyLoggerConfig({
 		level: config.observability.logging.level,
@@ -14710,6 +15523,9 @@ async function buildApp(config) {
 	const db = connectDatabase(config.database.url);
 	app.decorate("db", db);
 	app.decorate("config", config);
+	const commandVersion = resolveCommandVersion(config.commandVersion);
+	app.decorate("commandVersion", commandVersion);
+	app.log.info({ commandVersion }, "Hub server advertising command version");
 	const listenClient = postgres(config.database.url, { max: 1 });
 	const notifier = createNotifier(listenClient);
 	await app.register(websocket);
@@ -14906,6 +15722,10 @@ async function buildApp(config) {
 	return app;
 }
 //#endregion
+//#region src/core/version.ts
+const pkg = createRequire(import.meta.url)("../../package.json");
+const COMMAND_VERSION = typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : "0.0.0";
+//#endregion
 //#region src/core/server.ts
 /**
 * Full server start orchestration:
@@ -14918,7 +15738,7 @@ async function buildApp(config) {
 * 7. Start Fastify server
 */
 async function startServer(options) {
-	process.stderr.write("\n  First Tree Hub v0.1.0\n\n");
+	process.stderr.write(`\n  First Tree Hub v${COMMAND_VERSION}\n\n`);
 	const cliArgs = {};
 	if (options.port !== void 0) cliArgs.server = { port: options.port };
 	if (options.host !== void 0) cliArgs.server = {
@@ -14957,7 +15777,8 @@ async function startServer(options) {
 	const config = {
 		...serverConfig,
 		webDistPath: webDistPath ?? void 0,
-		instanceId: `srv_${randomUUID().slice(0, 8)}`
+		instanceId: `srv_${randomUUID().slice(0, 8)}`,
+		commandVersion: COMMAND_VERSION
 	};
 	const { initTelemetry, shutdownTelemetry } = await import("./observability-Xi-sEZI7.mjs");
 	await initTelemetry(serverConfig.observability.tracing, config.instanceId);
@@ -14983,417 +15804,206 @@ async function startServer(options) {
 	process.stderr.write("  Open the URL above in your browser to get started.\n");
 	process.stderr.write("  Press Ctrl+C to stop.\n\n");
 }
-/**
-* Resolve web dist path.
-* 1. npm install: embedded at dist/web/ (relative to the built CLI)
-* 2. Monorepo dev: resolved from @first-tree-hub/web package (builds if needed)
-*/
-function resolveWebDist() {
-	const embeddedPath = join(dirname(fileURLToPath(import.meta.url)), "..", "web");
-	if (existsSync(join(embeddedPath, "index.html"))) return embeddedPath;
-	try {
-		const webDir = dirname(fileURLToPath(import.meta.resolve("@first-tree-hub/web/package.json")));
-		const distPath = join(webDir, "dist");
-		const indexPath = join(distPath, "index.html");
-		if (existsSync(indexPath)) return distPath;
-		status("Web", "building...");
-		execSync("pnpm --filter @first-tree-hub/web build", {
-			stdio: [
-				"ignore",
-				"ignore",
-				"pipe"
-			],
-			cwd: join(webDir, "../..")
-		});
-		if (existsSync(indexPath)) return distPath;
-	} catch {}
-}
-//#endregion
-//#region src/core/service-install.ts
-/**
-* Run a subprocess capturing stderr so failures surface a meaningful error
-* instead of Node's opaque "Command failed". Used for launchctl/systemctl —
-* anywhere the stderr message is diagnostically crucial.
-*/
-function runCapture(program, args, timeoutMs) {
-	const res = spawnSync(program, args, {
-		encoding: "utf-8",
-		timeout: timeoutMs,
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		]
-	});
-	if (res.status === 0) return { ok: true };
-	return {
-		ok: false,
-		stderr: (res.stderr ?? "").trim(),
-		code: res.status
-	};
-}
-function sleepSync(ms) {
-	const shared = new Int32Array(new SharedArrayBuffer(4));
-	Atomics.wait(shared, 0, 0, ms);
-}
-const LAUNCHD_LABEL = "dev.first-tree-hub.client";
-const SYSTEMD_UNIT = "first-tree-hub-client.service";
-const LOG_DIR = join(DEFAULT_HOME_DIR$1, "logs");
-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 {
-			kind: "bin",
-			program: realpathSync(bin)
-		};
-	} catch {
-		return {
-			kind: "bin",
-			program: bin
-		};
-	}
-	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]
-	};
-}
-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 outLog = join(LOG_DIR, "client.out.log");
-	const errLog = join(LOG_DIR, "client.err.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>
-  </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(outLog)}</string>
-  <key>StandardErrorPath</key>
-  <string>${escapeXml(errLog)}</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"
-	};
-	const out = res.stdout ?? "";
-	const stateLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("state ="));
-	const pidLine = out.split(/\r?\n/).find((l) => l.trim().startsWith("pid ="));
-	if (stateLine?.includes("running")) {
-		const pid = pidLine?.split("=")[1]?.trim();
-		return {
-			state: "active",
-			detail: pid ? `pid ${pid}` : "running"
-		};
-	}
-	return {
-		state: "inactive",
-		detail: stateLine?.trim() ?? "loaded"
-	};
-}
-/**
-* Poll `launchctl print` until the label disappears, confirming launchd has
-* finished the async eviction kicked off by `bootout`. Required because
-* `bootout` returns before the actual unload completes when the service has
-* active WebSocket connections — a follow-up `bootstrap` against a still-
-* registered label fails with `Bootstrap failed: 5: Input/output error`.
+/**
+* Resolve web dist path.
+* 1. npm install: embedded at dist/web/ (relative to the built CLI)
+* 2. Monorepo dev: resolved from @first-tree-hub/web package (builds if needed)
 */
-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,
+function resolveWebDist() {
+	const embeddedPath = join(dirname(fileURLToPath(import.meta.url)), "..", "web");
+	if (existsSync(join(embeddedPath, "index.html"))) return embeddedPath;
+	try {
+		const webDir = dirname(fileURLToPath(import.meta.resolve("@first-tree-hub/web/package.json")));
+		const distPath = join(webDir, "dist");
+		const indexPath = join(distPath, "index.html");
+		if (existsSync(indexPath)) return distPath;
+		status("Web", "building...");
+		execSync("pnpm --filter @first-tree-hub/web build", {
 			stdio: [
 				"ignore",
 				"ignore",
 				"pipe"
-			]
-		}).status !== 0) return true;
-		sleepSync(200);
-	}
-	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)) process.stderr.write(`    warning: launchctl bootout: ${bootoutRes.stderr || `exit ${bootoutRes.code ?? "unknown"}`}\n`);
-	}
-	waitForLabelEvicted(target, LAUNCHD_LABEL, 1e4);
-	let lastBootstrapErr = null;
-	for (let attempt = 1; attempt <= 2; attempt++) {
-		const res = runCapture("launchctl", [
-			"bootstrap",
-			target,
-			plistPath
-		], 1e4);
-		if (res.ok) {
-			lastBootstrapErr = null;
-			break;
-		}
-		lastBootstrapErr = res;
-		if (attempt < 2) sleepSync(1e3);
-	}
-	if (lastBootstrapErr) throw new Error(`launchctl bootstrap failed: ${lastBootstrapErr.stderr || `exit ${lastBootstrapErr.code ?? "unknown"}`}\n    Command: launchctl bootstrap ${target} ${plistPath}\n    Recovery: \`launchctl bootout ${target}/${LAUNCHD_LABEL}\` then \`first-tree-hub service install\`.`);
-	const enableRes = runCapture("launchctl", ["enable", `${target}/${LAUNCHD_LABEL}`], 5e3);
-	if (!enableRes.ok) process.stderr.write(`    warning: launchctl enable: ${enableRes.stderr || `exit ${enableRes.code ?? "unknown"}`}\n`);
-	const { state, detail } = launchdState();
-	return {
-		platform: "launchd",
-		label: LAUNCHD_LABEL,
-		unitPath: plistPath,
-		logDir: LOG_DIR,
-		state,
-		detail
-	};
-}
-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)) process.stderr.write(`    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"
-	};
-}
-function systemdUnitPath() {
-	return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "systemd", "user", SYSTEMD_UNIT);
+			],
+			cwd: join(webDir, "../..")
+		});
+		if (existsSync(indexPath)) return distPath;
+	} catch {}
 }
-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.out.log")}
-StandardError=append:${join(LOG_DIR, "client.err.log")}
-Environment=PATH=/usr/local/bin:/usr/bin:/bin
-
-[Install]
-WantedBy=default.target
-`;
+//#endregion
+//#region src/core/update.ts
+const PACKAGE_NAME = "@agent-team-foundation/first-tree-hub";
+/**
+* Pick the `npm` binary to invoke for self-update. Background service units
+* hard-code a minimal PATH (/usr/local/bin, /opt/homebrew/bin, /usr/bin,
+* /bin) that misses nvm / asdf / Volta toolchain directories — the client
+* launches fine from an absolute path resolved at install time, but a plain
+* `spawn("npm")` then ENOENTs. Node and npm always ship side-by-side, so
+* `dirname(execPath)/npm` is the most reliable fallback across those
+* managers; if the sibling is missing (e.g. corporate custom layout) we
+* fall back to PATH lookup.
+*/
+function resolveNpmCommand() {
+	const binName = process.platform === "win32" ? "npm.cmd" : "npm";
+	const sibling = join(dirname(process.execPath), binName);
+	if (existsSync(sibling)) return sibling;
+	return "npm";
 }
-function shellQuote(value) {
-	if (/^[A-Za-z0-9_\-./:=]+$/.test(value)) return value;
-	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+/**
+* Detect how the CLI was launched. Used by the update path to decide whether
+* `npm install -g <pkg>@latest` makes sense.
+*
+*  - `"global"`: launched from an `npm install -g` install. The self-update
+*    reinstalls the same package at `@latest`.
+*  - `"source"`: launched from inside a git checkout (dev / monorepo). Update
+*    is a no-op; operator should `git pull`.
+*  - `"npx"` (fallback): any other path (e.g. one-shot `npx`, pnpm dlx). Auto
+*    update is not safe; log a hint and skip.
+*/
+function detectInstallMode(argv1 = process.argv[1] ?? "") {
+	if (!argv1) return "npx";
+	let dir = dirname(resolve(argv1));
+	for (let i = 0; i < 10; i++) {
+		if (existsSync(resolve(dir, ".git"))) return "source";
+		const pkgPath = resolve(dir, "package.json");
+		if (existsSync(pkgPath)) try {
+			if (JSON.parse(readFileSync(pkgPath, "utf8")).name === PACKAGE_NAME) {
+				if (/\/(?:_npx|\.npm\/_npx)\//.test(dir)) return "npx";
+				return "global";
+			}
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return "npx";
 }
-function systemdState() {
-	if (!existsSync(systemdUnitPath())) return { state: "not-installed" };
-	const res = spawnSync("systemctl", [
-		"--user",
-		"is-active",
-		SYSTEMD_UNIT
-	], {
-		encoding: "utf-8",
-		timeout: 5e3,
-		stdio: [
+/**
+* Install `<pkg>@latest` globally. Returns after the child exits. Does not
+* exit the parent process — callers are expected to handle that (so the
+* UpdateManager can attempt the restart itself while this function remains
+* side-effect-scoped).
+*/
+async function installGlobalLatest() {
+	return new Promise((resolvePromise) => {
+		const child = spawn(resolveNpmCommand(), [
+			"install",
+			"-g",
+			`${PACKAGE_NAME}@latest`
+		], { stdio: [
 			"ignore",
 			"pipe",
 			"pipe"
-		]
+		] });
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+		child.stderr.on("data", (chunk) => {
+			stderrChunks.push(chunk);
+			process.stderr.write(chunk);
+		});
+		child.on("error", (err) => {
+			resolvePromise({
+				ok: false,
+				mode: "global",
+				reason: err instanceof Error ? err.message : String(err)
+			});
+		});
+		child.on("exit", (code) => {
+			if (code === 0) resolvePromise({
+				ok: true,
+				mode: "global",
+				installedVersion: parseInstalledVersion(Buffer.concat(stdoutChunks).toString("utf8"))
+			});
+			else {
+				const stderr = Buffer.concat(stderrChunks).toString("utf8").trim();
+				resolvePromise({
+					ok: false,
+					mode: "global",
+					reason: `npm install -g exited with code ${code}${stderr ? `: ${stderr.split("\n").slice(-3).join(" | ")}` : ""}`
+				});
+			}
+		});
 	});
-	const out = (res.stdout ?? "").trim();
-	if (res.status === 0 && out === "active") return {
-		state: "active",
-		detail: "running"
-	};
-	return {
-		state: "inactive",
-		detail: out || "unit present but not active"
-	};
-}
-function installSystemd() {
-	const invocation = resolveCliInvocation();
-	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,
-		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)) process.stderr.write(`    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) process.stderr.write(`    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"
-	};
-}
-/** Is background-service install supported on the current platform? */
-function isServiceSupported() {
-	return process.platform === "darwin" || process.platform === "linux";
 }
 /**
-* Install the background service for the current platform.
-*
-* @throws {Error} if the platform is not supported or the service manager fails.
+* Best-effort extraction of the version npm reported as installed. npm's
+* stdout lines look like `+ @agent-team-foundation/first-tree-hub@0.9.2`.
+* Returns null if nothing matches — callers treat null as "install succeeded
+* but version unknown".
 */
-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 {
-			platform: "launchd",
-			label: LAUNCHD_LABEL,
-			unitPath: launchdPlistPath(),
-			logDir: LOG_DIR,
-			state,
-			detail
-		};
-	}
-	if (process.platform === "linux") {
-		const { state, detail } = systemdState();
-		return {
-			platform: "systemd",
-			label: SYSTEMD_UNIT,
-			unitPath: systemdUnitPath(),
-			logDir: LOG_DIR,
-			state,
-			detail
-		};
+function parseInstalledVersion(stdout) {
+	const match = new RegExp(`${escapeForRegex(PACKAGE_NAME)}@(\\S+)`).exec(stdout);
+	if (!match?.[1]) return null;
+	const cleaned = match[1].replace(/[,\s)]+$/, "");
+	return semver.valid(cleaned) ?? cleaned;
+}
+function escapeForRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Interactive update prompt. Defaults to N on timeout. */
+const promptUpdate = async ({ currentVersion, targetVersion, timeoutSeconds }) => {
+	const message = `A newer First Tree Hub client is available.\n  You: ${currentVersion}\n  Server bundled with: ${targetVersion}\n  Will install: latest on npm (>= ${targetVersion})\n  Updating will restart the client and briefly interrupt any active sessions.\n  Update now?`;
+	try {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1e3);
+		try {
+			return await confirm({
+				message,
+				default: false
+			}, { signal: controller.signal });
+		} finally {
+			clearTimeout(timer);
+		}
+	} catch {
+		return false;
 	}
-	return {
-		platform: "unsupported",
-		label: "",
-		unitPath: "",
-		logDir: LOG_DIR,
-		state: "not-installed",
-		detail: `platform ${process.platform} not supported`
+};
+/**
+* Update prompt that always declines. Wired in when the operator passes
+* `--no-interactive` — the UpdateManager will log the drift and move on
+* instead of blocking on a TTY confirm.
+*/
+const declineUpdate = async () => false;
+/**
+* Build the command-layer `executeUpdate` callback.
+*
+* `managed=true` means a process supervisor (launchd / systemd / Docker
+* `restart`) is expected to relaunch us after `process.exit` — the callback
+* installs the new bits and exits with `SELF_RESTART_EXIT_CODE` so the
+* relaunch picks up the new binary.
+*
+* `managed=false` means the process is running standalone (e.g. manual
+* `client start`, `client connect --no-service`, CI without a supervisor).
+* Exiting in that mode would leave the client offline until an operator
+* noticed — so the callback instead prints a restart hint, returns
+* `{ installed: true }`, and the UpdateManager stops retrying until the
+* operator restarts manually.
+*/
+function createExecuteUpdate({ managed }) {
+	return async () => {
+		const mode = detectInstallMode();
+		if (mode === "source") {
+			process.stderr.write("  [update] Running from source checkout — self-update skipped. Use `git pull` instead.\n");
+			return { installed: false };
+		}
+		if (mode === "npx") {
+			process.stderr.write("  [update] Cannot self-update — not launched from a global npm install.\n  Run `npm i -g @agent-team-foundation/first-tree-hub` manually.\n");
+			return { installed: false };
+		}
+		process.stderr.write("  [update] Running `npm install -g @agent-team-foundation/first-tree-hub@latest`...\n");
+		const result = await installGlobalLatest();
+		if (!result.ok) {
+			process.stderr.write(`  [update] Install failed: ${result.reason}\n`);
+			return { installed: false };
+		}
+		const installed = result.installedVersion ?? "latest";
+		if (managed) {
+			process.stderr.write(`  [update] Installed ${installed}. Restarting (exit 75).\n`);
+			process.exit(75);
+		}
+		process.stderr.write(`  [update] Installed ${installed}. Restart the client manually (Ctrl+C then \`first-tree-hub client start\`) to pick up the new version.\n`);
+		return { installed: true };
 	};
 }
-/** 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
-export { stopPostgres as A, checkServerReachable as C, status as D, blank as E, SdkError as F, SessionRegistry as I, cleanWorkspaces as L, createOwner as M, hasUser as N, ensurePostgres as O, FirstTreeHubSDK as P, applyClientLoggerConfig as R, checkServerHealth as S, printResults as T, checkClientConfig as _, uninstallClientService as a, checkNodeVersion as b, promptAddAgent as c, loadOnboardState as d, onboardCheck as f, checkAgentConfigs as g, runMigrations as h, resolveCliInvocation as i, ClientRuntime as j, isDockerAvailable as k, promptMissingFields as l, saveOnboardState as m, installClientService as n, startServer as o, onboardCreate as p, isServiceSupported as r, isInteractive as s, getClientServiceStatus as t, formatCheckReport as u, checkDatabase as v, checkWebSocket as w, checkServerConfig as x, checkDocker as y };
+export { printResults as A, SdkError as B, checkDatabase as C, checkServerHealth as D, checkServerConfig as E, stopPostgres as F, cleanWorkspaces as H, ClientRuntime as I, createOwner as L, status as M, ensurePostgres as N, checkServerReachable as O, isDockerAvailable as P, hasUser as R, checkClientConfig as S, checkNodeVersion as T, applyClientLoggerConfig as U, SessionRegistry as V, isServiceSupported as _, COMMAND_VERSION as a, runMigrations as b, promptMissingFields as c, onboardCheck as d, onboardCreate as f, installClientService as g, getClientServiceStatus as h, startServer as i, blank as j, checkWebSocket as k, formatCheckReport as l, runHomeMigration as m, declineUpdate as n, isInteractive as o, saveOnboardState as p, promptUpdate as r, promptAddAgent as s, createExecuteUpdate as t, loadOnboardState as u, resolveCliInvocation as v, checkDocker as w, checkAgentConfigs as x, uninstallClientService as y, FirstTreeHubSDK as z };