@agent-team-foundation/first-tree-hub 0.9.3 → 0.9.4

package/dist/cli/index.mjs

@@ -1,31 +1,24 @@
 #!/usr/bin/env node
-import "../logger-core-2yeIU1fc-B-__AsQO.mjs";
-import { C as serverConfigSchema, _ as loadAgents, b as resetConfig, c as saveCredentials, 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-CWcBzk6C.mjs";
-import "../observability-CJzDFY_G-CmvgUuzc.mjs";
-import { A as printResults, B as SdkError, C as checkDatabase, D as checkServerHealth, E as checkServerConfig, F as stopPostgres, H as cleanWorkspaces, I as ClientRuntime, L as createOwner, O as checkServerReachable, S as checkClientConfig, T as checkNodeVersion, U as applyClientLoggerConfig, V as SessionRegistry, _ as isServiceSupported, a as COMMAND_VERSION, b as runMigrations, c as promptMissingFields, d as onboardCheck, f as onboardCreate, g as installClientService, h as getClientServiceStatus, i as startServer, k as checkWebSocket, l as formatCheckReport, m as runHomeMigration, n as declineUpdate, o as isInteractive, p as saveOnboardState, r as promptUpdate, s as promptAddAgent, t as createExecuteUpdate, u as loadOnboardState, w as checkDocker, x as checkAgentConfigs, y as uninstallClientService, z as FirstTreeHubSDK } from "../core-Y7M3d2aZ.mjs";
+import "../observability-DV_fQKqV-CuLWzBxQ.mjs";
+import { A as checkServerHealth, C as runMigrations, D as checkDocker, E as checkDatabase, G as SdkError, H as setJsonMode, I as stopPostgres, J as applyClientLoggerConfig, K as SessionRegistry, L as ClientRuntime, M as checkWebSocket, N as printResults, O as checkNodeVersion, R as createOwner, S as uninstallClientService, T as checkClientConfig, V as print, W as FirstTreeHubSDK, Y as configureClientLoggerForService, _ as runHomeMigration, a as showServiceLogs, b as isServiceSupported, c as COMMAND_VERSION, d as promptMissingFields, f as formatCheckReport, g as saveOnboardState, h as onboardCreate, i as parseDuration, j as checkServerReachable, k as checkServerConfig, l as isInteractive, m as onboardCheck, n as declineUpdate, o as validateLevel, p as loadOnboardState, q as cleanWorkspaces, r as promptUpdate, s as startServer, t as createExecuteUpdate, u as promptAddAgent, v as getClientServiceStatus, w as checkAgentConfigs, y as installClientService } from "../core-USyOOh7y.mjs";
+import "../logger-core-BTmvdflj-DhdipBkV.mjs";
+import { C as serverConfigSchema, _ 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-DWifXj9b.mjs";
 import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-GlaczcVf.mjs";
-import { Command } from "commander";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { Command } from "commander";
 import { confirm, input, password, select } from "@inquirer/prompts";
 //#region src/cli/output.ts
-/** Write a success JSON envelope to stdout. */
+/**
+* CLI output re-exports. The underlying implementation lives in
+* `core/output.ts` (the Print layer). Keep these thin wrappers so callers that
+* only depend on `cli/output.ts` keep working during the migration.
+*/
 function success(data) {
-	process.stdout.write(`${JSON.stringify({
-		ok: true,
-		data
-	})}\n`);
+	print.result(data);
 }
-/** Write an error JSON envelope to stderr and exit with the given code. */
 function fail(code, message, exitCode = 1) {
-	process.stderr.write(`${JSON.stringify({
-		ok: false,
-		error: {
-			code,
-			message
-		}
-	})}\n`);
-	process.exit(exitCode);
+	return print.fail(code, message, exitCode);
 }
 //#endregion
 //#region src/commands/agent-config.ts
@@ -318,22 +311,22 @@ function registerAgentCommands(program) {
 				mode: 448
 			});
 			setConfigValue(join(agentDir, "agent.yaml"), "agentId", agentId);
-			process.stderr.write(`  Agent "${agentName}" added.\n`);
-			process.stderr.write(`  Config: ${join(agentDir, "agent.yaml")}\n`);
+			print.line(`  Agent "${agentName}" added.\n`);
+			print.line(`  Config: ${join(agentDir, "agent.yaml")}\n`);
 		} catch (error) {
 			if (error.name === "ExitPromptError") {
-				process.stderr.write("\n  Cancelled.\n");
+				print.line("\n  Cancelled.\n");
 				return;
 			}
 			const msg = error instanceof Error ? error.message : String(error);
-			process.stderr.write(`  Error: ${msg}\n`);
+			print.line(`  Error: ${msg}\n`);
 			process.exit(1);
 		}
 	});
 	agent.command("remove <name>").description("Remove a local agent alias and its runtime data").action((name) => {
 		const agentDir = join(DEFAULT_CONFIG_DIR, "agents", name);
 		if (!existsSync(agentDir)) {
-			process.stderr.write(`  Agent "${name}" not found.\n`);
+			print.line(`  Agent "${name}" not found.\n`);
 			process.exit(1);
 		}
 		rmSync(agentDir, {
@@ -345,7 +338,7 @@ function registerAgentCommands(program) {
 			force: true
 		});
 		rmSync(join(DEFAULT_DATA_DIR, "sessions", `${name}.json`), { force: true });
-		process.stderr.write(`  Agent "${name}" removed.\n`);
+		print.line(`  Agent "${name}" removed.\n`);
 	});
 	agent.command("list").description("List locally-configured agents").action(() => {
 		const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
@@ -355,12 +348,12 @@ function registerAgentCommands(program) {
 				agentsDir
 			});
 			if (agents.size === 0) {
-				process.stderr.write("  No agents configured.\n");
+				print.line("  No agents configured.\n");
 				return;
 			}
-			for (const [name, config] of agents) process.stderr.write(`  ${name.padEnd(20)} runtime: ${config.runtime.padEnd(14)} agentId: ${config.agentId}\n`);
+			for (const [name, config] of agents) print.line(`  ${name.padEnd(20)} runtime: ${config.runtime.padEnd(14)} agentId: ${config.agentId}\n`);
 		} catch {
-			process.stderr.write("  No agents configured.\n");
+			print.line("  No agents configured.\n");
 		}
 	});
 	agent.command("create <name>").description("Create an agent on Hub and bind it locally").requiredOption("--type <type>", "Agent type (human, personal_assistant, autonomous_agent)").requiredOption("--client-id <id>", "Client (machine) that will run this agent — must be owned by you. Run `first-tree-hub client connect` on that machine first.").option("--runtime <runtime>", "Runtime handler (default: claude-code)", "claude-code").option("--display-name <name>", "Display name").option("--server <url>", "Hub server URL").action(async (name, options) => {
@@ -384,10 +377,10 @@ function registerAgentCommands(program) {
 			});
 			if (!createRes.ok) fail("CREATE_ERROR", (await createRes.json().catch(() => ({}))).error ?? `Failed to create agent (HTTP ${createRes.status})`, 1);
 			const created = await createRes.json();
-			process.stderr.write(`  \u2713 Agent created: ${created.name ?? created.uuid}\n`);
+			print.line(`  \u2713 Agent created: ${created.name ?? created.uuid}\n`);
 			const agentDir = saveAgentConfig(name, created.uuid, options.runtime);
-			process.stderr.write(`  \u2713 Config saved: ${agentDir}/agent.yaml\n`);
-			process.stderr.write("  ✓ Agent ready — start the client on that machine to bind\n");
+			print.line(`  \u2713 Config saved: ${agentDir}/agent.yaml\n`);
+			print.line("  ✓ Agent ready — start the client on that machine to bind\n");
 		} catch (error) {
 			fail("CREATE_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -413,7 +406,7 @@ function registerAgentCommands(program) {
 				signal: AbortSignal.timeout(1e4)
 			});
 			if (!patchRes.ok) fail("CLAIM_ERROR", (await patchRes.json().catch(() => ({}))).error ?? `Claim failed (HTTP ${patchRes.status})`, 1);
-			process.stderr.write(`  Claimed "${target.name ?? target.uuid}" — now managed by you.\n`);
+			print.line(`  Claimed "${target.name ?? target.uuid}" — now managed by you.\n`);
 		} catch (error) {
 			fail("CLAIM_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -423,7 +416,7 @@ function registerAgentCommands(program) {
 		const ttlMs = Number.parseInt(options?.ttl ?? String(defaultDays), 10) * 24 * 60 * 60 * 1e3;
 		const workspacesDir = join(DEFAULT_DATA_DIR, "workspaces");
 		if (!existsSync(workspacesDir)) {
-			process.stderr.write("  No workspaces found.\n");
+			print.line("  No workspaces found.\n");
 			return;
 		}
 		const agentNames = agentName ? [agentName] : readdirSync(workspacesDir);
@@ -436,9 +429,9 @@ function registerAgentCommands(program) {
 			for (const [chatId, data] of persisted) if (data.status !== "evicted") activeChatIds.add(chatId);
 			const removed = cleanWorkspaces(agentWorkspaceRoot, activeChatIds, ttlMs);
 			totalRemoved += removed.length;
-			for (const chatId of removed) process.stderr.write(`  Removed: ${name}/${chatId}\n`);
+			for (const chatId of removed) print.line(`  Removed: ${name}/${chatId}\n`);
 		}
-		process.stderr.write(`  ${totalRemoved} workspace(s) cleaned.\n`);
+		print.line(`  ${totalRemoved} workspace(s) cleaned.\n`);
 	});
 	const bind = agent.command("bind").description("Bind an agent to a client machine or external IM account");
 	bind.command("client <agentName>").description("Bind an unbound agent to a client machine (first-time bind only — ID is immutable once set)").requiredOption("--client-id <id>", "Client (machine) ID — must be owned by you. Run `first-tree-hub client connect` on that machine first.").option("--server <url>", "Hub server URL").action(async (agentName, options) => {
@@ -456,7 +449,7 @@ function registerAgentCommands(program) {
 				signal: AbortSignal.timeout(1e4)
 			});
 			if (!patchRes.ok) fail("BIND_CLIENT_ERROR", (await patchRes.json().catch(() => ({}))).error ?? `Bind failed (HTTP ${patchRes.status})`, 1);
-			process.stderr.write(`  \u2713 Bound "${target.name ?? target.uuid}" to client ${options.clientId}.\n`);
+			print.line(`  \u2713 Bound "${target.name ?? target.uuid}" to client ${options.clientId}.\n`);
 			success({
 				agentId: target.uuid,
 				clientId: options.clientId
@@ -471,7 +464,7 @@ function registerAgentCommands(program) {
 			const serverUrl = resolveServerUrl(options.server);
 			const { agentId } = resolveLocalAgent(options.agent);
 			await bindFeishuBot(serverUrl, await ensureFreshAccessToken(), agentId, options.appId, options.appSecret);
-			process.stderr.write("Feishu bot bound successfully.\n");
+			print.line("Feishu bot bound successfully.\n");
 			success({
 				platform: "feishu",
 				bound: true
@@ -486,7 +479,7 @@ function registerAgentCommands(program) {
 			const serverUrl = resolveServerUrl(options.server);
 			const { agentId } = resolveLocalAgent(options.agent);
 			await bindFeishuUser(serverUrl, await ensureFreshAccessToken(), agentId, humanAgentId, options.feishuId);
-			process.stderr.write(`Feishu user ${options.feishuId} bound to ${humanAgentId}.\n`);
+			print.line(`Feishu user ${options.feishuId} bound to ${humanAgentId}.\n`);
 			success({
 				platform: "feishu",
 				humanAgentId,
@@ -560,30 +553,30 @@ function registerAgentCommands(program) {
 			if (name) {
 				const ag = data.agents.find((a) => a.agentId === name);
 				if (!ag) {
-					process.stderr.write(`\n  Agent "${name}" is not running.\n\n`);
+					print.line(`\n  Agent "${name}" is not running.\n\n`);
 					return;
 				}
-				process.stderr.write(`\n  Agent: ${ag.agentId}\n`);
-				process.stderr.write(`  Runtime: ${ag.runtimeType ?? "—"}\n`);
-				process.stderr.write(`  State: ${ag.runtimeState ?? "—"}\n`);
-				if (ag.activeSessions !== null) process.stderr.write(`  Sessions: ${ag.activeSessions} active / ${ag.totalSessions ?? 0} total\n`);
-				if (ag.clientId) process.stderr.write(`  Client: ${ag.clientId}\n`);
-				process.stderr.write("\n");
+				print.line(`\n  Agent: ${ag.agentId}\n`);
+				print.line(`  Runtime: ${ag.runtimeType ?? "—"}\n`);
+				print.line(`  State: ${ag.runtimeState ?? "—"}\n`);
+				if (ag.activeSessions !== null) print.line(`  Sessions: ${ag.activeSessions} active / ${ag.totalSessions ?? 0} total\n`);
+				if (ag.clientId) print.line(`  Client: ${ag.clientId}\n`);
+				print.line("\n");
 				return;
 			}
-			process.stderr.write(`\n  Hub: ${serverUrl}\n\n`);
-			process.stderr.write(`  Clients: ${data.clients} connected\n`);
-			process.stderr.write(`  Agents: ${data.running} running / ${data.total} total\n`);
-			process.stderr.write(`  Errors: ${data.byState.error} | Blocked: ${data.byState.blocked} | Working: ${data.byState.working} | Idle: ${data.byState.idle}\n\n`);
+			print.line(`\n  Hub: ${serverUrl}\n\n`);
+			print.line(`  Clients: ${data.clients} connected\n`);
+			print.line(`  Agents: ${data.running} running / ${data.total} total\n`);
+			print.line(`  Errors: ${data.byState.error} | Blocked: ${data.byState.blocked} | Working: ${data.byState.working} | Idle: ${data.byState.idle}\n\n`);
 			if (data.agents.length > 0) {
 				const header = `  ${"AGENT".padEnd(18)} ${"RUNTIME".padEnd(14)} ${"STATE".padEnd(10)} SESSIONS`;
-				process.stderr.write(`${header}\n`);
-				process.stderr.write(`  ${"─".repeat(header.length - 2)}\n`);
+				print.line(`${header}\n`);
+				print.line(`  ${"─".repeat(header.length - 2)}\n`);
 				for (const a of data.agents) {
 					const sessions = a.activeSessions !== null ? `${a.activeSessions}/${a.totalSessions ?? 0}` : "—";
-					process.stderr.write(`  ${(a.agentId ?? "").padEnd(18)} ${(a.runtimeType ?? "—").padEnd(14)} ${(a.runtimeState ?? "—").padEnd(10)} ${sessions}\n`);
+					print.line(`  ${(a.agentId ?? "").padEnd(18)} ${(a.runtimeType ?? "—").padEnd(14)} ${(a.runtimeState ?? "—").padEnd(10)} ${sessions}\n`);
 				}
-				process.stderr.write("\n");
+				print.line("\n");
 			}
 		} catch (error) {
 			fail("STATUS_ERROR", error instanceof Error ? error.message : String(error));
@@ -598,7 +591,7 @@ function registerAgentCommands(program) {
 				signal: AbortSignal.timeout(1e4)
 			});
 			if (!response.ok) fail("RESET_ERROR", `Server returned ${response.status}`, 1);
-			process.stderr.write(`  Agent "${name}" reset to idle.\n`);
+			print.line(`  Agent "${name}" reset to idle.\n`);
 		} catch (error) {
 			fail("RESET_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -616,18 +609,18 @@ function registerAgentCommands(program) {
 			if (!response.ok) fail("FETCH_ERROR", `Server returned ${response.status}`, 1);
 			const sessions = await response.json();
 			if (sessions.length === 0) {
-				process.stderr.write(`\n  No sessions for "${agentName}".\n\n`);
+				print.line(`\n  No sessions for "${agentName}".\n\n`);
 				return;
 			}
-			process.stderr.write(`\n  Sessions for "${agentName}":\n\n`);
+			print.line(`\n  Sessions for "${agentName}":\n\n`);
 			const header = `  ${"CHAT".padEnd(40)} ${"STATE".padEnd(12)} ${"RUNTIME".padEnd(10)} LAST ACTIVITY`;
-			process.stderr.write(`${header}\n`);
-			process.stderr.write(`  ${"─".repeat(header.length - 2)}\n`);
+			print.line(`${header}\n`);
+			print.line(`  ${"─".repeat(header.length - 2)}\n`);
 			for (const s of sessions) {
 				const chatShort = s.chatId.length > 38 ? `${s.chatId.slice(0, 35)}...` : s.chatId;
-				process.stderr.write(`  ${chatShort.padEnd(40)} ${s.state.padEnd(12)} ${(s.runtimeState ?? "—").padEnd(10)} ${s.lastActivityAt}\n`);
+				print.line(`  ${chatShort.padEnd(40)} ${s.state.padEnd(12)} ${(s.runtimeState ?? "—").padEnd(10)} ${s.lastActivityAt}\n`);
 			}
-			process.stderr.write("\n");
+			print.line("\n");
 		} catch (error) {
 			fail("SESSIONS_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -647,7 +640,7 @@ function registerAgentCommands(program) {
 				const body = await response.text();
 				fail("SESSION_CMD_ERROR", `Server returned ${response.status}: ${body}`, 1);
 			}
-			process.stderr.write(`  Session ${cmd}: ${chatId} → sent\n`);
+			print.line(`  Session ${cmd}: ${chatId} → sent\n`);
 		} catch (error) {
 			fail("SESSION_CMD_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -671,9 +664,9 @@ function registerAgentCommands(program) {
 				fail("DM_ERROR", `Failed to create DM: ${dmRes.status} — ${body}`, 1);
 			}
 			const dm = await dmRes.json();
-			process.stderr.write(`\n  Chat with ${targetAgent.displayName ?? targetAgent.name ?? targetAgent.uuid}\n`);
-			process.stderr.write(`  Chat ID: ${dm.id}\n`);
-			process.stderr.write(`  Type a message and press Enter. Ctrl+C to exit.\n\n`);
+			print.line(`\n  Chat with ${targetAgent.displayName ?? targetAgent.name ?? targetAgent.uuid}\n`);
+			print.line(`  Chat ID: ${dm.id}\n`);
+			print.line(`  Type a message and press Enter. Ctrl+C to exit.\n\n`);
 			const rl = (await import("node:readline")).createInterface({
 				input: process.stdin,
 				output: process.stderr,
@@ -694,7 +687,7 @@ function registerAgentCommands(program) {
 					for (const msg of newMessages) {
 						const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
 						const preview = content.length > 500 ? `${content.slice(0, 500)}...` : content;
-						process.stderr.write(`\r  [${targetAgent.displayName ?? targetAgent.name ?? "agent"}] ${preview}\n`);
+						print.line(`\r  [${targetAgent.displayName ?? targetAgent.name ?? "agent"}] ${preview}\n`);
 					}
 					if (msgData.items.length > 0 && msgData.items[0]) {
 						const newest = msgData.items[0].createdAt;
@@ -725,16 +718,16 @@ function registerAgentCommands(program) {
 					});
 					if (!sendRes.ok) {
 						const body = await sendRes.text();
-						process.stderr.write(`  [error] Failed to send: ${sendRes.status} — ${body}\n`);
+						print.line(`  [error] Failed to send: ${sendRes.status} — ${body}\n`);
 					} else lastSeenAt = (await sendRes.json()).createdAt;
 				} catch (err) {
-					process.stderr.write(`  [error] ${err instanceof Error ? err.message : String(err)}\n`);
+					print.line(`  [error] ${err instanceof Error ? err.message : String(err)}\n`);
 				}
 				rl.prompt();
 			});
 			rl.on("close", () => {
 				clearInterval(pollTimer);
-				process.stderr.write("\n  Chat ended.\n");
+				print.line("\n  Chat ended.\n");
 				process.exit(0);
 			});
 		} catch (error) {
@@ -812,14 +805,14 @@ async function promptReplaceOrCancel(newMemberId, newServerUrl) {
 	const existingOrg = typeof existingPayload?.organizationId === "string" ? existingPayload.organizationId : null;
 	const serviceStatus = getClientServiceStatus();
 	const serviceLine = serviceStatus.state === "active" ? `running (${serviceStatus.detail ?? "live"})` : serviceStatus.state === "inactive" ? `installed but not running${serviceStatus.detail ? ` — ${serviceStatus.detail}` : ""}` : "not installed";
-	process.stderr.write("\n");
-	process.stderr.write("  ⚠️  This computer is already connected to the Hub under another account.\n\n");
-	process.stderr.write(`       Existing account:  ${existingMember}\n`);
-	if (existingOrg) process.stderr.write(`       Organization:      ${existingOrg.slice(0, 8)}\n`);
-	process.stderr.write(`       Server:            ${existing.serverUrl}\n`);
-	process.stderr.write(`       Background service: ${serviceLine}\n\n`);
-	process.stderr.write("     Replacing only affects THIS computer. Your agents, messages, and\n");
-	process.stderr.write("     settings on the Hub itself are untouched.\n\n");
+	print.line("\n");
+	print.line("  ⚠️  This computer is already connected to the Hub under another account.\n\n");
+	print.line(`       Existing account:  ${existingMember}\n`);
+	if (existingOrg) print.line(`       Organization:      ${existingOrg.slice(0, 8)}\n`);
+	print.line(`       Server:            ${existing.serverUrl}\n`);
+	print.line(`       Background service: ${serviceLine}\n\n`);
+	print.line("     Replacing only affects THIS computer. Your agents, messages, and\n");
+	print.line("     settings on the Hub itself are untouched.\n\n");
 	if (await select({
 		message: "How would you like to continue?",
 		choices: [{
@@ -836,15 +829,15 @@ async function promptReplaceOrCancel(newMemberId, newServerUrl) {
 	return "proceed";
 }
 function printIsolationGuide(newServerUrl) {
-	process.stderr.write("\n  Cancelled. The existing account on this computer is untouched.\n\n");
-	process.stderr.write("  To run this new account alongside it (advanced — no background service):\n\n");
-	process.stderr.write("    export FIRST_TREE_HUB_HOME=\"$HOME/.first-tree/hub-<label>\"\n");
-	process.stderr.write(`    first-tree-hub client connect ${newServerUrl} --token <token>\n`);
-	process.stderr.write("    first-tree-hub client start\n\n");
-	process.stderr.write("  Notes:\n");
-	process.stderr.write("    - Run the commands in a FRESH terminal (the isolated home must be set first).\n");
-	process.stderr.write("    - In isolated mode the client stays online only while that terminal runs.\n");
-	process.stderr.write("    - The main account's background service is not affected.\n\n");
+	print.line("\n  Cancelled. The existing account on this computer is untouched.\n\n");
+	print.line("  To run this new account alongside it (advanced — no background service):\n\n");
+	print.line("    export FIRST_TREE_HUB_HOME=\"$HOME/.first-tree/hub-<label>\"\n");
+	print.line(`    first-tree-hub client connect ${newServerUrl} --token <token>\n`);
+	print.line("    first-tree-hub client start\n\n");
+	print.line("  Notes:\n");
+	print.line("    - Run the commands in a FRESH terminal (the isolated home must be set first).\n");
+	print.line("    - In isolated mode the client stays online only while that terminal runs.\n");
+	print.line("    - The main account's background service is not affected.\n\n");
 }
 /**
 * Authenticate via connect token — exchange for full JWT credentials.
@@ -863,7 +856,7 @@ async function authenticateWithToken(url, token) {
 * Authenticate via interactive username/password login.
 */
 async function authenticateInteractive(url) {
-	process.stderr.write("\n  Log in to Hub:\n");
+	print.line("\n  Log in to Hub:\n");
 	const username = await input({ message: "  Username:" });
 	const pw = await password({ message: "  Password:" });
 	const loginRes = await fetch(`${url}/api/v1/auth/login`, {
@@ -900,30 +893,30 @@ function registerConnectCommand(parent) {
 				}
 			}
 			setConfigValue(join(DEFAULT_CONFIG_DIR, "client.yaml"), "server.url", url);
-			process.stderr.write(`\n  \u2713 Server configured: ${url}\n`);
+			print.line(`\n  \u2713 Server configured: ${url}\n`);
 			saveCredentials({
 				...tokens,
 				serverUrl: url
 			});
-			process.stderr.write("  ✓ Authenticated\n");
+			print.line("  ✓ Authenticated\n");
 			resetConfig();
 			resetConfigMeta();
 			const config = await initConfig({
 				schema: clientConfigSchema,
 				role: "client"
 			});
-			process.stderr.write(`  \u2713 Connected as this computer (id: ${config.client.id})\n`);
+			print.line(`  \u2713 Connected as this computer (id: ${config.client.id})\n`);
 			if (options.service !== false && isServiceSupported()) {
 				const info = installClientService();
-				process.stderr.write(`  \u2713 Installed as a background service (${info.platform}) — you can close this terminal\n\n`);
-				process.stderr.write(`    Unit:  ${info.unitPath}\n`);
-				process.stderr.write(`    Logs:  ${info.logDir}\n`);
-				if (info.state === "active" && info.detail) process.stderr.write(`    State: running (${info.detail})\n`);
-				process.stderr.write("\n");
+				print.line(`  \u2713 Installed as a background service (${info.platform}) — you can close this terminal\n\n`);
+				print.line(`    Unit:  ${info.unitPath}\n`);
+				print.line(`    Logs:  ${info.logDir}\n`);
+				if (info.state === "active" && info.detail) print.line(`    State: running (${info.detail})\n`);
+				print.line("\n");
 				return;
 			}
-			if (options.service === false) process.stderr.write("  (--no-service) running inline — Ctrl+C to stop\n");
-			else process.stderr.write(`  Background service not supported on ${process.platform}; running inline.\n`);
+			if (options.service === false) print.line("  (--no-service) running inline — Ctrl+C to stop\n");
+			else print.line(`  Background service not supported on ${process.platform}; running inline.\n`);
 			const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
 			const agents = loadAgents({
 				schema: agentConfigSchema,
@@ -941,7 +934,7 @@ function registerConnectCommand(parent) {
 			await runtime.start();
 			runtime.watchAgentsDir(agentsDir);
 			const shutdown = async () => {
-				process.stderr.write("\n  Shutting down...\n");
+				print.line("\n  Shutting down...\n");
 				runtime.unwatchAgentsDir();
 				await runtime.stop();
 				process.exit(0);
@@ -951,11 +944,11 @@ function registerConnectCommand(parent) {
 			await new Promise(() => {});
 		} catch (error) {
 			if (error.name === "ExitPromptError") {
-				process.stderr.write("\n  Cancelled.\n");
+				print.line("\n  Cancelled.\n");
 				return;
 			}
 			const msg = error instanceof Error ? error.message : String(error);
-			process.stderr.write(`  Error: ${msg}\n`);
+			print.line(`  Error: ${msg}\n`);
 			process.exit(1);
 		} finally {
 			resetConfig();
@@ -980,12 +973,13 @@ function registerClientCommands(program) {
 				role: "client"
 			});
 			applyClientLoggerConfig({ level: config.logLevel });
+			if (process.env.FIRST_TREE_HUB_SERVICE_MODE === "1") configureClientLoggerForService(join(DEFAULT_HOME_DIR, "logs"));
 			const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
 			const agents = loadAgents({
 				schema: agentConfigSchema,
 				agentsDir
 			});
-			process.stderr.write(`\n  Connecting to ${config.server.url} (client id: ${config.client.id})...\n`);
+			print.line(`\n  Connecting to ${config.server.url} (client id: ${config.client.id})...\n`);
 			const managed = options.interactive === false;
 			const runtime = new ClientRuntime(config.server.url, config.client.id, {
 				currentVersion: COMMAND_VERSION,
@@ -999,7 +993,7 @@ function registerClientCommands(program) {
 			await runtime.start();
 			runtime.watchAgentsDir(agentsDir);
 			const shutdown = async () => {
-				process.stderr.write("\n  Shutting down...\n");
+				print.line("\n  Shutting down...\n");
 				runtime.unwatchAgentsDir();
 				await runtime.stop();
 				process.exit(0);
@@ -1009,7 +1003,7 @@ function registerClientCommands(program) {
 			await new Promise(() => {});
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
-			process.stderr.write(`  Error: ${msg}\n`);
+			print.line(`  Error: ${msg}\n`);
 			process.exit(1);
 		} finally {
 			resetConfig();
@@ -1017,7 +1011,7 @@ function registerClientCommands(program) {
 		}
 	});
 	client.command("doctor").description("Check client environment readiness").action(async () => {
-		process.stderr.write("\n  First Tree Hub Client Doctor\n\n");
+		print.line("\n  First Tree Hub Client Doctor\n\n");
 		printResults([
 			checkNodeVersion(),
 			checkClientConfig(),
@@ -1027,8 +1021,8 @@ function registerClientCommands(program) {
 		]);
 	});
 	client.command("stop").description("Stop the client (sends SIGTERM to running process)").action(() => {
-		process.stderr.write("  Client stop: use Ctrl+C or `kill` the running process.\n");
-		process.stderr.write("  Daemon mode with PID file is planned for a future release.\n");
+		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("status").description("Show client and agent connection status").action(() => {
 		const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
@@ -1038,31 +1032,31 @@ function registerClientCommands(program) {
 				agentsDir
 			});
 			if (agents.size === 0) {
-				process.stderr.write("  No agents configured.\n");
+				print.line("  No agents configured.\n");
 				return;
 			}
-			process.stderr.write("\n  Configured agents:\n\n");
-			for (const [name, config] of agents) process.stderr.write(`  ${name.padEnd(20)} runtime: ${config.runtime.padEnd(14)} agentId: ${config.agentId}\n`);
-			process.stderr.write("\n");
+			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("\n");
 		} catch {
-			process.stderr.write("  No agents directory found.\n");
+			print.line("  No agents directory found.\n");
 		}
 	});
 	const service = client.command("service").description("Install/uninstall the background service that keeps this computer online");
 	service.command("install").description("Install as a background service — auto-starts on login/boot").action(() => {
 		if (!isServiceSupported()) {
-			process.stderr.write(`  Background service is not supported on ${process.platform}.\n  Run \`first-tree-hub client start\` manually to keep the computer online.
+			print.line(`  Background service is not supported on ${process.platform}.\n  Run \`first-tree-hub client start\` manually to keep the computer online.
 `);
 			process.exit(1);
 		}
 		try {
 			const info = installClientService();
-			process.stderr.write(`\n  \u2713 Installed as a background service (${info.platform}).\n`);
-			process.stderr.write(`    Unit:  ${info.unitPath}\n`);
-			process.stderr.write(`    Logs:  ${info.logDir}\n`);
-			if (info.state === "active") process.stderr.write(`    State: running${info.detail ? ` (${info.detail})` : ""}\n`);
-			else process.stderr.write(`    State: ${info.state}${info.detail ? ` (${info.detail})` : ""}\n`);
-			process.stderr.write("\n  You can close this terminal — the computer stays online.\n");
+			print.line(`\n  \u2713 Installed as a background service (${info.platform}).\n`);
+			print.line(`    Unit:  ${info.unitPath}\n`);
+			print.line(`    Logs:  ${info.logDir}\n`);
+			if (info.state === "active") print.line(`    State: running${info.detail ? ` (${info.detail})` : ""}\n`);
+			else print.line(`    State: ${info.state}${info.detail ? ` (${info.detail})` : ""}\n`);
+			print.line("\n  You can close this terminal — the computer stays online.\n");
 		} catch (error) {
 			fail("SERVICE_INSTALL_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -1070,26 +1064,40 @@ function registerClientCommands(program) {
 	service.command("status").description("Show background service state").action(() => {
 		const info = getClientServiceStatus();
 		if (info.platform === "unsupported") {
-			process.stderr.write(`  Not supported on ${process.platform}.\n`);
+			print.line(`  Not supported on ${process.platform}.\n`);
 			return;
 		}
-		process.stderr.write(`\n  ${info.platform}: ${info.label}\n`);
-		process.stderr.write(`  Unit:  ${info.unitPath}\n`);
-		process.stderr.write(`  Logs:  ${info.logDir}\n`);
-		process.stderr.write(`  State: ${info.state}${info.detail ? ` (${info.detail})` : ""}\n\n`);
+		print.line(`\n  ${info.platform}: ${info.label}\n`);
+		print.line(`  Unit:  ${info.unitPath}\n`);
+		print.line(`  Logs:  ${info.logDir}\n`);
+		print.line(`  State: ${info.state}${info.detail ? ` (${info.detail})` : ""}\n\n`);
 	});
 	service.command("uninstall").description("Stop and remove the background service").action(() => {
 		if (!isServiceSupported()) {
-			process.stderr.write(`  Not supported on ${process.platform}.\n`);
+			print.line(`  Not supported on ${process.platform}.\n`);
 			return;
 		}
 		try {
 			const info = uninstallClientService();
-			process.stderr.write(`\n  \u2713 Uninstalled background service (${info.platform}).\n\n`);
+			print.line(`\n  \u2713 Uninstalled background service (${info.platform}).\n\n`);
 		} catch (error) {
 			fail("SERVICE_UNINSTALL_ERROR", error instanceof Error ? error.message : String(error));
 		}
 	});
+	service.command("logs").description("Read background-service logs (pretty by default)").option("-f, --tail", "follow new lines as they arrive (Ctrl+C to stop)", false).option("--since <duration>", "only show records newer than duration (e.g. 10s, 5m, 2h, 1d)").option("--level <level>", "minimum level (trace|debug|info|warn|error|fatal)").option("--json", "emit raw NDJSON lines instead of pretty formatting", false).action(async (options) => {
+		try {
+			const level = validateLevel(options.level);
+			const sinceMs = options.since ? parseDuration(options.since) : void 0;
+			await showServiceLogs({
+				tail: options.tail === true,
+				level,
+				sinceMs,
+				json: options.json === true
+			});
+		} catch (error) {
+			fail("SERVICE_LOGS_ERROR", error instanceof Error ? error.message : String(error));
+		}
+	});
 	client.command("hub-list").description("List clients on the Hub server").option("--server <url>", "Hub server URL").action(async (options) => {
 		try {
 			const serverUrl = resolveServerUrl(options.server);
@@ -1101,18 +1109,18 @@ function registerClientCommands(program) {
 			if (!response.ok) fail("FETCH_ERROR", `Server returned ${response.status}`, 1);
 			const clients = await response.json();
 			if (clients.length === 0) {
-				process.stderr.write("  No clients.\n");
+				print.line("  No clients.\n");
 				return;
 			}
-			process.stderr.write(`\n  Clients: ${clients.length}\n\n`);
+			print.line(`\n  Clients: ${clients.length}\n\n`);
 			const header = `  ${"CLIENT".padEnd(20)} ${"HOST".padEnd(25)} ${"AGENTS".padEnd(8)} CONNECTED`;
-			process.stderr.write(`${header}\n`);
-			process.stderr.write(`  ${"─".repeat(header.length - 2)}\n`);
+			print.line(`${header}\n`);
+			print.line(`  ${"─".repeat(header.length - 2)}\n`);
 			for (const c of clients) {
 				const since = c.connectedAt ? timeSince(c.connectedAt) : "—";
-				process.stderr.write(`  ${c.id.padEnd(20)} ${(c.hostname ?? "—").padEnd(25)} ${String(c.agentCount).padEnd(8)} ${since}\n`);
+				print.line(`  ${c.id.padEnd(20)} ${(c.hostname ?? "—").padEnd(25)} ${String(c.agentCount).padEnd(8)} ${since}\n`);
 			}
-			process.stderr.write("\n");
+			print.line("\n");
 		} catch (error) {
 			fail("CLIENT_LIST_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -1127,7 +1135,7 @@ function registerClientCommands(program) {
 				signal: AbortSignal.timeout(1e4)
 			});
 			if (!response.ok) fail("DISCONNECT_ERROR", `Server returned ${response.status}`, 1);
-			process.stderr.write(`  Client "${clientId}" disconnected.\n`);
+			print.line(`  Client "${clientId}" disconnected.\n`);
 		} catch (error) {
 			fail("DISCONNECT_ERROR", error instanceof Error ? error.message : String(error));
 		}
@@ -1170,10 +1178,10 @@ function registerConfigCommands(program) {
 				schema: flags.client ? clientConfigSchema : serverConfigSchema,
 				role: flags.client ? "client" : "server"
 			});
-			process.stderr.write("\n  Configuration saved.\n");
+			print.line("\n  Configuration saved.\n");
 		} catch (error) {
 			if (error.name === "ExitPromptError") {
-				process.stderr.write("\n  Cancelled.\n");
+				print.line("\n  Cancelled.\n");
 				return;
 			}
 			throw error;
@@ -1186,27 +1194,27 @@ function registerConfigCommands(program) {
 		else if (value === "false") parsed = false;
 		else if (/^\d+$/.test(value)) parsed = Number(value);
 		setConfigValue(path, key, parsed);
-		process.stderr.write(`  Set ${key} in ${path}\n`);
+		print.line(`  Set ${key} in ${path}\n`);
 	});
 	addScopeOptions(config.command("get").description("Get a config value")).argument("<key>", "Config key (dot notation)").option("--show-secrets", "Show secret values in plaintext").action((key, flags) => {
 		const { path, schema } = resolveConfigPath(flags);
 		const value = getConfigValue(path, key);
-		if (value === void 0) process.stderr.write(`  ${key}: (not set)\n`);
+		if (value === void 0) print.line(`  ${key}: (not set)\n`);
 		else {
 			const display = isSecretField(schema, key) && !flags.showSecrets ? "***" : String(value);
-			process.stderr.write(`  ${key}: ${display}\n`);
+			print.line(`  ${key}: ${display}\n`);
 		}
 	});
 	addScopeOptions(config.command("list").description("List all config values")).option("--show-secrets", "Show secret values in plaintext").action((flags) => {
 		const { path, schema } = resolveConfigPath(flags);
 		const values = readConfigFile(path);
 		if (Object.keys(values).length === 0) {
-			process.stderr.write(`  No config found at ${path}\n`);
+			print.line(`  No config found at ${path}\n`);
 			return;
 		}
-		process.stderr.write(`\n  Config: ${path}\n\n`);
+		print.line(`\n  Config: ${path}\n\n`);
 		printFlat(values, schema, "", flags.showSecrets ?? false);
-		process.stderr.write("\n");
+		print.line("\n");
 	});
 }
 function printFlat(obj, schema, prefix, showSecrets) {
@@ -1215,7 +1223,7 @@ function printFlat(obj, schema, prefix, showSecrets) {
 		if (typeof value === "object" && value !== null && !Array.isArray(value)) printFlat(value, schema, fullKey, showSecrets);
 		else {
 			const display = isSecretField(schema, fullKey) && !showSecrets ? "***" : String(value);
-			process.stderr.write(`  ${fullKey.padEnd(30)} ${display}\n`);
+			print.line(`  ${fullKey.padEnd(30)} ${display}\n`);
 		}
 	}
 }
@@ -1240,13 +1248,13 @@ function isSecretField(schema, dotPath) {
 //#region src/commands/onboard.ts
 async function promptMissing(args) {
 	if (!args.server) try {
-		const { resolveServerUrl } = await import("../bootstrap-CWcBzk6C.mjs").then((n) => n.t);
+		const { resolveServerUrl } = await import("../bootstrap-DWifXj9b.mjs").then((n) => n.t);
 		resolveServerUrl();
 	} catch {
 		args.server = await input({ message: "Hub server URL:" });
 		saveOnboardState(args);
 	}
-	const { loadCredentials } = await import("../bootstrap-CWcBzk6C.mjs").then((n) => n.t);
+	const { loadCredentials } = await import("../bootstrap-DWifXj9b.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:" });
@@ -1345,7 +1353,7 @@ function registerOnboardCommand(program) {
 			if (args.check) {
 				const items = await onboardCheck(args);
 				const report = formatCheckReport(items);
-				process.stderr.write(`\nOnboard Check: ${args.id ?? "(no id)"}\n\n${report}\n\n`);
+				print.line(`\nOnboard Check: ${args.id ?? "(no id)"}\n\n${report}\n\n`);
 				if (items.some((i) => i.status === "missing_required" || i.status === "error")) process.exit(1);
 				return;
 			}
@@ -1353,14 +1361,14 @@ function registerOnboardCommand(program) {
 			const items = await onboardCheck(args);
 			if (items.some((i) => i.status === "missing_required" || i.status === "error")) {
 				const report = formatCheckReport(items);
-				process.stderr.write(`\nOnboard Check: ${args.id ?? "(no id)"}\n\n${report}\n\n`);
+				print.line(`\nOnboard Check: ${args.id ?? "(no id)"}\n\n${report}\n\n`);
 				fail("MISSING_PARAMS", "Required parameters are missing. See checklist above.");
 			}
 			await onboardCreate(args);
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
 			if (isInteractive()) {
-				process.stderr.write(`\n\u274C ${msg}\n\n`);
+				print.line(`\n\u274C ${msg}\n\n`);
 				process.exit(1);
 			}
 			fail("ONBOARD_ERROR", msg);
@@ -1379,22 +1387,22 @@ function registerServerCommands(program) {
 			});
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
-			process.stderr.write(`\n  Error: ${msg}\n\n`);
+			print.line(`\n  Error: ${msg}\n\n`);
 			process.exit(1);
 		}
 	});
 	server.command("stop").description("Stop the managed PostgreSQL container").action(() => {
 		try {
-			if (stopPostgres()) process.stderr.write("  PostgreSQL container stopped.\n");
-			else process.stderr.write("  No managed PostgreSQL container found.\n");
+			if (stopPostgres()) print.line("  PostgreSQL container stopped.\n");
+			else print.line("  No managed PostgreSQL container found.\n");
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
-			process.stderr.write(`  Error stopping PostgreSQL: ${msg}\n`);
+			print.line(`  Error stopping PostgreSQL: ${msg}\n`);
 			process.exit(1);
 		}
 	});
 	server.command("doctor").description("Check server environment readiness").action(async () => {
-		process.stderr.write("\n  First Tree Hub Server Doctor\n\n");
+		print.line("\n  First Tree Hub Server Doctor\n\n");
 		printResults([
 			checkNodeVersion(),
 			checkDocker(),
@@ -1409,13 +1417,13 @@ function registerServerCommands(program) {
 			const res = await fetch(`${url}/api/v1/health`);
 			if (res.ok) {
 				const data = await res.json();
-				console.log(JSON.stringify(data, null, 2));
+				process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
 			} else {
-				process.stderr.write(`  Server returned ${res.status}\n`);
+				print.line(`  Server returned ${res.status}\n`);
 				process.exit(1);
 			}
 		} catch {
-			process.stderr.write(`  Cannot connect to ${url}\n`);
+			print.line(`  Cannot connect to ${url}\n`);
 			process.exit(1);
 		}
 	});
@@ -1425,10 +1433,10 @@ function registerServerCommands(program) {
 				schema: serverConfigSchema,
 				role: "server"
 			})).database.url);
-			process.stderr.write(`  Migrations complete (${tableCount} tables)\n`);
+			print.line(`  Migrations complete (${tableCount} tables)\n`);
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
-			process.stderr.write(`  Error: ${msg}\n`);
+			print.line(`  Error: ${msg}\n`);
 			process.exit(1);
 		}
 	});
@@ -1438,11 +1446,11 @@ function registerServerCommands(program) {
 				schema: serverConfigSchema,
 				role: "server"
 			})).database.url, options.username, options.org, options.name, options.password);
-			process.stderr.write(`  Admin user "${result.username}" created.\n`);
-			if (!options.password) process.stderr.write(`  Password: ${result.password}  (save this — shown only once)\n`);
+			print.line(`  Admin user "${result.username}" created.\n`);
+			if (!options.password) print.line(`  Password: ${result.password}  (save this — shown only once)\n`);
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
-			process.stderr.write(`  Error: ${msg}\n`);
+			print.line(`  Error: ${msg}\n`);
 			process.exit(1);
 		}
 	});
@@ -1451,7 +1459,7 @@ function registerServerCommands(program) {
 //#region src/commands/status.ts
 function registerStatusCommand(program) {
 	program.command("status").description("Global overview — server health + configured agents").action(async () => {
-		process.stderr.write("\n");
+		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}`;
@@ -1460,31 +1468,31 @@ function registerStatusCommand(program) {
 			if (res.ok) {
 				const data = await res.json();
 				const uptime = data.uptime_seconds ? formatUptime(data.uptime_seconds) : "unknown";
-				process.stderr.write(`  Server:     ✓ running (${serverUrl}, uptime: ${uptime})\n`);
-			} else process.stderr.write(`  Server:     ✗ unhealthy (${res.status})\n`);
+				print.line(`  Server:     ✓ running (${serverUrl}, uptime: ${uptime})\n`);
+			} else print.line(`  Server:     ✗ unhealthy (${res.status})\n`);
 		} catch {
-			process.stderr.write(`  Server:     ✗ not running (${serverUrl})\n`);
+			print.line(`  Server:     ✗ not running (${serverUrl})\n`);
 		}
 		const dbProvider = getNestedValue(serverConfig, "database.provider") ?? "unknown";
 		const hasDbUrl = getNestedValue(serverConfig, "database.url") !== void 0;
-		process.stderr.write(`  Database:   ${hasDbUrl ? "✓ configured" : "✗ not configured"} (${dbProvider})\n`);
+		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
 			});
-			process.stderr.write(`  Agents:     ${agents.size} configured\n`);
+			print.line(`  Agents:     ${agents.size} configured\n`);
 		} catch {
-			process.stderr.write("  Agents:     error reading config\n");
+			print.line("  Agents:     error reading config\n");
 		}
-		else process.stderr.write("  Agents:     0 configured\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");
-			process.stderr.write(`  Client:     configured → ${clientServerUrl}\n`);
-		} else process.stderr.write("  Client:     not configured\n");
-		process.stderr.write("\n");
+			print.line(`  Client:     configured → ${clientServerUrl}\n`);
+		} else print.line("  Client:     not configured\n");
+		print.line("\n");
 	});
 }
 function getNestedValue(obj, dotPath) {
@@ -1508,7 +1516,21 @@ function formatUptime(seconds) {
 //#region src/cli/index.ts
 runHomeMigration();
 const program = new Command();
-program.name("first-tree-hub").description("First Tree Hub — centralized collaboration platform for agent teams").version(COMMAND_VERSION);
+program.name("first-tree-hub").description("First Tree Hub — centralized collaboration platform for agent teams").version(COMMAND_VERSION).option("--json", "emit only machine-readable JSON on stdout; silence human status lines on stderr").option("--verbose", "raise log level to debug (overrides FIRST_TREE_HUB_LOG_LEVEL)").hook("preAction", (thisCommand) => {
+	const opts = thisCommand.optsWithGlobals();
+	const json = opts.json === true || process.env.FIRST_TREE_HUB_JSON === "1";
+	setJsonMode(json);
+	if (opts.verbose) applyClientLoggerConfig({
+		level: "debug",
+		explicit: true
+	});
+	else if (process.env.FIRST_TREE_HUB_LOG_LEVEL) applyClientLoggerConfig({ explicit: true });
+	else if (json) applyClientLoggerConfig({
+		level: "error",
+		explicit: true
+	});
+	else applyClientLoggerConfig({ level: "warn" });
+});
 registerServerCommands(program);
 registerClientCommands(program);
 registerAgentCommands(program);