@agent-team-foundation/first-tree-hub 0.10.10 → 0.10.12

package/dist/{bootstrap-jx5nN1qZ.mjs → bootstrap-CDeXqhkQ.mjs}

@@ -585,11 +585,14 @@ const serverConfigSchema = defineConfig({
 		})
 	}) }),
 	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
+	trustProxy: field(z.boolean().default(false), { env: "FIRST_TREE_HUB_TRUST_PROXY" }),
 	rateLimit: optional({
 		max: field(z.number().default(100), { env: "FIRST_TREE_HUB_RATE_LIMIT_MAX" }),
 		loginMax: field(z.number().default(5), { env: "FIRST_TREE_HUB_RATE_LIMIT_LOGIN_MAX" }),
-		webhookMax: field(z.number().default(60), { env: "FIRST_TREE_HUB_RATE_LIMIT_WEBHOOK_MAX" })
+		webhookMax: field(z.number().default(60), { env: "FIRST_TREE_HUB_RATE_LIMIT_WEBHOOK_MAX" }),
+		agentMessageMax: field(z.number().default(30), { env: "FIRST_TREE_HUB_RATE_LIMIT_AGENT_MESSAGE_MAX" })
 	}),
+	ws: optional({ maxPayload: field(z.number().int().min(1024).default(262144), { env: "FIRST_TREE_HUB_WS_MAX_PAYLOAD" }) }),
 	inbox: optional({ maxInFlightPerAgent: field(z.number().int().min(1).max(1024).default(32), { env: "FIRST_TREE_HUB_INBOX_MAX_IN_FLIGHT_PER_AGENT" }) }),
 	kael: optional({
 		endpoint: field(z.string(), { env: "KAEL_ENDPOINT" }),
@@ -690,15 +693,23 @@ function resolveAccessToken() {
 * promise so N concurrent callers resolve from a single HTTP call.
 */
 let inflightRefresh = null;
+/** Default freshness window for HTTP callers: refresh if token expires within 30s. */
+const DEFAULT_MIN_VALIDITY_MS = 3e4;
 /**
 * Ensure the persisted access token is fresh. Call before any API request
 * when using persisted credentials. Returns the (possibly refreshed) access
 * token. Service-user API keys are out of scope for this milestone.
+*
+* `opts.minValidityMs` raises the freshness bar — refresh when the cached
+* token has less than that much life left. The WS proactive-refresh path
+* passes a value that overlaps its lead window so it never receives a
+* token already inside the "about to expire" zone.
 */
-async function ensureFreshAccessToken() {
+async function ensureFreshAccessToken(opts) {
+	const minValidityMs = opts?.minValidityMs ?? DEFAULT_MIN_VALIDITY_MS;
 	const creds = loadCredentials();
 	if (!creds) throw new Error("No credentials found. Run `first-tree-hub client connect <server-url>` to sign in.");
-	if (!isTokenExpired(creds.accessToken)) return creds.accessToken;
+	if (!isTokenStale(creds.accessToken, minValidityMs)) return creds.accessToken;
 	if (inflightRefresh) return inflightRefresh;
 	inflightRefresh = (async () => {
 		const res = await fetch(`${creds.serverUrl}/api/v1/auth/refresh`, {
@@ -723,13 +734,13 @@ async function ensureFreshAccessToken() {
 }
 /** Back-compat alias retained so existing call sites keep compiling. */
 const ensureFreshAdminToken = ensureFreshAccessToken;
-function isTokenExpired(token) {
+function isTokenStale(token, minValidityMs) {
 	try {
 		const parts = token.split(".");
 		if (parts.length !== 3 || !parts[1]) return true;
 		const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
 		if (!payload.exp) return false;
-		return payload.exp * 1e3 < Date.now() + 3e4;
+		return payload.exp * 1e3 < Date.now() + minValidityMs;
 	} catch {
 		return true;
 	}

package/dist/cli/index.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import "../observability-DPyf745N-BSc8QNcR.mjs";
-import { $ as success, A as checkServerHealth, C as checkAgentConfigs, D as checkDocker, E as checkDatabase, F as getClientServiceStatus, H as stopPostgres, I as installClientService, J as removeLocalAgent, K as findStaleAliases, L as isServiceSupported, M as checkWebSocket, N as printResults, O as checkNodeVersion, P as reconcileAgentConfigs, Q as fail, S as runMigrations, T as checkClientConfig, U as ClientRuntime, W as handleClientOrgMismatch, Y as createOwner, Z as resolveReplyToFromEnv, _ as onboardCreate, a as declineUpdate, at as ClientUserMismatchError, b as createApiNameResolver, c as COMMAND_VERSION, ct as SessionRegistry, d as isInteractive, dt as applyClientLoggerConfig, f as promptAddAgent, ft as configureClientLoggerForService, g as onboardCheck, h as loadOnboardState, i as createExecuteUpdate, it as ClientOrgMismatchError, j as checkServerReachable, k as checkServerConfig, l as reconcileLocalRuntimeProviders, lt as cleanWorkspaces, m as formatCheckReport, nt as setJsonMode, o as promptUpdate, ot as FirstTreeHubSDK, p as promptMissingFields, q as formatStaleReason, r as registerSaaSConnectCommand, s as startServer, st as SdkError, tt as print, u as uploadClientCapabilities, ut as probeCapabilities, v as saveOnboardState, w as checkBackgroundService, x as migrateLocalAgentDirs, y as runHomeMigration } from "../saas-connect-CuJWyzzq.mjs";
+import { $ as findStaleAliases, A as checkDatabase, B as installClientService, C as runHomeMigration, D as checkAgentConfigs, E as runMigrations, F as checkServerReachable, G as stopClientService, I as checkWebSocket, L as printResults, M as checkNodeVersion, N as checkServerConfig, O as checkBackgroundService, P as checkServerHealth, R as reconcileAgentConfigs, S as saveOnboardState, T as migrateLocalAgentDirs, U as restartClientService, V as isServiceSupported, W as startClientService, X as ClientRuntime, Y as stopPostgres, Z as handleClientOrgMismatch, _ as promptMissingFields, _t as probeCapabilities, a as declineUpdate, at as fail, b as onboardCheck, c as detectInstallMode, ct as print, d as startServer, dt as ClientOrgMismatchError, et as formatStaleReason, f as COMMAND_VERSION, ft as ClientUserMismatchError, g as promptAddAgent, gt as cleanWorkspaces, h as isInteractive, ht as SessionRegistry, i as createExecuteUpdate, it as resolveReplyToFromEnv, j as checkDocker, k as checkClientConfig, l as fetchLatestVersion, lt as setJsonMode, m as uploadClientCapabilities, mt as SdkError, nt as createOwner, o as promptUpdate, ot as success, p as reconcileLocalRuntimeProviders, pt as FirstTreeHubSDK, r as registerSaaSConnectCommand, s as PACKAGE_NAME, tt as removeLocalAgent, u as installGlobalLatest, v as formatCheckReport, vt as applyClientLoggerConfig, w as createApiNameResolver, x as onboardCreate, y as loadOnboardState, yt as configureClientLoggerForService, z as getClientServiceStatus } from "../saas-connect-DLVGb8OH.mjs";
 import "../logger-core-BTmvdflj-DjW8FM4T.mjs";
-import { C as serverConfigSchema, S as resolveConfigReadonly, _ as loadAgents, b as resetConfig, c as saveCredentials, d as DEFAULT_HOME_DIR, f as agentConfigSchema, g as initConfig, h as getConfigValue, i as loadCredentials, l as DEFAULT_CONFIG_DIR, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, r as ensureFreshAdminToken, s as saveAgentConfig, u as DEFAULT_DATA_DIR, w as setConfigValue, x as resetConfigMeta, y as readConfigFile } from "../bootstrap-jx5nN1qZ.mjs";
+import { C as serverConfigSchema, S as resolveConfigReadonly, _ as loadAgents, b as resetConfig, c as saveCredentials, d as DEFAULT_HOME_DIR, f as agentConfigSchema, g as initConfig, h as getConfigValue, i as loadCredentials, l as DEFAULT_CONFIG_DIR, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, r as ensureFreshAdminToken, s as saveAgentConfig, u as DEFAULT_DATA_DIR, w as setConfigValue, x as resetConfigMeta, y as readConfigFile } from "../bootstrap-CDeXqhkQ.mjs";
 import "../dist-DwbhZyGi.mjs";
 import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-viiZmwcn.mjs";
 import "../invitation-B1pjAyOz-BaCA9PII.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import * as semver from "semver";
 import { Command } from "commander";
 import { confirm, input, password, select } from "@inquirer/prompts";
 //#region src/commands/agent-config.ts
@@ -235,7 +236,7 @@ function createSdk(agentName) {
 	const { serverUrl, agentId } = resolveLocalAgent(agentName);
 	return new FirstTreeHubSDK({
 		serverUrl,
-		getAccessToken: () => ensureFreshAccessToken(),
+		getAccessToken: (opts) => ensureFreshAccessToken(opts),
 		agentId
 	});
 }
@@ -335,7 +336,7 @@ function registerAgentCommands(program) {
 			const clientId = readClientId();
 			const sdk = new FirstTreeHubSDK({
 				serverUrl,
-				getAccessToken: () => ensureFreshAccessToken()
+				getAccessToken: (opts) => ensureFreshAccessToken(opts)
 			});
 			const stale = await findStaleAliases({
 				clientId,
@@ -1081,8 +1082,37 @@ function registerConnectCommand(parent) {
 function registerClientCommands(program) {
 	const client = program.command("client").description("Client runtime — connect agents to the server");
 	registerConnectCommand(client);
-	client.command("start").description("Start client — connect all configured agents to the server").option("--no-interactive", "Skip interactive prompts (for Docker/CI)").action(async (options) => {
+	client.command("start").description("Start client — connect all configured agents to the server").option("--no-interactive", "Skip interactive prompts (for Docker/CI)").option("--foreground", "Run inline instead of delegating to the background service (for debugging)").action(async (options) => {
 		try {
+			const isSupervisorChild = options.interactive === false && process.env.FIRST_TREE_HUB_SERVICE_MODE === "1";
+			if (!(options.foreground === true || isSupervisorChild) && isServiceSupported()) {
+				const svc = getClientServiceStatus();
+				if (svc.state === "active") {
+					print.line("\n");
+					print.line(`  Service is already running (${svc.platform}${svc.detail ? `, ${svc.detail}` : ""}).\n`);
+					print.line("  Use `first-tree-hub client restart` to restart, or `--foreground` to run inline.\n\n");
+					return;
+				}
+				if (svc.state === "inactive") {
+					const res = startClientService();
+					if (!res.ok) {
+						print.line(`\n  Failed to start service: ${res.reason}\n`);
+						print.line("  Try `--foreground` to run inline instead.\n\n");
+						process.exit(1);
+					}
+					const after = getClientServiceStatus();
+					print.line("\n");
+					print.line(`  Started ${after.platform} service${after.detail ? ` (${after.detail})` : ""}.\n`);
+					const journalHint = after.platform === "systemd" ? `  (or \`journalctl --user -u ${after.label.replace(/\.service$/, "")}\`)` : "";
+					print.line(`  Logs:  ${after.logDir}${journalHint}\n\n`);
+					return;
+				}
+				if (svc.state === "unknown") {
+					print.line(`\n  Service state could not be determined (${svc.platform}${svc.detail ? `: ${svc.detail}` : ""}).\n`);
+					print.line("  Inspect with `first-tree-hub client doctor`, or pass `--foreground` to bypass.\n\n");
+					process.exit(1);
+				}
+			}
 			await promptMissingFields({
 				schema: clientConfigSchema,
 				role: "client",
@@ -1191,7 +1221,7 @@ function registerClientCommands(program) {
 			});
 			const sdk = new FirstTreeHubSDK({
 				serverUrl,
-				getAccessToken: () => ensureFreshAccessToken()
+				getAccessToken: (opts) => ensureFreshAccessToken(opts)
 			});
 			agentCheck = await reconcileAgentConfigs({
 				clientId: cfg.client.id,
@@ -1212,11 +1242,72 @@ function registerClientCommands(program) {
 			checkBackgroundService()
 		]);
 	});
-	client.command("stop").description("Stop the client (sends SIGTERM to running process)").action(() => {
-		print.line("  Client stop: use Ctrl+C or `kill` the running process.\n");
-		print.line("  Daemon mode with PID file is planned for a future release.\n");
+	client.command("stop").description("Stop the background service (preserves auto-start; use `client start` to bring it back)").action(() => {
+		if (!isServiceSupported()) {
+			print.line(`\n  Service control not supported on ${process.platform}.\n`);
+			print.line("  If running inline, use Ctrl+C or kill the process.\n\n");
+			return;
+		}
+		const svc = getClientServiceStatus();
+		if (svc.state === "not-installed") {
+			print.line("\n  No background service installed — nothing to stop.\n");
+			print.line("  If running inline, use Ctrl+C or kill the process.\n\n");
+			return;
+		}
+		if (svc.state === "inactive") {
+			print.line("\n  Service is already stopped.\n\n");
+			return;
+		}
+		const res = stopClientService();
+		if (!res.ok) {
+			print.line(`\n  Failed to stop service: ${res.reason}\n\n`);
+			process.exit(1);
+		}
+		print.line(`\n  Stopped ${svc.platform} service.\n`);
+		print.line("  Auto-start on next login is preserved. Run `first-tree-hub client start` to bring it back.\n\n");
+	});
+	client.command("restart").description("Restart the background service").action(() => {
+		if (!isServiceSupported()) {
+			print.line(`\n  Service control not supported on ${process.platform}.\n`);
+			print.line("  Restart your inline `client start` process manually.\n\n");
+			return;
+		}
+		if (getClientServiceStatus().state === "not-installed") {
+			print.line("\n  No background service installed.\n");
+			print.line("  Run `first-tree-hub client connect <url>` first.\n\n");
+			process.exit(1);
+		}
+		const res = restartClientService();
+		if (!res.ok) {
+			print.line(`\n  Failed to restart service: ${res.reason}\n\n`);
+			process.exit(1);
+		}
+		const after = getClientServiceStatus();
+		print.line(`\n  Restarted ${after.platform} service${after.detail ? ` (${after.detail})` : ""}.\n\n`);
 	});
-	client.command("status").description("Show client and agent connection status").action(() => {
+	client.command("status").description("Show CLI, service, hub, and agent status (one-screen overview)").action(() => {
+		print.line("\n");
+		print.line(`  CLI:      ${COMMAND_VERSION}\n`);
+		if (isServiceSupported()) {
+			const svc = getClientServiceStatus();
+			const tail = svc.platform === "systemd" ? `  (logs: journalctl --user -u ${svc.label.replace(/\.service$/, "")} -f)` : "";
+			if (svc.state === "active") print.line(`  Service:  ✓ running (${svc.platform}${svc.detail ? `, ${svc.detail}` : ""})${tail}\n`);
+			else if (svc.state === "inactive") print.line(`  Service:  ✗ stopped (${svc.platform}${svc.detail ? `, ${svc.detail}` : ""})\n`);
+			else if (svc.state === "not-installed") print.line("  Service:  not installed — run `first-tree-hub client connect <url>`\n");
+			else print.line(`  Service:  unknown (${svc.platform}${svc.detail ? `, ${svc.detail}` : ""})\n`);
+		} else print.line(`  Service:  not supported on ${process.platform} (runs inline)\n`);
+		const clientYaml = join(DEFAULT_CONFIG_DIR, "client.yaml");
+		if (existsSync(clientYaml)) try {
+			const cfg = readConfigFile(clientYaml);
+			const serverUrl = getNested(cfg, "server.url");
+			const clientId = getNested(cfg, "client.id");
+			print.line(`  Hub:      ${serverUrl ?? "(not configured)"}\n`);
+			print.line(`  Client:   ${clientId ?? "(not configured)"}\n`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			print.line(`  Hub:      (could not read ${clientYaml}: ${msg.slice(0, 60)})\n`);
+		}
+		else print.line("  Hub:      (not configured — run `first-tree-hub client connect <url>`)\n");
 		const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
 		try {
 			const agents = loadAgents({
@@ -1224,14 +1315,14 @@ function registerClientCommands(program) {
 				agentsDir
 			});
 			if (agents.size === 0) {
-				print.line("  No agents configured.\n");
+				print.line("  Agents:   0 configured\n\n");
 				return;
 			}
-			print.line("\n  Configured agents:\n\n");
-			for (const [name, config] of agents) print.line(`  ${name.padEnd(20)} runtime: ${config.runtime.padEnd(14)} agentId: ${config.agentId}\n`);
+			print.line(`  Agents:   ${agents.size} configured\n\n`);
+			for (const [name, config] of agents) print.line(`    ${name.padEnd(20)} runtime: ${config.runtime.padEnd(14)} agentId: ${config.agentId}\n`);
 			print.line("\n");
 		} catch {
-			print.line("  No agents directory found.\n");
+			print.line("  Agents:   (no agents directory)\n\n");
 		}
 	});
 	client.command("hub-list").description("List clients on the Hub server").option("--server <url>", "Hub server URL").action(async (options) => {
@@ -1303,7 +1394,7 @@ function registerClientCommands(program) {
 			try {
 				const sdk = new FirstTreeHubSDK({
 					serverUrl,
-					getAccessToken: () => ensureFreshAccessToken()
+					getAccessToken: (opts) => ensureFreshAccessToken(opts)
 				});
 				const stale = await findStaleAliases({
 					clientId,
@@ -1374,6 +1465,15 @@ function timeSince(isoDate) {
 	if (hours < 24) return `${hours}h ${minutes % 60}m`;
 	return `${Math.floor(hours / 24)}d ${hours % 24}h`;
 }
+/** Read a `dot.path.like.this` from a parsed YAML object, returning string | null. */
+function getNested(obj, path) {
+	let cur = obj;
+	for (const part of path.split(".")) {
+		if (cur === null || cur === void 0 || typeof cur !== "object") return null;
+		cur = cur[part];
+	}
+	return typeof cur === "string" ? cur : null;
+}
 //#endregion
 //#region src/commands/config.ts
 function resolveConfigPath(flags) {
@@ -1471,13 +1571,13 @@ function isSecretField(schema, dotPath) {
 //#region src/commands/onboard.ts
 async function promptMissing(args) {
 	if (!args.server) try {
-		const { resolveServerUrl } = await import("../bootstrap-jx5nN1qZ.mjs").then((n) => n.t);
+		const { resolveServerUrl } = await import("../bootstrap-CDeXqhkQ.mjs").then((n) => n.t);
 		resolveServerUrl();
 	} catch {
 		args.server = await input({ message: "Hub server URL:" });
 		saveOnboardState(args);
 	}
-	const { loadCredentials } = await import("../bootstrap-jx5nN1qZ.mjs").then((n) => n.t);
+	const { loadCredentials } = await import("../bootstrap-CDeXqhkQ.mjs").then((n) => n.t);
 	if (!loadCredentials()) throw new Error("No saved credentials. Run `first-tree-hub client connect <server-url>` before onboarding.");
 	if (!args.id) {
 		args.id = await input({ message: "Agent ID:" });
@@ -1679,62 +1779,92 @@ function registerServerCommands(program) {
 	});
 }
 //#endregion
-//#region src/commands/status.ts
-function registerStatusCommand(program) {
-	program.command("status").description("Global overview — server health + configured agents").action(async () => {
-		print.line("\n");
-		const serverConfig = readConfigFile(join(DEFAULT_CONFIG_DIR, "server.yaml"));
-		const serverPort = getNestedValue(serverConfig, "server.port") ?? 8e3;
-		const serverUrl = `http://${getNestedValue(serverConfig, "server.host") ?? "127.0.0.1"}:${serverPort}`;
+//#region src/commands/update.ts
+/**
+* `first-tree-hub update` — user-driven CLI upgrade.
+*
+* Lives at the top level (not under `client`) because the tarball bundles
+* server / client / web / shared into a single artifact: upgrading affects
+* the whole CLI, not the client subsystem alone.
+*
+* Pairs with — but does not replace — the server-driven UpdateManager
+* (packages/client/src/runtime/update-manager.ts), which fires automatically
+* when a connected client falls behind the server-bundled version. This
+* command is the manual equivalent: same install + restart sequence, but
+* triggered on the operator's terms.
+*/
+function registerUpdateCommand(program) {
+	program.command("update").description("Upgrade first-tree-hub to the latest published version and restart the service").option("--check", "Only check whether a newer version is available; do not install").option("--no-restart", "Install the new version but skip restarting the background service").action(async (options) => {
+		const mode = detectInstallMode();
+		if (mode === "source") {
+			print.line("\n  Running from a source checkout — `update` is a no-op.\n");
+			print.line("  Use `git pull` instead.\n\n");
+			return;
+		}
+		if (mode === "npx") {
+			print.line("\n  Not launched from a global npm install — cannot self-update.\n");
+			print.line(`  Install globally first:  npm i -g ${PACKAGE_NAME}\n\n`);
+			return;
+		}
+		print.line("\n  Checking npm registry...\n");
+		const latest = fetchLatestVersion();
+		if (!latest.ok) {
+			print.line(`  Could not fetch latest version: ${latest.reason}\n\n`);
+			process.exit(1);
+		}
+		const current = COMMAND_VERSION;
+		if ((semver.valid(current) ? semver.compare(current, latest.version) : -1) >= 0) {
+			print.line(`  Already on ${current} (latest is ${latest.version}).\n\n`);
+			return;
+		}
+		if (options.check) {
+			print.line(`  Update available: ${current} → ${latest.version}\n`);
+			print.line("  Run `first-tree-hub update` to install.\n\n");
+			return;
+		}
+		print.line(`  Updating ${current} → ${latest.version}...\n`);
+		const installRes = await installGlobalLatest();
+		if (!installRes.ok) {
+			print.line(`\n  Install failed: ${installRes.reason}\n\n`);
+			process.exit(1);
+		}
+		const installed = installRes.installedVersion ?? latest.version;
+		print.line(`  Installed ${installed}.\n`);
+		if (options.restart === false) {
+			print.line("  Skipping restart (--no-restart). Run `first-tree-hub client restart` when ready.\n\n");
+			return;
+		}
+		if (!isServiceSupported()) {
+			print.line(`  No service manager on ${process.platform}; restart your inline `);
+			print.line("`client start` process to pick up the new version.\n\n");
+			return;
+		}
+		const svc = getClientServiceStatus();
+		if (svc.state === "not-installed") {
+			print.line("  No background service installed — nothing to restart.\n");
+			print.line("  Run `first-tree-hub client connect <url>` to set one up.\n\n");
+			return;
+		}
 		try {
-			const res = await fetch(`${serverUrl}/api/v1/health`);
-			if (res.ok) {
-				const data = await res.json();
-				const uptime = data.uptime_seconds ? formatUptime(data.uptime_seconds) : "unknown";
-				print.line(`  Server:     ✓ running (${serverUrl}, uptime: ${uptime})\n`);
-			} else print.line(`  Server:     ✗ unhealthy (${res.status})\n`);
-		} catch {
-			print.line(`  Server:     ✗ not running (${serverUrl})\n`);
+			installClientService();
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			print.line(`  warning: unit-file refresh failed: ${msg}\n`);
+			print.line("  Continuing with restart against the old unit.\n");
 		}
-		const dbProvider = getNestedValue(serverConfig, "database.provider") ?? "unknown";
-		const hasDbUrl = getNestedValue(serverConfig, "database.url") !== void 0;
-		print.line(`  Database:   ${hasDbUrl ? "✓ configured" : "✗ not configured"} (${dbProvider})\n`);
-		const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
-		if (existsSync(agentsDir)) try {
-			const agents = loadAgents({
-				schema: agentConfigSchema,
-				agentsDir
-			});
-			print.line(`  Agents:     ${agents.size} configured\n`);
-		} catch {
-			print.line("  Agents:     error reading config\n");
-		}
-		else print.line("  Agents:     0 configured\n");
-		const clientConfigPath = join(DEFAULT_CONFIG_DIR, "client.yaml");
-		if (existsSync(clientConfigPath)) {
-			const clientServerUrl = getNestedValue(readConfigFile(clientConfigPath), "server.url");
-			print.line(`  Client:     configured → ${clientServerUrl}\n`);
-		} else print.line("  Client:     not configured\n");
-		print.line("\n");
+		if (svc.state === "inactive") {
+			print.line("  Service is stopped — leaving it stopped. Use `client start` to bring it up.\n\n");
+			return;
+		}
+		const restartRes = restartClientService();
+		if (!restartRes.ok) {
+			print.line(`\n  Service restart failed: ${restartRes.reason}\n`);
+			print.line("  Run `first-tree-hub client restart` to retry.\n\n");
+			process.exit(1);
+		}
+		print.line(`  Service restarted on ${installed}.\n\n`);
 	});
 }
-function getNestedValue(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 formatUptime(seconds) {
-	const days = Math.floor(seconds / 86400);
-	const hours = Math.floor(seconds % 86400 / 3600);
-	const mins = Math.floor(seconds % 3600 / 60);
-	if (days > 0) return `${days}d ${hours}h`;
-	if (hours > 0) return `${hours}h ${mins}m`;
-	return `${mins}m`;
-}
 //#endregion
 //#region src/cli/index.ts
 runHomeMigration();
@@ -1759,7 +1889,7 @@ registerServerCommands(program);
 registerClientCommands(program);
 registerAgentCommands(program);
 registerConfigCommands(program);
-registerStatusCommand(program);
+registerUpdateCommand(program);
 registerOnboardCommand(program);
 program.parse();
 //#endregion

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import "./observability-DPyf745N-BSc8QNcR.mjs";
-import { A as checkServerHealth, B as ensurePostgres, C as checkAgentConfigs, D as checkDocker, E as checkDatabase, F as getClientServiceStatus, G as rotateClientIdWithBackup, H as stopPostgres, I as installClientService, L as isServiceSupported, M as checkWebSocket, N as printResults, O as checkNodeVersion, R as resolveCliInvocation, S as runMigrations, T as checkClientConfig, U as ClientRuntime, V as isDockerAvailable, W as handleClientOrgMismatch, X as hasUser, Y as createOwner, _ as onboardCreate, d as isInteractive, et as blank, f as promptAddAgent, g as onboardCheck, j as checkServerReachable, k as checkServerConfig, m as formatCheckReport, n as deriveHubUrlFromToken, ot as FirstTreeHubSDK, p as promptMissingFields, rt as status, s as startServer, st as SdkError, t as HubUrlDerivationError, y as runHomeMigration, z as uninstallClientService } from "./saas-connect-CuJWyzzq.mjs";
+import { A as checkDatabase, B as installClientService, C as runHomeMigration, D as checkAgentConfigs, E as runMigrations, F as checkServerReachable, G as stopClientService, H as resolveCliInvocation, I as checkWebSocket, J as isDockerAvailable, K as uninstallClientService, L as printResults, M as checkNodeVersion, N as checkServerConfig, P as checkServerHealth, Q as rotateClientIdWithBackup, U as restartClientService, V as isServiceSupported, W as startClientService, X as ClientRuntime, Y as stopPostgres, Z as handleClientOrgMismatch, _ as promptMissingFields, b as onboardCheck, d as startServer, g as promptAddAgent, h as isInteractive, j as checkDocker, k as checkClientConfig, mt as SdkError, n as deriveHubUrlFromToken, nt as createOwner, pt as FirstTreeHubSDK, q as ensurePostgres, rt as hasUser, st as blank, t as HubUrlDerivationError, ut as status, v as formatCheckReport, x as onboardCreate, z as getClientServiceStatus } from "./saas-connect-DLVGb8OH.mjs";
 import "./logger-core-BTmvdflj-DjW8FM4T.mjs";
-import { a as resolveAccessToken, n as ensureFreshAccessToken, o as resolveServerUrl, r as ensureFreshAdminToken } from "./bootstrap-jx5nN1qZ.mjs";
+import { a as resolveAccessToken, n as ensureFreshAccessToken, o as resolveServerUrl, r as ensureFreshAdminToken } from "./bootstrap-CDeXqhkQ.mjs";
 import "./dist-DwbhZyGi.mjs";
 import { n as bindFeishuUser, t as bindFeishuBot } from "./feishu-viiZmwcn.mjs";
 import "./invitation-B1pjAyOz-BaCA9PII.mjs";
-export { ClientRuntime, FirstTreeHubSDK, HubUrlDerivationError, SdkError, bindFeishuBot, bindFeishuUser, blank, checkAgentConfigs, checkClientConfig, checkDatabase, checkDocker, checkNodeVersion, checkServerConfig, checkServerHealth, checkServerReachable, checkWebSocket, createOwner, deriveHubUrlFromToken, ensureFreshAccessToken, ensureFreshAdminToken, ensurePostgres, formatCheckReport, getClientServiceStatus, handleClientOrgMismatch, hasUser, installClientService, isDockerAvailable, isInteractive, isServiceSupported, onboardCheck, onboardCreate, printResults, promptAddAgent, promptMissingFields, resolveAccessToken, resolveCliInvocation, resolveServerUrl, rotateClientIdWithBackup, runHomeMigration, runMigrations, startServer, status, stopPostgres, uninstallClientService };
+export { ClientRuntime, FirstTreeHubSDK, HubUrlDerivationError, SdkError, bindFeishuBot, bindFeishuUser, blank, checkAgentConfigs, checkClientConfig, checkDatabase, checkDocker, checkNodeVersion, checkServerConfig, checkServerHealth, checkServerReachable, checkWebSocket, createOwner, deriveHubUrlFromToken, ensureFreshAccessToken, ensureFreshAdminToken, ensurePostgres, formatCheckReport, getClientServiceStatus, handleClientOrgMismatch, hasUser, installClientService, isDockerAvailable, isInteractive, isServiceSupported, onboardCheck, onboardCreate, printResults, promptAddAgent, promptMissingFields, resolveAccessToken, resolveCliInvocation, resolveServerUrl, restartClientService, rotateClientIdWithBackup, runHomeMigration, runMigrations, startClientService, startServer, status, stopClientService, stopPostgres, uninstallClientService };

package/dist/{saas-connect-CuJWyzzq.mjs → saas-connect-DLVGb8OH.mjs}

@@ -1,11 +1,11 @@
 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-DPyf745N-BSc8QNcR.mjs";
-import { C as serverConfigSchema, S as resolveConfigReadonly, _ as loadAgents, b as resetConfig, c as saveCredentials, 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, x as resetConfigMeta } from "./bootstrap-jx5nN1qZ.mjs";
+import { C as serverConfigSchema, S as resolveConfigReadonly, _ as loadAgents, b as resetConfig, c as saveCredentials, 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, x as resetConfigMeta } from "./bootstrap-CDeXqhkQ.mjs";
 import { $ as refreshTokenSchema, A as createOrgFromMeSchema, B as imageInlineContentSchema, C as clientRegisterSchema, D as createAgentSchema, E as createAdapterMappingSchema, F as dryRunAgentRuntimeConfigSchema, G as isReservedAgentName$1, H as inboxDeliverFrameSchema$1, I as extractMentions, J as loginSchema, K as joinByInvitationSchema, L as githubCallbackQuerySchema, M as createTaskSchema, N as defaultRuntimeConfigPayload, O as createChatSchema, P as delegateFeishuUserSchema, Q as rebindAgentSchema, R as githubDevCallbackQuerySchema, S as clientCapabilitiesSchema$1, St as wsAuthFrameSchema, T as createAdapterConfigSchema, U as inboxPollQuerySchema, V as inboxAckFrameSchema, W as isRedactedEnvValue, X as notificationQuerySchema, Y as messageSourceSchema$1, Z as paginationQuerySchema, _ as adminUpdateTaskSchema, _t as updateClientCapabilitiesSchema, a as AGENT_STATUSES, at as sendToAgentSchema, b as agentRuntimeConfigPayloadSchema$1, bt as updateSystemConfigSchema, ct as sessionEventSchema$1, d as TASK_HEALTH_SIGNALS, dt as switchOrgSchema, et as runtimeStateMessageSchema, f as TASK_STATUSES, ft as taskListQuerySchema, g as adminCreateTaskSchema, gt as updateChatSchema, h as addParticipantSchema, ht as updateAgentSchema, i as AGENT_SOURCES, it as sendMessageSchema, j as createOrganizationSchema, k as createMemberSchema, l as SYSTEM_CONFIG_DEFAULTS, lt as sessionReconcileRequestSchema, m as WS_AUTH_FRAME_TIMEOUT_MS, mt as updateAgentRuntimeConfigSchema, n as AGENT_NAME_REGEX$1, nt as scanMentionTokens, o as AGENT_TYPES, ot as sessionCompletionMessageSchema, p as TASK_TERMINAL_STATUSES, pt as updateAdapterConfigSchema, q as linkTaskChatSchema, r as AGENT_SELECTOR_HEADER$1, rt as selfServiceFeishuBotSchema, s as AGENT_VISIBILITY, st as sessionEventMessageSchema, t as AGENT_BIND_REJECT_REASONS, tt as safeRedirectPath, u as TASK_CREATOR_TYPES, ut as sessionStateMessageSchema, v as agentBindRequestSchema, vt as updateMemberSchema, w as connectTokenExchangeSchema, x as agentTypeSchema$1, xt as updateTaskStatusSchema, y as agentPinnedMessageSchema$1, yt as updateOrganizationSchema, z as githubStartQuerySchema } from "./dist-DwbhZyGi.mjs";
 import { _ as recordRedemption, a as ConflictError, b as uuidv7, c as UnauthorizedError, d as findActiveByToken, f as getActiveInvitation, h as organizations, i as ClientUserMismatchError$1, l as buildInviteUrl, m as invitations, n as BadRequestError, o as ForbiddenError, p as invitationRedemptions, r as ClientOrgMismatchError$1, s as NotFoundError, t as AppError, u as ensureActiveInvitation, y as users } from "./invitation-B1pjAyOz-BaCA9PII.mjs";
 import { createRequire } from "node:module";
 import { ZodError, z } from "zod";
-import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, 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";
@@ -1539,11 +1539,14 @@ defineConfig({
 		})
 	}) }),
 	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
+	trustProxy: field(z.boolean().default(false), { env: "FIRST_TREE_HUB_TRUST_PROXY" }),
 	rateLimit: optional({
 		max: field(z.number().default(100), { env: "FIRST_TREE_HUB_RATE_LIMIT_MAX" }),
 		loginMax: field(z.number().default(5), { env: "FIRST_TREE_HUB_RATE_LIMIT_LOGIN_MAX" }),
-		webhookMax: field(z.number().default(60), { env: "FIRST_TREE_HUB_RATE_LIMIT_WEBHOOK_MAX" })
+		webhookMax: field(z.number().default(60), { env: "FIRST_TREE_HUB_RATE_LIMIT_WEBHOOK_MAX" }),
+		agentMessageMax: field(z.number().default(30), { env: "FIRST_TREE_HUB_RATE_LIMIT_AGENT_MESSAGE_MAX" })
 	}),
+	ws: optional({ maxPayload: field(z.number().int().min(1024).default(262144), { env: "FIRST_TREE_HUB_WS_MAX_PAYLOAD" }) }),
 	inbox: optional({ maxInFlightPerAgent: field(z.number().int().min(1).max(1024).default(32), { env: "FIRST_TREE_HUB_INBOX_MAX_IN_FLIGHT_PER_AGENT" }) }),
 	kael: optional({
 		endpoint: field(z.string(), { env: "KAEL_ENDPOINT" }),
@@ -2061,7 +2064,7 @@ var ClientConnection = class extends EventEmitter {
 				this.reconnectAttempt = 0;
 				this.wsLogger.debug("socket opened, sending auth");
 				try {
-					const token = await this.getAccessToken();
+					const token = await this.getAccessToken({ minValidityMs: AUTH_REFRESH_LEAD_MS + 5e3 });
 					ws.send(JSON.stringify({
 						type: "auth",
 						token
@@ -2093,7 +2096,11 @@ var ClientConnection = class extends EventEmitter {
 					settle(reject, typedErr ?? /* @__PURE__ */ new Error(`WebSocket closed before ready (code ${code})`));
 					return;
 				}
-				this.wsLogger.warn({
+				if (code === 1e3) this.wsLogger.info({
+					code,
+					wasRegistered
+				}, "disconnected");
+				else this.wsLogger.warn({
 					code,
 					wasRegistered
 				}, "disconnected");
@@ -6254,7 +6261,7 @@ var ClientRuntime = class {
 			serverUrl,
 			clientId,
 			sdkVersion: options.currentVersion,
-			getAccessToken: () => ensureFreshAccessToken()
+			getAccessToken: (opts) => ensureFreshAccessToken(opts)
 		});
 		registerBuiltinHandlers();
 		this.connection.on("auth:expired", () => {
@@ -6637,6 +6644,37 @@ function runCapture(program, args, timeoutMs) {
 		]
 	});
 	if (res.status === 0) return { ok: true };
+	if (res.signal) return {
+		ok: false,
+		stderr: `${program} timed out after ${timeoutMs}ms (signal=${res.signal})`,
+		code: null
+	};
+	return {
+		ok: false,
+		stderr: (res.stderr ?? "").trim(),
+		code: res.status
+	};
+}
+/** Same as runCapture but also returns stdout — for queries (loginctl show-user, etc.). */
+function runCaptureOut(program, args, timeoutMs) {
+	const res = spawnSync(program, args, {
+		encoding: "utf-8",
+		timeout: timeoutMs,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (res.status === 0) return {
+		ok: true,
+		stdout: (res.stdout ?? "").trim()
+	};
+	if (res.signal) return {
+		ok: false,
+		stderr: `${program} timed out after ${timeoutMs}ms (signal=${res.signal})`,
+		code: null
+	};
 	return {
 		ok: false,
 		stderr: (res.stderr ?? "").trim(),
@@ -6647,8 +6685,40 @@ 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";
+/**
+* Map a `FIRST_TREE_HUB_HOME` basename to the suffix appended to the
+* service manager's unit name / label.
+*
+* Why this exists: `FIRST_TREE_HUB_HOME` already isolates config /
+* credentials / workspace under a separate home dir, but until now the
+* systemd unit name and launchd label were hard-coded — so a developer
+* running with an isolated home would still rewrite the same
+* `first-tree-hub-client.service` unit file as the prod install. This
+* derivation closes that loop: dev homes get their own unit name and
+* coexist with prod.
+*
+* Rule:
+*   - "hub" → ""        (default home; preserves the existing prod
+*                        unit name `first-tree-hub-client.service` for
+*                        every machine already in the field)
+*   - "hub-<x>" → "<x>" ("hub-test" → "test", giving
+*                        `first-tree-hub-client-test.service`)
+*   - anything else → the basename verbatim (a custom home like
+*                     "~/.first-tree/foo" yields suffix "foo")
+*
+* Empty / falsy basenames defensively fall back to the default — we
+* never want to silently drop a user's intent into prod's unit name.
+*/
+function deriveServiceSuffix(homeBasename) {
+	if (!homeBasename) return "";
+	if (homeBasename === "hub") return "";
+	if (homeBasename.startsWith("hub-")) return homeBasename.slice(4) || homeBasename;
+	return homeBasename;
+}
+const SERVICE_SUFFIX = deriveServiceSuffix(basename(DEFAULT_HOME_DIR$1));
+const LAUNCHD_LABEL = SERVICE_SUFFIX ? `dev.first-tree-hub.client.${SERVICE_SUFFIX}` : "dev.first-tree-hub.client";
+const SYSTEMD_UNIT = SERVICE_SUFFIX ? `first-tree-hub-client-${SERVICE_SUFFIX}.service` : "first-tree-hub-client.service";
+const SYSLOG_IDENT = SERVICE_SUFFIX ? `first-tree-hub-client-${SERVICE_SUFFIX}` : "first-tree-hub-client";
 const LOG_DIR = join(DEFAULT_HOME_DIR$1, "logs");
 function whichBin(name) {
 	try {
@@ -6663,23 +6733,36 @@ function whichBin(name) {
 /**
 * 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).
+* Two regimes:
+*
+*   ① Prod (default home, empty service suffix) — prefer the installed
+*      `first-tree-hub` bin on PATH (usually a shim under /usr/local/bin
+*      or ~/.npm-global/bin). Using the shim means an `npm i -g … @latest`
+*      atomically swaps the binary the unit launches, no unit rewrite
+*      needed.
+*
+*   ② Dev / isolated (non-empty suffix from a custom FIRST_TREE_HUB_HOME)
+*      — pin to the running interpreter + script path. This skips the
+*      PATH lookup, which would otherwise resolve `first-tree-hub` to
+*      the operator's prod global install — making the dev unit silently
+*      run prod code against a dev home (i.e., the whole isolation story
+*      collapses with no error message). Pinning execPath+argv[1] forces
+*      the dev unit to launch the dev build that just installed it.
 */
-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
-		};
+function resolveCliInvocation(serviceSuffix = SERVICE_SUFFIX) {
+	if (serviceSuffix === "") {
+		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).");
@@ -6729,7 +6812,7 @@ ${argsXml}
     <key>PATH</key>
     <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
     <key>FIRST_TREE_HUB_SERVICE_MODE</key>
-    <string>1</string>
+    <string>1</string>${SERVICE_SUFFIX ? `\n    <key>FIRST_TREE_HUB_HOME</key>\n    <string>${escapeXml(DEFAULT_HOME_DIR$1)}</string>` : ""}
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -6773,9 +6856,12 @@ function launchdState() {
 	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();
+		const pidStr = pidLine?.split("=")[1]?.trim();
+		const pidNum = pidStr ? Number(pidStr) : NaN;
+		const pid = Number.isFinite(pidNum) && pidNum > 0 ? pidNum : void 0;
 		return {
 			state: "active",
+			pid,
 			detail: pid ? `pid ${pid}` : "running"
 		};
 	}
@@ -6818,7 +6904,7 @@ function installLaunchd() {
 	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);
+	if (!waitForLabelEvicted(target, LAUNCHD_LABEL, 1e4)) print.line("    warning: launchctl bootout still settling after 10s; bootstrap may need a retry\n");
 	let lastBootstrapErr = null;
 	for (let attempt = 1; attempt <= 2; attempt++) {
 		const res = runCapture("launchctl", [
@@ -6836,13 +6922,14 @@ function installLaunchd() {
 	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();
+	const { state, pid, detail } = launchdState();
 	return {
 		platform: "launchd",
 		label: LAUNCHD_LABEL,
 		unitPath: plistPath,
 		logDir: LOG_DIR,
 		state,
+		pid,
 		detail
 	};
 }
@@ -6865,20 +6952,25 @@ function systemdUnitPath() {
 function renderSystemdUnit(invocation) {
 	return `[Unit]
 Description=First Tree Hub Client
-After=network-online.target
-Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=10
 
 [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
+Restart=on-failure
 RestartSec=10
-StandardOutput=append:${join(LOG_DIR, "client.stdout.log")}
-StandardError=append:${join(LOG_DIR, "client.stderr.log")}
+SuccessExitStatus=0
+RestartForceExitStatus=75
+KillSignal=SIGTERM
+KillMode=mixed
+TimeoutStopSec=30
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=${SYSLOG_IDENT}
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
 Environment=FIRST_TREE_HUB_SERVICE_MODE=1
-
-[Install]
+${SERVICE_SUFFIX ? `Environment=FIRST_TREE_HUB_HOME=${shellQuote(DEFAULT_HOME_DIR$1)}\n` : ""}[Install]
 WantedBy=default.target
 `;
 }
@@ -6902,15 +6994,75 @@ function systemdState() {
 		]
 	});
 	const out = (res.stdout ?? "").trim();
-	if (res.status === 0 && out === "active") return {
-		state: "active",
-		detail: "running"
-	};
+	if (res.status === 0 && out === "active") {
+		const pid = readSystemdMainPid();
+		return {
+			state: "active",
+			pid,
+			detail: pid ? `pid ${pid}` : "running"
+		};
+	}
 	return {
 		state: "inactive",
 		detail: out || "unit present but not active"
 	};
 }
+function readSystemdMainPid() {
+	const res = runCaptureOut("systemctl", [
+		"--user",
+		"show",
+		SYSTEMD_UNIT,
+		"-p",
+		"MainPID",
+		"--value"
+	], 5e3);
+	if (!res.ok) return void 0;
+	const n = Number(res.stdout);
+	return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+/**
+* Best-effort `loginctl enable-linger` for the current user.
+*
+* Why this matters: a `--user` systemd service is tied to the user's session.
+* Without linger, when the user logs out (closes their last SSH session,
+* graphical session ends, etc.) the user's systemd manager exits and stops
+* every service it owns — including ours. The next login restarts everything,
+* which is silently wrong: agents go offline for hours and the operator has
+* no obvious cause.
+*
+* `enable-linger <self>` is allowed without sudo on systemd ≥ 240 thanks to
+* polkit's `org.freedesktop.login1.set-self-linger` rule. On older distros
+* or hardened setups it requires polkit auth — we don't try to escalate;
+* the warning printed by the caller is the operator's signal to run it
+* manually.
+*/
+function tryEnableLinger() {
+	const username = userInfo().username;
+	if (!username) return {
+		ok: false,
+		reason: "could not determine username"
+	};
+	const showRes = runCaptureOut("loginctl", [
+		"show-user",
+		username,
+		"-p",
+		"Linger",
+		"--value"
+	], 5e3);
+	if (showRes.ok && showRes.stdout === "yes") return {
+		ok: true,
+		alreadyOn: true
+	};
+	const res = runCapture("loginctl", ["enable-linger", username], 5e3);
+	if (res.ok) return {
+		ok: true,
+		alreadyOn: false
+	};
+	return {
+		ok: false,
+		reason: res.stderr || `exit ${res.code ?? "unknown"}`
+	};
+}
 function installSystemd() {
 	const invocation = resolveCliInvocation();
 	ensureLogDir();
@@ -6919,6 +7071,8 @@ function installSystemd() {
 	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 lingerRes = tryEnableLinger();
+	if (!lingerRes.ok) print.line(`    warning: loginctl enable-linger failed: ${lingerRes.reason}\n    The service will stop when you log out. Run manually: sudo loginctl enable-linger ${userInfo().username}\n`);
 	const enableRes = runCapture("systemctl", [
 		"--user",
 		"enable",
@@ -6926,13 +7080,14 @@ function installSystemd() {
 		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();
+	const { state, pid, detail } = systemdState();
 	return {
 		platform: "systemd",
 		label: SYSTEMD_UNIT,
 		unitPath,
 		logDir: LOG_DIR,
 		state,
+		pid,
 		detail
 	};
 }
@@ -6973,24 +7128,26 @@ function installClientService() {
 /** Report the current service state without modifying anything. */
 function getClientServiceStatus() {
 	if (process.platform === "darwin") {
-		const { state, detail } = launchdState();
+		const { state, pid, detail } = launchdState();
 		return {
 			platform: "launchd",
 			label: LAUNCHD_LABEL,
 			unitPath: launchdPlistPath(),
 			logDir: LOG_DIR,
 			state,
+			pid,
 			detail
 		};
 	}
 	if (process.platform === "linux") {
-		const { state, detail } = systemdState();
+		const { state, pid, detail } = systemdState();
 		return {
 			platform: "systemd",
 			label: SYSTEMD_UNIT,
 			unitPath: systemdUnitPath(),
 			logDir: LOG_DIR,
 			state,
+			pid,
 			detail
 		};
 	}
@@ -7003,6 +7160,137 @@ function getClientServiceStatus() {
 		detail: `platform ${process.platform} not supported`
 	};
 }
+/** Start the service. No-op + ok if already running. */
+function startClientService() {
+	if (process.platform === "linux") {
+		const res = runCapture("systemctl", [
+			"--user",
+			"start",
+			SYSTEMD_UNIT
+		], 15e3);
+		if (!res.ok) return {
+			ok: false,
+			reason: res.stderr || `exit ${res.code ?? "unknown"}`
+		};
+		return { ok: true };
+	}
+	if (process.platform === "darwin") {
+		const target = launchctlDomainTarget();
+		const plistPath = launchdPlistPath();
+		if (!existsSync(plistPath)) return {
+			ok: false,
+			reason: "service not installed"
+		};
+		if (runCaptureOut("launchctl", ["print", `${target}/${LAUNCHD_LABEL}`], 5e3).ok) {
+			const res = runCapture("launchctl", ["kickstart", `${target}/${LAUNCHD_LABEL}`], 1e4);
+			if (!res.ok) return {
+				ok: false,
+				reason: res.stderr || `exit ${res.code ?? "unknown"}`
+			};
+			return { ok: true };
+		}
+		const res = runCapture("launchctl", [
+			"bootstrap",
+			target,
+			plistPath
+		], 1e4);
+		if (!res.ok) return {
+			ok: false,
+			reason: res.stderr || `exit ${res.code ?? "unknown"}`
+		};
+		return { ok: true };
+	}
+	return {
+		ok: false,
+		reason: `service control not supported on ${process.platform}`
+	};
+}
+/**
+* Stop the service without disabling auto-start on next boot/login.
+*
+* systemd: `systemctl --user stop` — unit stays enabled, so a reboot or
+* `client start` brings it back. Combined with `Restart=on-failure +
+* SuccessExitStatus=0` in the unit, the SIGTERM path actually terminates
+* (the bug `Restart=always` had: stop would be immediately undone).
+*
+* launchd: `launchctl bootout` — unloads the running registration but
+* leaves the plist in `~/Library/LaunchAgents/`, so the next user login
+* (or `client start`) reloads it.
+*/
+function stopClientService() {
+	if (process.platform === "linux") {
+		const res = runCapture("systemctl", [
+			"--user",
+			"stop",
+			SYSTEMD_UNIT
+		], 35e3);
+		if (!res.ok) return {
+			ok: false,
+			reason: res.stderr || `exit ${res.code ?? "unknown"}`
+		};
+		return { ok: true };
+	}
+	if (process.platform === "darwin") {
+		const res = runCapture("launchctl", ["bootout", `${launchctlDomainTarget()}/${LAUNCHD_LABEL}`], 3e4);
+		if (!res.ok) {
+			if (/not find|no such|not loaded/i.test(res.stderr)) return {
+				ok: true,
+				detail: "not running"
+			};
+			return {
+				ok: false,
+				reason: res.stderr || `exit ${res.code ?? "unknown"}`
+			};
+		}
+		return { ok: true };
+	}
+	return {
+		ok: false,
+		reason: `service control not supported on ${process.platform}`
+	};
+}
+/** Restart the service. Equivalent to stop + start, but uses the manager's atomic primitive. */
+function restartClientService() {
+	if (process.platform === "linux") {
+		const res = runCapture("systemctl", [
+			"--user",
+			"restart",
+			SYSTEMD_UNIT
+		], 45e3);
+		if (!res.ok) return {
+			ok: false,
+			reason: res.stderr || `exit ${res.code ?? "unknown"}`
+		};
+		return { ok: true };
+	}
+	if (process.platform === "darwin") {
+		const target = launchctlDomainTarget();
+		const plistPath = launchdPlistPath();
+		if (!existsSync(plistPath)) return {
+			ok: false,
+			reason: "service not installed"
+		};
+		if (runCapture("launchctl", [
+			"kickstart",
+			"-k",
+			`${target}/${LAUNCHD_LABEL}`
+		], 3e4).ok) return { ok: true };
+		const bootstrapRes = runCapture("launchctl", [
+			"bootstrap",
+			target,
+			plistPath
+		], 1e4);
+		if (!bootstrapRes.ok) return {
+			ok: false,
+			reason: bootstrapRes.stderr || `exit ${bootstrapRes.code ?? "unknown"}`
+		};
+		return { ok: true };
+	}
+	return {
+		ok: false,
+		reason: `service control not supported on ${process.platform}`
+	};
+}
 /** Uninstall the background service. No-op if not installed. */
 function uninstallClientService() {
 	if (process.platform === "darwin") return uninstallLaunchd();
@@ -8756,7 +9044,7 @@ function createFeedbackHandler(config) {
 	return { handle };
 }
 //#endregion
-//#region ../server/dist/app-B1rxbSHG.mjs
+//#region ../server/dist/app-O9kCTpaF.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -14195,8 +14483,40 @@ const editMessageSchema = z.object({
 	format: z.string().optional(),
 	content: z.unknown()
 });
+/**
+* Per-agent rate limit on outbound message writes. Keyed by `agent.uuid`
+* (populated by `agentSelectorHook`, which runs as an onRequest hook before
+* the global limiter — registered with `hook: "preHandler"` — fires).
+*
+* Rationale: agent ↔ agent reply loops are the documented failure mode
+* (`mention_only` is the semantic guard; this is the hard ceiling).
+*
+* The IP fallback is **defensive scaffolding, not a real code path**. These
+* routes mount under `/agent` which forces `memberAuth + agentSelector`
+* onRequest hooks (see app.ts) — a missing `req.agent` would have already
+* 403'd before this preHandler runs. The fallback exists so that if a future
+* refactor reorders hooks (or detaches one of these routes from the agent
+* scope), the limiter degrades to per-IP keying with a logged warning rather
+* than silently keying everyone to the same `undefined` bucket.
+*/
+function agentMessageWriteRateLimit(max) {
+	return { rateLimit: {
+		max,
+		timeWindow: "1 minute",
+		keyGenerator: (req) => {
+			const agentId = req.agent?.uuid;
+			if (agentId) return `agent:${agentId}`;
+			log$2.warn({
+				ip: req.ip,
+				route: req.routeOptions?.url ?? req.url
+			}, "rate-limit keyGenerator fell back to IP — req.agent missing on a route under /agent (hook order regression?)");
+			return `ip:${req.ip}`;
+		}
+	} };
+}
 async function agentMessageRoutes(app) {
-	app.post("/:chatId/messages", async (request, reply) => {
+	const writeRateLimit = agentMessageWriteRateLimit(app.config.rateLimit?.agentMessageMax ?? 30);
+	app.post("/:chatId/messages", { config: writeRateLimit }, async (request, reply) => {
 		const identity = requireAgent(request);
 		await assertParticipant(app.db, request.params.chatId, identity.uuid);
 		const body = sendMessageSchema.parse(request.body);
@@ -14240,7 +14560,8 @@ async function agentMessageRoutes(app) {
 	});
 }
 async function agentSendToAgentRoutes(app) {
-	app.post("/:name/messages", async (request, reply) => {
+	const writeRateLimit = agentMessageWriteRateLimit(app.config.rateLimit?.agentMessageMax ?? 30);
+	app.post("/:name/messages", { config: writeRateLimit }, async (request, reply) => {
 		const identity = requireAgent(request);
 		const body = sendToAgentSchema.parse(request.body);
 		const { message: msg, recipients } = await sendToAgent(app.db, identity.uuid, request.params.name, body);
@@ -18015,7 +18336,11 @@ async function buildApp(config) {
 		format: config.observability.logging.format,
 		bridgeToSpanLevel: config.observability.logging.bridgeToSpanLevel
 	});
-	const app = Fastify({ loggerInstance: rootLogger$1 });
+	const app = Fastify({
+		loggerInstance: rootLogger$1,
+		trustProxy: config.trustProxy
+	});
+	if (config.trustProxy) app.log.warn("trustProxy=true — Fastify trusts ANY upstream's x-forwarded-for. Ensure Cloudflare / CapRover is the only ingress; do NOT expose this container's port to the public internet directly.");
 	const otelPlugin = getFastifyOtelPlugin();
 	if (otelPlugin) await app.register(otelPlugin);
 	await app.register(observabilityPlugin);
@@ -18027,7 +18352,7 @@ async function buildApp(config) {
 	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);
+	await app.register(websocket, { options: { maxPayload: config.ws?.maxPayload ?? 65536 } });
 	const corsOrigin = config.cors?.origin;
 	const isDev = process.env.NODE_ENV !== "production";
 	await app.register(cors, {
@@ -18036,7 +18361,8 @@ async function buildApp(config) {
 	});
 	await app.register(rateLimit, {
 		max: config.rateLimit?.max ?? 100,
-		timeWindow: "1 minute"
+		timeWindow: "1 minute",
+		hook: "preHandler"
 	});
 	const memberAuth = memberAuthHook(db, config.secrets.jwtSecret);
 	const adminOnly = requireAdminRoleHook();
@@ -18053,6 +18379,10 @@ async function buildApp(config) {
 			details: error.issues,
 			...traceField
 		});
+		if (error instanceof Error && "statusCode" in error && typeof error.statusCode === "number" && error.statusCode >= 400 && error.statusCode < 500) return reply.status(error.statusCode).send({
+			error: error.message,
+			...traceField
+		});
 		request.log.error({ err: error }, "unhandled request error");
 		return reply.status(500).send({
 			error: "Internal server error",
@@ -18426,12 +18756,27 @@ function resolveNpmCommand() {
 */
 function detectInstallMode(argv1 = process.argv[1] ?? "") {
 	if (!argv1) return "npx";
-	let dir = dirname(resolve(argv1));
+	let resolvedArgv1;
+	try {
+		resolvedArgv1 = realpathSync(argv1);
+	} catch {
+		resolvedArgv1 = argv1;
+	}
+	const start = dirname(resolve(resolvedArgv1));
+	{
+		let dir = start;
+		for (let i = 0; i < 10; i++) {
+			if (existsSync(resolve(dir, ".git"))) return "source";
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	}
+	let dir = start;
 	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 (JSON.parse(readFileSync(pkgPath, "utf8")).name === "@agent-team-foundation/first-tree-hub") {
 				if (/\/(?:_npx|\.npm\/_npx)\//.test(dir)) return "npx";
 				return "global";
 			}
@@ -18505,6 +18850,42 @@ function parseInstalledVersion(stdout) {
 function escapeForRegex(s) {
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/**
+* Look up the latest published version of the CLI package.
+*
+* Uses `npm view <pkg> version` (rather than fetch'ing registry.npmjs.org
+* directly) so the user's `.npmrc` registry, proxy, and auth settings are
+* honored — important for corporate users routed through Verdaccio /
+* Artifactory mirrors.
+*/
+function fetchLatestVersion(timeoutMs = 1e4) {
+	const res = spawnSync(resolveNpmCommand(), [
+		"view",
+		PACKAGE_NAME,
+		"version"
+	], {
+		encoding: "utf-8",
+		timeout: timeoutMs,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (res.status !== 0) return {
+		ok: false,
+		reason: (res.stderr ?? "").trim() || `npm view exited with code ${res.status}`
+	};
+	const version = (res.stdout ?? "").trim();
+	if (!semver.valid(version)) return {
+		ok: false,
+		reason: `npm view returned non-semver value: ${version.slice(0, 80)}`
+	};
+	return {
+		ok: true,
+		version
+	};
+}
 /** 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?`;
@@ -18754,4 +19135,4 @@ function registerSaaSConnectCommand(program) {
 	});
 }
 //#endregion
-export { success as $, checkServerHealth as A, ensurePostgres as B, checkAgentConfigs as C, checkDocker as D, checkDatabase as E, getClientServiceStatus as F, rotateClientIdWithBackup as G, stopPostgres as H, installClientService as I, removeLocalAgent as J, findStaleAliases as K, isServiceSupported as L, checkWebSocket as M, printResults as N, checkNodeVersion as O, reconcileAgentConfigs as P, fail as Q, resolveCliInvocation as R, runMigrations as S, checkClientConfig as T, ClientRuntime as U, isDockerAvailable as V, handleClientOrgMismatch as W, hasUser as X, createOwner as Y, resolveReplyToFromEnv as Z, onboardCreate as _, declineUpdate as a, ClientUserMismatchError as at, createApiNameResolver as b, COMMAND_VERSION as c, SessionRegistry as ct, isInteractive as d, applyClientLoggerConfig as dt, blank as et, promptAddAgent as f, configureClientLoggerForService as ft, onboardCheck as g, loadOnboardState as h, createExecuteUpdate as i, ClientOrgMismatchError as it, checkServerReachable as j, checkServerConfig as k, reconcileLocalRuntimeProviders as l, cleanWorkspaces as lt, formatCheckReport as m, deriveHubUrlFromToken as n, setJsonMode as nt, promptUpdate as o, FirstTreeHubSDK as ot, promptMissingFields as p, formatStaleReason as q, registerSaaSConnectCommand as r, status as rt, startServer as s, SdkError as st, HubUrlDerivationError as t, print as tt, uploadClientCapabilities as u, probeCapabilities as ut, saveOnboardState as v, checkBackgroundService as w, migrateLocalAgentDirs as x, runHomeMigration as y, uninstallClientService as z };
+export { findStaleAliases as $, checkDatabase as A, installClientService as B, runHomeMigration as C, checkAgentConfigs as D, runMigrations as E, checkServerReachable as F, stopClientService as G, resolveCliInvocation as H, checkWebSocket as I, isDockerAvailable as J, uninstallClientService as K, printResults as L, checkNodeVersion as M, checkServerConfig as N, checkBackgroundService as O, checkServerHealth as P, rotateClientIdWithBackup as Q, reconcileAgentConfigs as R, saveOnboardState as S, migrateLocalAgentDirs as T, restartClientService as U, isServiceSupported as V, startClientService as W, ClientRuntime as X, stopPostgres as Y, handleClientOrgMismatch as Z, promptMissingFields as _, probeCapabilities as _t, declineUpdate as a, fail as at, onboardCheck as b, detectInstallMode as c, print as ct, startServer as d, ClientOrgMismatchError as dt, formatStaleReason as et, COMMAND_VERSION as f, ClientUserMismatchError as ft, promptAddAgent as g, cleanWorkspaces as gt, isInteractive as h, SessionRegistry as ht, createExecuteUpdate as i, resolveReplyToFromEnv as it, checkDocker as j, checkClientConfig as k, fetchLatestVersion as l, setJsonMode as lt, uploadClientCapabilities as m, SdkError as mt, deriveHubUrlFromToken as n, createOwner as nt, promptUpdate as o, success as ot, reconcileLocalRuntimeProviders as p, FirstTreeHubSDK as pt, ensurePostgres as q, registerSaaSConnectCommand as r, hasUser as rt, PACKAGE_NAME as s, blank as st, HubUrlDerivationError as t, removeLocalAgent as tt, installGlobalLatest as u, status as ut, formatCheckReport as v, applyClientLoggerConfig as vt, createApiNameResolver as w, onboardCreate as x, loadOnboardState as y, configureClientLoggerForService as yt, getClientServiceStatus as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-team-foundation/first-tree-hub",
-  "version": "0.10.10",
+  "version": "0.10.12",
   "type": "module",
   "description": "First Tree Hub — unified CLI for server, client, and agent management",
   "exports": {