@agent-team-foundation/first-tree-hub 0.12.10 → 0.14.0

package/dist/{saas-connect-Fgnnnola.mjs → saas-connect-DX3-nDs9.mjs}

@@ -1,12 +1,12 @@
 import { a as __toCommonJS, o as __toESM, t as __commonJSMin } from "./chunk-BSw8zbkd.mjs";
 import { A as FIRST_TREE_HUB_ATTR, C as stampOrgScope, D as untrustedAttrs, E as startWsConnectionSpan, M as require_pino, O as withSpan, S as stampChatResource, _ as rootLogger$1, a as buildRateLimitError, c as currentTraceId, g as reportErrorToRoot, i as bodyCaptureOnSendHook, j as redactUrl, k as withWsMessageSpan, l as decodeJwtForTrace, m as observabilityPlugin, n as applyLoggerConfig, o as classifyJoseError, r as attachRequestContext, s as createLogger$1, t as adapterAttrs, u as endWsConnectionSpan, x as stampAgentResource, y as setWsConnectionAttrs } from "./observability-BAScT_5S-BcW9HgkG.mjs";
-import { C as resetConfigMeta, E as setConfigValue, S as resetConfig, T as serverConfigSchema, b as migrateLegacyHome, c as resolveServerUrl, d as DEFAULT_CONFIG_DIR, f as DEFAULT_DATA_DIR$1, g as collectMissingPrompts, h as clientConfigSchema, i as ensureFreshAccessToken, l as saveAgentConfig, m as agentConfigSchema, o as loadCredentials, p as DEFAULT_HOME_DIR$1, u as saveCredentials, v as initConfig, w as resolveConfigReadonly, y as loadAgents } from "./bootstrap-CW73oEYn.mjs";
+import { C as resetConfigMeta, E as setConfigValue, S as resetConfig, T as serverConfigSchema, b as migrateLegacyHome, c as resolveServerUrl, d as DEFAULT_CONFIG_DIR, f as DEFAULT_DATA_DIR$1, g as collectMissingPrompts, h as clientConfigSchema, i as ensureFreshAccessToken, l as saveAgentConfig, m as agentConfigSchema, o as loadCredentials, p as DEFAULT_HOME_DIR$1, u as saveCredentials, v as initConfig, w as resolveConfigReadonly, y as loadAgents } from "./bootstrap-C15ZBOCC.mjs";
 import { a as print, i as blank, n as CLI_USER_AGENT, r as COMMAND_VERSION, s as status, t as cliFetch } from "./cli-fetch--tiwKm5S.mjs";
-import { $ as onboardingEventSchema, A as createOrgFromMeSchema, B as githubStartQuerySchema, C as contextTreeSnapshotSchema, Ct as updateClientCapabilitiesSchema, D as createChatSchema, E as createAgentSchema, Et as wsAuthFrameSchema, G as isOrgSettingNamespace, H as inboxAckFrameSchema, I as githubAppInstallationClaimBodySchema, J as joinByInvitationSchema, K as isRedactedEnvValue, L as githubAppInstallationPermissionsSchema$1, M as defaultRuntimeConfigPayload, N as delegateFeishuUserSchema, O as createMeChatSchema, P as dryRunAgentRuntimeConfigSchema, Q as notificationQuerySchema, R as githubCallbackQuerySchema, S as connectTokenExchangeSchema, St as updateChatSchema, T as createAdapterMappingSchema, Tt as updateOrganizationSchema, U as inboxDeliverFrameSchema$1, V as imageInlineContentSchema, W as inboxPollQuerySchema, X as loginSchema, Y as listMeChatsQuerySchema, Z as messageSourceSchema$1, _ as agentRuntimeConfigPayloadSchema$1, _t as stripCode, a as AGENT_TYPES, at as rebindAgentSchema, bt as updateAgentRuntimeConfigSchema, ct as safeRedirectPath, d as ORG_SETTINGS_NAMESPACES$1, dt as sendMessageSchema, et as paginationQuerySchema, f as WS_AUTH_FRAME_TIMEOUT_MS, ft as sendToAgentSchema, g as agentPinnedMessageSchema$1, gt as sessionStateMessageSchema, h as agentBindRequestSchema, ht as sessionReconcileRequestSchema, i as AGENT_STATUSES, k as createMemberSchema, l as MENTION_REGEX, m as addParticipantSchema, mt as sessionEventSchema$1, n as AGENT_NAME_REGEX$1, nt as patchOnboardingSchema, o as AGENT_VISIBILITY, ot as refreshTokenSchema, p as addMeChatParticipantsSchema, pt as sessionEventMessageSchema, q as isReservedAgentName$1, r as AGENT_SELECTOR_HEADER$1, s as CHAT_ENGAGEMENT_STATUSES, st as runtimeStateMessageSchema, t as AGENT_BIND_REJECT_REASONS, tt as patchChatEngagementSchema, u as NOTIFICATION_TYPES, ut as selfServiceFeishuBotSchema, v as agentTypeSchema$1, vt as submitQuestionAnswerSchema, w as createAdapterConfigSchema, wt as updateMemberSchema, x as clientRegisterSchema, xt as updateAgentSchema, y as chatMetadataSchema$1, yt as updateAdapterConfigSchema, z as githubDevCallbackQuerySchema } from "./dist-B1GHzMLc.mjs";
-import { a as ConflictError, c as UnauthorizedError, i as ClientUserMismatchError$1, l as organizations, n as BadRequestError, o as ForbiddenError, r as ClientOrgMismatchError$1, s as NotFoundError, t as AppError, u as users } from "./errors-CF5evtJt-B0NTIVPt.mjs";
+import { $ as listMeChatSourceCountsQuerySchema, A as createMeChatSchema, At as updateOrganizationSchema, B as githubAppInstallationClaimBodySchema, C as clientRegisterSchema, Ct as submitQuestionAnswerSchema, D as createAdapterMappingSchema, Dt as updateChatSchema, E as createAdapterConfigSchema, Et as updateAgentSchema, F as delegateFeishuUserSchema, G as imageInlineContentSchema, H as githubCallbackQuerySchema, I as dryRunAgentRuntimeConfigSchema, J as inboxPollQuerySchema, K as inboxAckFrameSchema, M as createOrgFromMeSchema, O as createAgentSchema, Ot as updateClientCapabilitiesSchema, P as defaultRuntimeConfigPayload, Q as joinByInvitationSchema, R as getMeDocResponseSchema, St as stripCode, T as contextTreeSnapshotSchema, Tt as updateAgentRuntimeConfigSchema, U as githubDevCallbackQuerySchema, V as githubAppInstallationPermissionsSchema$1, W as githubStartQuerySchema, X as isRedactedEnvValue, Y as isOrgSettingNamespace, Z as isReservedAgentName$1, _ as agentBindRequestSchema, _t as sendToAgentSchema, a as AGENT_TYPES, at as paginationQuerySchema, b as agentTypeSchema$1, bt as sessionReconcileRequestSchema, d as MENTION_REGEX, dt as refreshTokenSchema, et as listMeChatsQuerySchema, f as NOTIFICATION_TYPES, ft as runtimeStateMessageSchema, g as addParticipantSchema, gt as sendMessageSchema, h as addMeChatParticipantsSchema, ht as selfServiceFeishuBotSchema, i as AGENT_STATUSES, it as onboardingEventSchema, j as createMemberSchema, jt as wsAuthFrameSchema, k as createChatSchema, kt as updateMemberSchema, l as GITHUB_ENTITY_TYPES, m as WS_AUTH_FRAME_TIMEOUT_MS, n as AGENT_NAME_REGEX$1, nt as messageSourceSchema$1, o as AGENT_VISIBILITY, ot as patchChatEngagementSchema, p as ORG_SETTINGS_NAMESPACES$1, pt as safeRedirectPath, q as inboxDeliverFrameSchema$1, r as AGENT_SELECTOR_HEADER$1, rt as notificationQuerySchema, s as CHAT_ENGAGEMENT_STATUSES, st as patchOnboardingSchema, t as AGENT_BIND_REJECT_REASONS, tt as loginSchema, ut as rebindAgentSchema, v as agentPinnedMessageSchema$1, vt as sessionEventMessageSchema, w as connectTokenExchangeSchema, wt as updateAdapterConfigSchema, x as chatMetadataSchema$1, xt as sessionStateMessageSchema, y as agentRuntimeConfigPayloadSchema$1, yt as sessionEventSchema$1, z as getMeDocSchema } from "./dist-1XGLJMOq.mjs";
+import { a as ConflictError, c as UnauthorizedError, i as ClientUserMismatchError$1, l as organizations, n as BadRequestError, o as ForbiddenError, r as ClientOrgMismatchError$1, s as NotFoundError, t as AppError, u as users } from "./errors-LPcARA4K-Dbrptiyz.mjs";
 import { n as init_esm, r as trace, t as esm_exports } from "./esm-iadMkGbV.mjs";
-import { $ as notifyRecipients, A as getPresence, B as listAgentsManagedByUser, C as ensureParticipant, D as getChatDetail, E as getCachedAudience, F as joinAsParticipant, G as listClients, H as listChatParticipantsWithNames, I as joinChat, K as listClientsForOrgAdmin, L as leaveAsParticipant, M as heartbeatInstance, N as inboxEntries, O as getClient, P as invalidateChatAudience, Q as messages, R as leaveChat, S as ensureCanJoin, T as getActivityOverview, U as listChats, V as listAgentsWithRuntime, W as listChatsForMember, X as markSupersededByChat, Y as markStaleAgents, Z as members, _ as createChat, _t as unbindAgent, a as agentVisibilityCondition, at as registerClient, b as disconnectClient, c as assertParticipant, ct as resolveChatMembership, d as chatMembership, dt as sendToAgent$1, et as pendingQuestions, f as chats, ft as serverInstances, g as clients, gt as touchAgent, h as cleanupStalePresence, ht as submitAnswer, i as agentPresence, it as registerChatMessageDispatcher, j as heartbeatClient, k as getOnlineCount, l as bindAgent, lt as retireClient, m as cleanupStaleClients, mt as setRuntimeState, n as addParticipant, nt as recomputeWatchersForAgent, o as agents, ot as removeParticipant, p as claimClient, pt as setOffline, q as listMessages, r as agentChatSessions, rt as recomputeWatchersForMember, s as assertClientOwner, st as resetActivity, t as addChatParticipants, tt as recomputeChatWatchers, u as changeChatType, ut as sendMessage, v as createNotifier, vt as updateClientCapabilities, w as findOrCreateDirectChat, x as editMessage, y as deriveAuthState, yt as upsertSessionState, z as listActiveAgentsPinnedToClient } from "./client-BViGcaUC-CZb2Svgh.mjs";
-import { a as invitationRedemptions, c as recordRedemption, i as getActiveInvitation, l as rotateInvitation, n as ensureActiveInvitation, o as invitations, r as findActiveByToken, t as buildInviteUrl, u as uuidv7 } from "./invitation-Bg0TRiyx-BsZH4GCS.mjs";
+import { $ as notifyRecipients, A as getPresence, B as listAgentsManagedByUser, C as ensureParticipant, D as getChatDetail, E as getCachedAudience, F as joinAsParticipant, G as listClients, H as listChatParticipantsWithNames, I as joinChat, K as listClientsForOrgAdmin, L as leaveAsParticipant, M as heartbeatInstance, N as inboxEntries, O as getClient, P as invalidateChatAudience, Q as messages, R as leaveChat, S as ensureCanJoin, T as getActivityOverview, U as listChats, V as listAgentsWithRuntime, W as listChatsForMember, X as markSupersededByChat, Y as markStaleAgents, Z as members, _ as createChat, _t as unbindAgent, a as agentVisibilityCondition, at as registerClient, b as disconnectClient, c as assertParticipant, ct as resolveChatMembership, d as chatMembership, dt as sendToAgent$1, et as pendingQuestions, f as chats, ft as serverInstances, g as clients, gt as touchAgent, h as cleanupStalePresence, ht as submitAnswer, i as agentPresence, it as registerChatMessageDispatcher, j as heartbeatClient, k as getOnlineCount, l as bindAgent, lt as retireClient, m as cleanupStaleClients, mt as setRuntimeState, n as addParticipant, nt as recomputeWatchersForAgent, o as agents, ot as removeParticipant, p as claimClient, pt as setOffline, q as listMessages, r as agentChatSessions, rt as recomputeWatchersForMember, s as assertClientOwner, st as resetActivity, t as addChatParticipants, tt as recomputeChatWatchers, u as changeChatType, ut as sendMessage, v as createNotifier, vt as updateClientCapabilities, w as findOrCreateDirectChat, x as editMessage, y as deriveAuthState, yt as upsertSessionState, z as listActiveAgentsPinnedToClient } from "./client-RM_03B_l-DiEIa9xe.mjs";
+import { a as invitationRedemptions, c as recordRedemption, i as getActiveInvitation, l as rotateInvitation, n as ensureActiveInvitation, o as invitations, r as findActiveByToken, t as buildInviteUrl, u as uuidv7 } from "./invitation-DZO4NX3P-BPxTeHf-.mjs";
 import { createRequire } from "node:module";
 import { ZodError, z } from "zod";
 import { basename, delimiter, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
@@ -16,7 +16,7 @@ import { EventEmitter } from "node:events";
 import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import WebSocket from "ws";
-import { chmod, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, readdir, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { parse, stringify } from "yaml";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { execFile, execFileSync, execSync, spawn, spawnSync } from "node:child_process";
@@ -386,6 +386,7 @@ z.object({
 const PROMPT_APPEND_MAX_LENGTH = 32e3;
 const MCP_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
 const ENV_KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+const WINDOWS_DRIVE_PATH_PATTERN = /^[A-Za-z]:/;
 const promptConfigSchema = z.object({ append: z.string().max(PROMPT_APPEND_MAX_LENGTH).default("") });
 const mcpStdioServerSchema = z.object({
 	name: z.string().regex(MCP_NAME_PATTERN, "MCP name must match /^[a-z0-9][a-z0-9_-]{0,63}$/i"),
@@ -415,10 +416,38 @@ const envEntrySchema = z.object({
 	value: z.string(),
 	sensitive: z.boolean().default(false)
 });
+function hasControlCharacters(value) {
+	for (let idx = 0; idx < value.length; idx++) {
+		const code = value.charCodeAt(idx);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+function getRepoLocalPathSafetyError(localPath) {
+	if (localPath.length === 0) return "Git repo local path must not be empty";
+	if (localPath.trim() !== localPath) return "Git repo local path must not have leading or trailing whitespace";
+	if (hasControlCharacters(localPath)) return "Git repo local path must not contain control characters";
+	if (localPath.includes("\\")) return "Git repo local path must use forward slashes";
+	if (localPath.startsWith("/") || WINDOWS_DRIVE_PATH_PATTERN.test(localPath)) return "Git repo local path must be relative";
+	const segments = localPath.split("/");
+	for (const segment of segments) {
+		if (!segment) return "Git repo local path must not contain empty path segments";
+		if (segment === "." || segment === "..") return "Git repo local path must not contain dot segments";
+		if (segment.trim() !== segment) return "Git repo local path segments must not have leading or trailing whitespace";
+	}
+	return null;
+}
 const gitRepoSchema = z.object({
 	url: z.string().min(1),
 	ref: z.string().min(1).optional(),
-	localPath: z.string().min(1).optional()
+	localPath: z.string().min(1).superRefine((localPath, ctx) => {
+		const safetyError = getRepoLocalPathSafetyError(localPath);
+		if (!safetyError) return;
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: safetyError
+		});
+	}).optional()
 });
 /**
 * Untagged base shape — 5 user-tunable fields, no `kind` discriminator.
@@ -630,6 +659,16 @@ const agentTypeSchema = z.enum([
 	"autonomous_agent"
 ]);
 const agentVisibilitySchema = z.enum(["private", "organization"]);
+const avatarColorTokenSchema = z.enum([
+	"hue-0",
+	"hue-1",
+	"hue-2",
+	"hue-3",
+	"hue-4",
+	"hue-5",
+	"hue-6",
+	"hue-7"
+]);
 const agentSourceSchema = z.enum(["admin-api", "portal"]);
 z.enum(["active", "suspended"]);
 /**
@@ -676,7 +715,8 @@ z.object({
 	visibility: agentVisibilitySchema.optional(),
 	metadata: z.record(z.string(), z.unknown()).optional(),
 	managerId: z.string().nullable().optional(),
-	clientId: z.string().min(1).max(100).nullable().optional()
+	clientId: z.string().min(1).max(100).nullable().optional(),
+	avatarColorToken: avatarColorTokenSchema.nullable().optional()
 });
 z.object({
 	clientId: z.string().min(1).max(100),
@@ -698,6 +738,8 @@ z.object({
 	managerId: z.string().nullable(),
 	clientId: z.string().nullable(),
 	runtimeProvider: runtimeProviderSchema,
+	avatarColorToken: z.string().nullable(),
+	avatarImageUrl: z.string().nullable(),
 	presenceStatus: presenceStatusSchema.optional(),
 	createdAt: z.string(),
 	updatedAt: z.string()
@@ -759,6 +801,14 @@ const chatMetadataSchema = z.discriminatedUnion("source", [githubChatMetadataSch
 * sneak through `{ source: "github" }` without the required fields.
 */
 const optionalChatMetadataSchema = z.union([z.object({}).strict(), chatMetadataSchema]);
+const chatSourceSchema = z.enum([
+	"manual",
+	"github_issue",
+	"github_pull_request",
+	"github_discussion",
+	"github_commit",
+	"feishu"
+]);
 const chatTypeSchema = z.enum(["direct", "group"]);
 const chatEngagementStatusSchema = z.enum([
 	"active",
@@ -970,6 +1020,11 @@ const contextTreeSummarySchema = z.object({
 	removedCount: z.number().int().nonnegative(),
 	changedNodeCount: z.number().int().nonnegative()
 });
+const contextTreeUsageSummarySchema = z.object({
+	windowDays: z.number().int().positive(),
+	agentCount: z.number().int().nonnegative(),
+	usageCount: z.number().int().nonnegative()
+});
 z.object({
 	repo: z.string().nullable(),
 	branch: z.string().nullable(),
@@ -978,6 +1033,7 @@ z.object({
 	snapshotStatus: contextTreeSnapshotStatusSchema,
 	contextStatus: contextTreeStatusSchema,
 	summary: contextTreeSummarySchema,
+	usage: contextTreeUsageSummarySchema,
 	updates: z.array(contextTreeUpdateSchema),
 	nodes: z.array(contextTreeNodeSchema),
 	edges: z.array(contextTreeEdgeSchema),
@@ -1254,12 +1310,35 @@ z.object({
 	cursor: z.string().optional(),
 	limit: z.coerce.number().int().min(1).max(200).default(50),
 	filter: meChatFilterSchema.default("all"),
-	engagement: chatEngagementViewSchema.default("active")
+	engagement: chatEngagementViewSchema.default("active"),
+	source: chatSourceSchema.optional()
 });
 const meChatParticipantSchema = z.object({
 	agentId: z.string(),
 	displayName: z.string(),
-	type: z.string()
+	type: z.string(),
+	avatarColorToken: z.string().nullable(),
+	avatarImageUrl: z.string().nullable()
+});
+/**
+* Live activity hint surfaced in the conversation row's time slot. Derived
+* server-side from the latest `session_events` row for the chat. See
+* `MeChatRow.liveActivity` for the lifecycle rules.
+*
+* `kind` is intentionally narrower than the full `sessionEventKind` enum:
+* `turn_end` / `error` produce `liveActivity: null` rather than a live
+* indicator.
+*/
+const liveActivityKindSchema = z.enum([
+	"tool_call",
+	"thinking",
+	"assistant_text"
+]);
+const liveActivitySchema = z.object({
+	agentId: z.string(),
+	kind: liveActivityKindSchema,
+	label: z.string(),
+	startedAt: z.string()
 });
 const meChatRowSchema = z.object({
 	chatId: z.string(),
@@ -1274,7 +1353,8 @@ const meChatRowSchema = z.object({
 	unreadMentionCount: z.number().int(),
 	canReply: z.boolean(),
 	engagementStatus: chatEngagementStatusSchema,
-	workingAgentIds: z.array(z.string())
+	engagedAgentIds: z.array(z.string()),
+	liveActivity: liveActivitySchema.nullable()
 });
 z.object({
 	rows: z.array(meChatRowSchema),
@@ -1298,6 +1378,47 @@ z.object({
 	type: z.literal("chat:message"),
 	chatId: z.string()
 });
+/**
+* Per-source aggregate for the conversation-list tag bar.
+*
+*   - `chatCount` — number of chats the caller is in for this source. Used
+*     to hide tags whose count is 0 ("don't render a PR tag if there are no
+*     PRs").
+*   - `unreadChatCount` — number of chats whose `unread_mention_count > 0`.
+*     This is "chats with unread mentions", NOT "total mention count", so
+*     the badge on each tag matches the semantics of the existing `unread`
+*     filter pill (`totalUnread` in `pages/workspace/conversations`) — a
+*     `2` on the PR tag means "2 PR chats have unread mentions", which is
+*     what a user expects to click into.
+*
+* The map ALWAYS contains the `manual` key (the default tab is always
+* available, even at zero counts); other keys are present only when the
+* caller has at least one chat for that source.
+*/
+const chatSourceCountSchema = z.object({
+	chatCount: z.number().int().nonnegative(),
+	unreadChatCount: z.number().int().nonnegative()
+});
+z.object({ engagement: chatEngagementViewSchema.default("active") });
+z.object({ counts: z.partialRecord(chatSourceSchema, chatSourceCountSchema) });
+const workspaceDocRefSchema = z.object({
+	type: z.literal("workspace"),
+	chatId: z.string().trim().min(1),
+	agentId: z.string().trim().min(1),
+	basePath: z.string().trim().optional(),
+	path: z.string().trim().min(1)
+});
+const documentContextSchema = z.object({ basePath: z.string().trim().min(1) });
+z.object({
+	agentId: z.string().trim().min(1),
+	basePath: z.string().trim().optional(),
+	path: z.string().trim().min(1)
+});
+z.object({
+	ref: workspaceDocRefSchema,
+	path: z.string(),
+	content: z.string()
+});
 z.enum([
 	"connect",
 	"create_agent",
@@ -1349,7 +1470,8 @@ z.object({
 	organizationId: z.string(),
 	organizationName: z.string(),
 	role: z.enum(["admin", "member"]),
-	agentId: z.string()
+	agentId: z.string(),
+	orgHasOtherMembers: z.boolean()
 });
 const memberRoleSchema = z.enum(["admin", "member"]);
 const memberSchema = z.object({
@@ -1724,7 +1846,8 @@ const sessionEventKind = z.enum([
 	"error",
 	"assistant_text",
 	"thinking",
-	"turn_end"
+	"turn_end",
+	"context_tree_usage"
 ]);
 const toolCallEventPayload = z.object({
 	toolUseId: z.string(),
@@ -1766,6 +1889,10 @@ const thinkingEventPayload = z.object({});
 * completed turns to show only the final result message.
 */
 const turnEndEventPayload = z.object({ status: z.enum(["success", "error"]) });
+const contextTreeUsageEventPayload = z.object({
+	purpose: z.literal("design_decision"),
+	treeRepoUrl: z.string().nullable()
+});
 const sessionEventSchema = z.discriminatedUnion("kind", [
 	z.object({
 		kind: z.literal("tool_call"),
@@ -1786,6 +1913,10 @@ const sessionEventSchema = z.discriminatedUnion("kind", [
 	z.object({
 		kind: z.literal("turn_end"),
 		payload: turnEndEventPayload
+	}),
+	z.object({
+		kind: z.literal("context_tree_usage"),
+		payload: contextTreeUsageEventPayload
 	})
 ]);
 z.object({
@@ -1799,7 +1930,8 @@ z.object({
 		errorEventPayload,
 		assistantTextEventPayload,
 		thinkingEventPayload,
-		turnEndEventPayload
+		turnEndEventPayload,
+		contextTreeUsageEventPayload
 	]),
 	createdAt: z.string()
 });
@@ -1968,6 +2100,7 @@ defineConfig({
 		host: field(z.string().default("127.0.0.1"), { env: "FIRST_TREE_HUB_HOST" }),
 		publicUrl: field(z.string().optional(), { env: "FIRST_TREE_HUB_PUBLIC_URL" })
 	},
+	workspace: { root: field(z.string().default(join(DEFAULT_DATA_DIR, "workspaces")), { env: "FIRST_TREE_HUB_WORKSPACES_ROOT" }) },
 	secrets: {
 		jwtSecret: field(z.string(), {
 			env: "FIRST_TREE_HUB_JWT_SECRET",
@@ -3309,7 +3442,7 @@ You are running inside **Agent Hub**, a messaging platform for agent teams.
 
 - Messages from other team members arrive as your prompt input
 - Each message includes a \`[From: <agent-name>]\` header — that name is also
-  what you pass back to \`agent send\` to reply to or address that agent
+  what you pass back to \`chat send\` to reply to or address that agent
 - **Your final text response is automatically delivered** to the chat — just respond normally
 - For **proactive communication** (sending to other agents, other chats, or structured data),
   use the \`first-tree-hub\` CLI below
@@ -3333,7 +3466,7 @@ The \`first-tree-hub\` CLI reads these automatically — no extra setup needed.
 
 ## Sending Messages
 
-Use the \`first-tree-hub agent send\` CLI — it reads the env vars above and
+Use the \`first-tree-hub chat send\` CLI — it reads the env vars above and
 attaches the \`Authorization\` + \`X-Agent-Id\` headers automatically:
 
 \`\`\`bash
@@ -3345,28 +3478,38 @@ attaches the \`Authorization\` + \`X-Agent-Id\` headers automatically:
 # the case in a group chat where someone @-mentioned you to talk to them),
 # the message stays in that chat. Otherwise it falls back to a direct chat
 # between you and the recipient. You don't need to think about which.
-first-tree-hub agent send <agentName> "your message"
+first-tree-hub chat send <agentName> "your message"
 
 # Send into a specific chat by id — use this only when you explicitly want
 # to address a chat your current session is NOT bound to.
-first-tree-hub agent send --chat <chatId> "your message"
+first-tree-hub chat send --chat <chatId> "your message"
 
 # Send markdown (default format is text)
-first-tree-hub agent send <agentName> -f markdown "**bold** message"
+first-tree-hub chat send <agentName> -f markdown "**bold** message"
 
 # Reply to a specific message
-first-tree-hub agent send <agentName> --reply-to <messageId> "reply content"
+first-tree-hub chat send <agentName> --reply-to <messageId> "reply content"
 
 # Pipe long content via stdin (recommended for special characters)
-echo "long message body" | first-tree-hub agent send <agentName>
+echo "long message body" | first-tree-hub chat send <agentName>
 \`\`\`
 
-> Agent uuids appear in \`agent chats\`, chat history, and participant lists,
-> but they are NOT accepted by \`agent send\` — always use the name.
+> Agent uuids appear in \`chat list\`, chat history, and participant lists,
+> but they are NOT accepted by \`chat send\` — always use the name.
 
 For content with quotes, \`$\`, backticks, or newlines, prefer stdin to avoid shell escaping issues.
 `;
 }
+function resolveGitRepoTargetPath(workspace, localPath) {
+	const safetyError = getRepoLocalPathSafetyError(localPath);
+	if (safetyError) throw new Error(`Unsafe git repo localPath "${localPath}": ${safetyError}`);
+	const workspaceRoot = resolve(workspace);
+	const targetPath = resolve(workspaceRoot, localPath);
+	const relativeTarget = relative(workspaceRoot, targetPath);
+	const escapesWorkspace = relativeTarget === ".." || relativeTarget.startsWith(`..${sep}`);
+	if (!relativeTarget || escapesWorkspace || isAbsolute(relativeTarget)) throw new Error(`Unsafe git repo localPath "${localPath}": resolved path escapes the session workspace`);
+	return targetPath;
+}
 const DEFAULT_CLONE_TIMEOUT_MS = 300 * 1e3;
 const FETCH_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
 const SESSION_BRANCH_PREFIX = "hub-session";
@@ -4631,6 +4774,7 @@ const createClaudeCodeHandler = (config) => {
 	/** Worktrees materialised for this session — each entry removed on shutdown. */
 	const ownedWorktrees = [];
 	async function toSDKUserMessage(message, sessionCtx, sessionId) {
+		emitContextTreeUsage(sessionCtx);
 		if (message.format === "file") {
 			const senderLabel = message.senderId ? await sessionCtx.resolveSenderLabel(message.senderId) : "";
 			const prefix = senderLabel ? `[From: ${senderLabel}]\n\n` : "";
@@ -4693,6 +4837,16 @@ const createClaudeCodeHandler = (config) => {
 			session_id: sessionId
 		};
 	}
+	function emitContextTreeUsage(sessionCtx) {
+		if (!contextTreePath) return;
+		sessionCtx.emitEvent({
+			kind: "context_tree_usage",
+			payload: {
+				purpose: "design_decision",
+				treeRepoUrl: contextTreeRepoUrl
+			}
+		});
+	}
 	/**
 	* Build env for the child Claude Code process.
 	*
@@ -4994,7 +5148,7 @@ const createClaudeCodeHandler = (config) => {
 		if (!gitMirrorManager || !payload?.gitRepos?.length) return;
 		for (const repo of payload.gitRepos) {
 			const localPath = repo.localPath ?? deriveRepoLocalPath(repo.url);
-			const targetPath = join(workspace, localPath);
+			const targetPath = resolveGitRepoTargetPath(workspace, localPath);
 			sessionCtx.log(`Git: preparing ${repo.url} → ${localPath}${repo.ref ? ` @ ${repo.ref}` : ""}`);
 			const mirror = await gitMirrorManager.ensureMirror(repo.url);
 			if (mirror.cloned) sessionCtx.log(`Git: cloned ${repo.url} in ${mirror.elapsedMs}ms`);
@@ -5205,7 +5359,7 @@ function buildCodexThreadOptions(payload, workspaceCwd) {
 	for (const repo of payload.gitRepos) {
 		const localPath = repo.localPath ?? deriveRepoLocalPath(repo.url);
 		if (!localPath) continue;
-		additionalDirectories.push(join(workspaceCwd, localPath));
+		additionalDirectories.push(resolveGitRepoTargetPath(workspaceCwd, localPath));
 	}
 	const opts = {
 		workingDirectory: workspaceCwd,
@@ -5296,13 +5450,23 @@ const createCodexHandler = (config) => {
 	function toCodexInput(message, sessionCtx) {
 		return sessionCtx.formatInboundContent(message).then((text) => text);
 	}
+	function emitContextTreeUsage(sessionCtx) {
+		if (!contextTreePath) return;
+		sessionCtx.emitEvent({
+			kind: "context_tree_usage",
+			payload: {
+				purpose: "design_decision",
+				treeRepoUrl: contextTreeRepoUrl
+			}
+		});
+	}
 	async function prepareGitWorktrees(payload, workspaceCwd, sessionCtx) {
 		if (!gitMirrorManager) return;
 		const branchAgentKey = agentName ?? sessionCtx.agent.agentId;
 		for (const repo of payload.gitRepos) {
 			const localPath = repo.localPath ?? deriveRepoLocalPath(repo.url);
 			if (!localPath) continue;
-			const targetPath = join(workspaceCwd, localPath);
+			const targetPath = resolveGitRepoTargetPath(workspaceCwd, localPath);
 			if (existsSync(targetPath)) continue;
 			try {
 				await gitMirrorManager.ensureMirror(repo.url);
@@ -5424,6 +5588,7 @@ const createCodexHandler = (config) => {
 		if (!activeThread) return;
 		const abort = new AbortController();
 		currentAbort = abort;
+		emitContextTreeUsage(sessionCtx);
 		sessionCtx.setRuntimeState("working");
 		const assistantTexts = [];
 		let turnFailed = false;
@@ -5908,13 +6073,17 @@ var Deduplicator = class {
 };
 function createResultSink(deps) {
 	async function buildMetadata(trigger) {
-		if (!trigger || trigger.senderId === deps.agent.agentId) return void 0;
-		const participants = await deps.participants.get();
-		if (participants.length <= 2) {
-			const peer = participants.find((p) => p.agentId === trigger.senderId);
-			if (peer && peer.mode !== "mention_only") return void 0;
-		}
-		return { mentions: [trigger.senderId] };
+		const metadata = {};
+		const documentBasePath = await deps.getDocumentBasePath?.();
+		if (documentBasePath) metadata.documentContext = documentContextSchema.parse({ basePath: documentBasePath });
+		if (trigger && trigger.senderId !== deps.agent.agentId) {
+			const participants = await deps.participants.get();
+			if (participants.length <= 2) {
+				const peer = participants.find((p) => p.agentId === trigger.senderId);
+				if (!peer || peer.mode === "mention_only") metadata.mentions = [trigger.senderId];
+			} else metadata.mentions = [trigger.senderId];
+		}
+		return Object.keys(metadata).length > 0 ? metadata : void 0;
 	}
 	return async function forwardResult(text) {
 		if (text.trim().length === 0) {
@@ -6005,6 +6174,16 @@ var SessionRegistry = class {
 		}
 	}
 };
+function documentBasePathFromRuntimeConfig(payload) {
+	if (payload.gitRepos.length !== 1) return null;
+	const repo = payload.gitRepos[0];
+	if (!repo) return null;
+	const localPath = repoLocalPath(repo).trim();
+	return localPath.length > 0 ? localPath : null;
+}
+function repoLocalPath(repo) {
+	return repo.localPath ?? deriveRepoLocalPath(repo.url);
+}
 /**
 * Manages per-chat session entries with session-oriented handler lifecycle.
 *
@@ -6494,7 +6673,8 @@ var SessionManager = class {
 				this.currentTrigger.delete(chatId);
 			},
 			log,
-			participants
+			participants,
+			getDocumentBasePath: () => this.resolveDocumentBasePath(log)
 		});
 		const envCtx = {
 			sdk: this.config.sdk,
@@ -6522,6 +6702,16 @@ var SessionManager = class {
 			resolveSenderLabel: async (senderId) => resolveSenderLabel(senderId, await participants.get())
 		};
 	}
+	async resolveDocumentBasePath(log) {
+		if (!this.config.agentConfigCache) return null;
+		try {
+			const { payload } = await this.config.agentConfigCache.refreshIfNewer(this.config.agentIdentity.agentId, 0);
+			return documentBasePathFromRuntimeConfig(payload);
+		} catch (err) {
+			log(`document preview base path unavailable: ${err instanceof Error ? err.message : String(err)}`);
+			return null;
+		}
+	}
 	/** Update per-session runtime state and recompute aggregate. Only active sessions may update. */
 	setSessionRuntimeState(chatId, state) {
 		const session = this.sessions.get(chatId);
@@ -7276,7 +7466,7 @@ function fail(code, message, exitCode = 1) {
 //#endregion
 //#region src/core/agent-messaging.ts
 /**
-* Resolve `replyTo` envelope fields for `agent send`. When the CLI is invoked
+* Resolve `replyTo` envelope fields for `chat send`. When the CLI is invoked
 * from inside a claude-code session (the handler exports
 * `FIRST_TREE_HUB_CHAT_ID` + `FIRST_TREE_HUB_INBOX_ID`), default the reply
 * target to the calling session's own chat so the peer's reply routes back
@@ -7568,7 +7758,7 @@ function rotateClientIdWithBackup(configDir) {
 }
 /**
 * Shared handler for `CLIENT_ORG_MISMATCH` across CLI entry points
-* (`client start` and `client connect --no-service`). Prompts interactively,
+* (`client start` and `connect <token> --no-service`). Prompts interactively,
 * rotates the local clientId, and always exits the current process — the
 * runtime is already poisoned (wrong clientId in memory), so continuing
 * in-band is not safe. Service-supervised (managed) runs skip the prompt and
@@ -8331,7 +8521,7 @@ function installLaunchd() {
 		lastBootstrapErr = res;
 		if (attempt < 2) sleepSync(1e3);
 	}
-	if (lastBootstrapErr) throw new Error(`launchctl bootstrap failed: ${lastBootstrapErr.stderr || `exit ${lastBootstrapErr.code ?? "unknown"}`}\n    Command: launchctl bootstrap ${target} ${plistPath}\n    Recovery: \`launchctl bootout ${target}/${LAUNCHD_LABEL}\` then \`first-tree-hub client connect <server-url>\`.`);
+	if (lastBootstrapErr) throw new Error(`launchctl bootstrap failed: ${lastBootstrapErr.stderr || `exit ${lastBootstrapErr.code ?? "unknown"}`}\n    Command: launchctl bootstrap ${target} ${plistPath}\n    Recovery: \`launchctl bootout ${target}/${LAUNCHD_LABEL}\` then \`first-tree-hub connect <token>\`.`);
 	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, pid, detail } = launchdState();
@@ -8491,7 +8681,7 @@ function installSystemd() {
 		"--now",
 		SYSTEMD_UNIT
 	], 1e4);
-	if (!enableRes.ok) throw new Error(`systemctl --user enable --now ${SYSTEMD_UNIT} failed: ${enableRes.stderr || `exit ${enableRes.code ?? "unknown"}`}\n    Recovery: \`systemctl --user stop ${SYSTEMD_UNIT}\` then \`first-tree-hub client connect <server-url>\`.`);
+	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 connect <token>\`.`);
 	const { state, pid, detail } = systemdState();
 	return {
 		platform: "systemd",
@@ -9003,7 +9193,7 @@ function checkBackgroundService() {
 	return {
 		label: "Background service",
 		ok: false,
-		detail: "not installed — re-run `first-tree-hub client connect <url>` to install"
+		detail: "not installed — re-run `first-tree-hub connect <token>` to install"
 	};
 }
 async function checkWebSocket() {
@@ -9297,7 +9487,7 @@ function runHomeMigration() {
 	}
 	print.line(`[first-tree-hub] Copied client home to new layout: ${result.from} → ${result.to}\n  (Legacy directory preserved as a backup — delete it manually once you've verified the new location works.)\n`);
 	if (process.argv.includes("--no-interactive")) {
-		print.line("[first-tree-hub] Note: running as background service — skipped auto re-register to avoid self-termination.\n  Service paths will refresh on the next `first-tree-hub client connect <url>`.\n");
+		print.line("[first-tree-hub] Note: running as background service — skipped auto re-register to avoid self-termination.\n  Service paths will refresh on the next `first-tree-hub connect <token>`.\n");
 		return;
 	}
 	const status = getClientServiceStatus();
@@ -9307,7 +9497,7 @@ function runHomeMigration() {
 		print.line(`[first-tree-hub] Re-registered background service with new home paths.\n`);
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
-		print.line(`[first-tree-hub] WARNING: home migration succeeded but re-registering the background service failed: ${msg}\n  Re-run \`first-tree-hub client connect <url>\` to refresh service paths.\n`);
+		print.line(`[first-tree-hub] WARNING: home migration succeeded but re-registering the background service failed: ${msg}\n  Re-run \`first-tree-hub connect <token>\` to refresh service paths.\n`);
 	}
 }
 //#endregion
@@ -9339,7 +9529,7 @@ async function onboardCheck(args) {
 		key: "connect",
 		label: "Signed in",
 		status: "missing_required",
-		hint: "Run `first-tree-hub client connect <server-url>` first"
+		hint: "Run `first-tree-hub connect <token>` first"
 	});
 	try {
 		const serverUrl = resolveServerUrl(args.server);
@@ -9493,7 +9683,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-30vUx69l.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-BGx71p5s.mjs").then((n) => n.r);
 		const targetAgentUuid = args.type === "human" ? assistantUuid : primary.uuid;
 		if (!targetAgentUuid) print.line(`Warning: Cannot bind Feishu bot — no runtime agent available for "${args.id}".\n`);
 		else {
@@ -9580,13 +9770,13 @@ async function promptMissingFields(options) {
 * add (there's nothing sensible to key the local dir on).
 */
 async function promptAddAgent(opts = {}) {
-	if (loadCredentials() === null) throw new Error("Not connected. Run `first-tree-hub client connect <server-url>` first.");
+	if (loadCredentials() === null) throw new Error("Not connected. Run `first-tree-hub connect <token>` first.");
 	let serverUrl;
 	try {
 		serverUrl = resolveServerUrl(process.env.FIRST_TREE_HUB_SERVER_URL);
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`${msg} Run \`first-tree-hub client connect\` or set FIRST_TREE_HUB_SERVER_URL.`);
+		throw new Error(`${msg} Run \`first-tree-hub connect <token>\` or set FIRST_TREE_HUB_SERVER_URL.`);
 	}
 	const agentId = opts.agentId ?? await input({
 		message: "Agent UUID on the Hub:",
@@ -10706,7 +10896,7 @@ function createFeedbackHandler(config) {
 	return { handle };
 }
 //#endregion
-//#region ../server/dist/app-B1wsm8zG.mjs
+//#region ../server/dist/app-l2iy80P2.mjs
 var import_fastify_opentelemetry = /* @__PURE__ */ __toESM(require_fastify_opentelemetry(), 1);
 init_esm();
 var __defProp = Object.defineProperty;
@@ -11316,6 +11506,21 @@ async function ensureDefaultOrganization(db) {
 */
 const RESERVED_AGENT_NAME_PREFIX = "__";
 /**
+* Derive the relative URL clients should use to fetch a manager-uploaded
+* avatar image. Returns `null` when no image is set. Embeds the upload
+* timestamp as `?v=<epoch>` so a fresh upload busts any browser cache
+* that may have memoised the previous version.
+*
+* Auth: the image route is intentionally public read — the URL leaks no
+* more than the agent's UUID, which is already required to address it.
+* Keeping it unauthenticated lets `<img src>` render without bespoke
+* fetch-and-blob plumbing.
+*/
+function agentAvatarImageUrl(uuid, updatedAt) {
+	if (!updatedAt) return null;
+	return `/api/v1/agents/${uuid}/avatar?v=${updatedAt.getTime()}`;
+}
+/**
 * True iff `clients.metadata.capabilities` is a non-empty object — i.e. the
 * client has reported at least one runtime probe result. Used to distinguish
 * "we don't know what's installed yet" (empty / never reported) from
@@ -11406,7 +11611,7 @@ async function resolveAgentClient(db, data) {
 		userId: clients.userId
 	}).from(clients).where(eq(clients.id, data.clientId)).limit(1);
 	if (!client) throw new BadRequestError(`Client "${data.clientId}" not found`);
-	if (!client.userId) throw new BadRequestError(`Client "${data.clientId}" has not been claimed by a user yet. Have the operator run \`first-tree-hub client connect\` on that machine before pinning an agent to it.`);
+	if (!client.userId) throw new BadRequestError(`Client "${data.clientId}" has not been claimed by a user yet. Have the operator run \`first-tree-hub connect <token>\` on that machine before pinning an agent to it.`);
 	if (client.userId !== manager.userId) throw new ForbiddenError(`Client "${data.clientId}" is not owned by the manager's user — pick a client belonging to that user.`);
 	return client.id;
 }
@@ -11574,6 +11779,8 @@ async function listAgentsForAdmin(db, scope, limit, cursor) {
 		managerId: agents.managerId,
 		clientId: agents.clientId,
 		runtimeProvider: agents.runtimeProvider,
+		avatarColorToken: agents.avatarColorToken,
+		avatarImageUpdatedAt: agents.avatarImageUpdatedAt,
 		createdAt: agents.createdAt,
 		updatedAt: agents.updatedAt,
 		presenceStatus: agentPresence.status,
@@ -11612,6 +11819,8 @@ async function listAgentsForMember(db, scope, limit, cursor, type) {
 		managerId: agents.managerId,
 		clientId: agents.clientId,
 		runtimeProvider: agents.runtimeProvider,
+		avatarColorToken: agents.avatarColorToken,
+		avatarImageUpdatedAt: agents.avatarImageUpdatedAt,
 		createdAt: agents.createdAt,
 		updatedAt: agents.updatedAt,
 		presenceStatus: agentPresence.status,
@@ -11648,6 +11857,7 @@ async function updateAgent(db, uuid, data) {
 	}
 	if (data.visibility !== void 0) updates.visibility = data.visibility;
 	if (data.metadata !== void 0) updates.metadata = data.metadata;
+	if (data.avatarColorToken !== void 0) updates.avatarColorToken = data.avatarColorToken;
 	if (data.managerId !== void 0) {
 		if (data.managerId === null) throw new BadRequestError("managerId cannot be cleared — every agent must have a manager");
 		const [manager] = await db.select({
@@ -11754,6 +11964,63 @@ async function deleteAgent(db, uuid) {
 	if (!agent) throw new Error("Unexpected: UPDATE RETURNING produced no row");
 	return agent;
 }
+/**
+* Supported avatar-image MIME types. The web client always uploads WEBP after
+* its own resize step; we accept PNG/JPEG too so a caller using the raw HTTP
+* API (curl, scripts) doesn't have to re-encode. Anything else is rejected at
+* the boundary — we never store an unknown content type.
+*/
+const SUPPORTED_AVATAR_IMAGE_MIMES = [
+	"image/webp",
+	"image/png",
+	"image/jpeg"
+];
+/** Hard server-side ceiling for the stored bytea blob. Client pre-resizes to ~50KB. */
+const MAX_AVATAR_IMAGE_BYTES = 512 * 1024;
+function isSupportedAvatarMime(mime) {
+	return SUPPORTED_AVATAR_IMAGE_MIMES.find((m) => m === mime) !== void 0;
+}
+/**
+* Fetch the avatar image blob for an agent. Returns `null` when no image
+* is set (the column is NULL). The data + mime pair is always coherent
+* (set/cleared together by the service writes below).
+*/
+async function getAgentAvatarImage(db, uuid) {
+	const [row] = await db.select({
+		data: agents.avatarImageData,
+		mime: agents.avatarImageMime,
+		updatedAt: agents.avatarImageUpdatedAt
+	}).from(agents).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).limit(1);
+	if (!row || !row.data || !row.mime || !row.updatedAt) return null;
+	return {
+		data: row.data,
+		mime: row.mime,
+		updatedAt: row.updatedAt
+	};
+}
+/** Replace (or set) an agent's avatar image. Validates mime + size. */
+async function setAgentAvatarImage(db, uuid, data, mime) {
+	if (!isSupportedAvatarMime(mime)) throw new BadRequestError(`Unsupported avatar image type "${mime}". Use PNG, JPEG, or WEBP.`);
+	if (data.length === 0) throw new BadRequestError("Avatar image payload is empty.");
+	if (data.length > 524288) throw new BadRequestError(`Avatar image is too large (${data.length} bytes; max ${MAX_AVATAR_IMAGE_BYTES}).`);
+	const now = /* @__PURE__ */ new Date();
+	if ((await db.update(agents).set({
+		avatarImageData: data,
+		avatarImageMime: mime,
+		avatarImageUpdatedAt: now,
+		updatedAt: now
+	}).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).returning({ uuid: agents.uuid })).length === 0) throw new NotFoundError(`Agent "${uuid}" not found`);
+	return now;
+}
+/** Clear an agent's avatar image (falls back to color + initial). */
+async function clearAgentAvatarImage(db, uuid) {
+	if ((await db.update(agents).set({
+		avatarImageData: null,
+		avatarImageMime: null,
+		avatarImageUpdatedAt: null,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).returning({ uuid: agents.uuid })).length === 0) throw new NotFoundError(`Agent "${uuid}" not found`);
+}
 const log$5 = createLogger$1("AgentFeishuBot");
 async function agentFeishuBotRoutes(app) {
 	/**
@@ -12964,8 +13231,9 @@ async function pushToWebhook(notification) {
 }
 /**
 * Session events — structured event stream per (agent, chat) session.
-* `kind` is 'tool_call' | 'error'; the payload shape is enforced by the
-* service layer via Zod (no FK / CHECK on this table per project rule).
+* `kind` is one of `'tool_call' | 'error' | 'assistant_text' | 'thinking'
+* | 'turn_end'`; payload shape per kind is enforced by the service layer
+* via Zod (no FK / CHECK on this table per project rule).
 *
 * `seq` is monotonic per (agent_id, chat_id). The single-writer invariant
 * in the client-side session-manager guarantees ordering; the service wraps
@@ -13061,6 +13329,18 @@ async function listEvents(db, agentId, chatId, options) {
 async function clearEvents(db, agentId, chatId) {
 	await db.delete(sessionEvents).where(and(eq(sessionEvents.agentId, agentId), eq(sessionEvents.chatId, chatId)));
 }
+async function summarizeContextTreeUsage(db, organizationId, windowDays) {
+	const since = /* @__PURE__ */ new Date(Date.now() - windowDays * 24 * 60 * 60 * 1e3);
+	const [row] = await db.select({
+		agentCount: sql`count(distinct ${sessionEvents.agentId})::int`,
+		usageCount: sql`count(*)::int`
+	}).from(sessionEvents).innerJoin(agents, eq(agents.uuid, sessionEvents.agentId)).where(and(eq(agents.organizationId, organizationId), eq(sessionEvents.kind, "context_tree_usage"), gte(sessionEvents.createdAt, since)));
+	return {
+		windowDays,
+		agentCount: row?.agentCount ?? 0,
+		usageCount: row?.usageCount ?? 0
+	};
+}
 /**
 * Default per-agent in-flight cap when `server.inbox.maxInFlightPerAgent` is
 * unset. Mirrors the schema default so a hub running without an explicit
@@ -13623,9 +13903,11 @@ function clientWsRoutes(notifier, instanceId) {
 								return;
 							}
 							const payload = sessionEventMessageSchema.parse(msg);
+							const boundInfo = boundAgents.get(agentId);
 							chainSessionOp(agentId, payload.chatId, async () => {
 								try {
 									await appendEvent(app.db, agentId, payload.chatId, payload.event);
+									if (boundInfo) notifier.notifySessionEvent(agentId, payload.chatId, payload.event.kind, boundInfo.organizationId).catch(() => {});
 								} catch (err) {
 									socket.send(JSON.stringify({
 										type: "error",
@@ -13709,6 +13991,22 @@ async function agentActivityRoutes(app) {
 	});
 }
 /**
+* Project a DB agent row into its wire shape. Strips the inline image
+* `avatarImageData` (large bytea, only meant for the image-serve route)
+* and synthesises the public `avatarImageUrl` from the upload timestamp.
+* `createdAt`/`updatedAt` are coerced to ISO strings so the response is
+* pure JSON.
+*/
+function serializeAgent(agent) {
+	const { avatarImageData: _data, avatarImageMime: _mime, avatarImageUpdatedAt, createdAt, updatedAt, ...rest } = agent;
+	return {
+		...rest,
+		createdAt: createdAt.toISOString(),
+		updatedAt: updatedAt.toISOString(),
+		avatarImageUrl: agentAvatarImageUrl(agent.uuid, avatarImageUpdatedAt ?? null)
+	};
+}
+/**
 * Class C — resource-scoped per-agent routes. Mounted at
 * `/api/v1/agents/:uuid/...`. The agent's UUID locates its org
 * intrinsically; `requireAgentAccess` resolves the caller's membership in
@@ -13737,11 +14035,7 @@ async function agentRoutes(app) {
 	}
 	app.get("/:uuid", async (request) => {
 		const { agent } = await requireAgentAccess(request, app.db, "visible");
-		return {
-			...agent,
-			createdAt: agent.createdAt.toISOString(),
-			updatedAt: agent.updatedAt.toISOString()
-		};
+		return serializeAgent(agent);
 	});
 	app.patch("/:uuid", { config: { otelRecordBody: true } }, async (request) => {
 		const { scope } = await requireAgentAccess(request, app.db, "manage");
@@ -13750,22 +14044,14 @@ async function agentRoutes(app) {
 		const before = body.clientId !== void 0 ? await getAgent(app.db, request.params.uuid) : null;
 		const agent = await updateAgent(app.db, request.params.uuid, body);
 		if (before && before.clientId === null && agent.clientId !== null) notifyClientAgentPinned(agent);
-		return {
-			...agent,
-			createdAt: agent.createdAt.toISOString(),
-			updatedAt: agent.updatedAt.toISOString()
-		};
+		return serializeAgent(agent);
 	});
 	app.patch("/:uuid/rebind", { config: { otelRecordBody: true } }, async (request) => {
 		await requireAgentAccess(request, app.db, "manage");
 		const body = rebindAgentSchema.parse(request.body);
 		const agent = await rebindAgent(app.db, request.params.uuid, body);
 		notifyClientAgentPinned(agent);
-		return {
-			...agent,
-			createdAt: agent.createdAt.toISOString(),
-			updatedAt: agent.updatedAt.toISOString()
-		};
+		return serializeAgent(agent);
 	});
 	app.post("/:uuid/disconnect", async (request, reply) => {
 		await requireAgentAccess(request, app.db, "manage");
@@ -13775,27 +14061,35 @@ async function agentRoutes(app) {
 	});
 	app.post("/:uuid/suspend", async (request) => {
 		await requireAgentAccess(request, app.db, "manage");
-		const agent = await suspendAgent(app.db, request.params.uuid);
-		return {
-			...agent,
-			createdAt: agent.createdAt.toISOString(),
-			updatedAt: agent.updatedAt.toISOString()
-		};
+		return serializeAgent(await suspendAgent(app.db, request.params.uuid));
 	});
 	app.post("/:uuid/reactivate", async (request) => {
 		await requireAgentAccess(request, app.db, "manage");
-		const agent = await reactivateAgent(app.db, request.params.uuid);
-		return {
-			...agent,
-			createdAt: agent.createdAt.toISOString(),
-			updatedAt: agent.updatedAt.toISOString()
-		};
+		return serializeAgent(await reactivateAgent(app.db, request.params.uuid));
 	});
 	app.delete("/:uuid", async (request, reply) => {
 		await requireAgentAccess(request, app.db, "manage");
 		await deleteAgent(app.db, request.params.uuid);
 		return reply.status(204).send();
 	});
+	app.addContentTypeParser(/^image\//, { parseAs: "buffer" }, (_req, body, done) => {
+		done(null, body);
+	});
+	app.put("/:uuid/avatar", { bodyLimit: MAX_AVATAR_IMAGE_BYTES + 1024 }, async (request, reply) => {
+		await requireAgentAccess(request, app.db, "manage");
+		const contentType = request.headers["content-type"];
+		if (typeof contentType !== "string" || !contentType.startsWith("image/")) throw new BadRequestError(`Avatar upload requires an image/* Content-Type. Supported: ${SUPPORTED_AVATAR_IMAGE_MIMES.join(", ")}.`);
+		const mime = contentType.split(";")[0]?.trim() ?? "";
+		const body = request.body;
+		if (!Buffer.isBuffer(body)) throw new BadRequestError("Avatar upload body must be raw image bytes.");
+		const updatedAt = await setAgentAvatarImage(app.db, request.params.uuid, body, mime);
+		return reply.status(200).send({ avatarImageUrl: agentAvatarImageUrl(request.params.uuid, updatedAt) });
+	});
+	app.delete("/:uuid/avatar", async (request, reply) => {
+		await requireAgentAccess(request, app.db, "manage");
+		await clearAgentAvatarImage(app.db, request.params.uuid);
+		return reply.status(204).send();
+	});
 	app.post("/:uuid/test", async (request, reply) => {
 		const { uuid } = request.params;
 		const { agent: targetAgent } = await requireAgentAccess(request, app.db, "manage");
@@ -13827,7 +14121,7 @@ async function agentRoutes(app) {
 		};
 		if (health === "disconnected") return reply.status(200).send({
 			status: "offline",
-			message: "Agent is not connected. Start the client with: first-tree-hub client connect <server-url>",
+			message: "Agent is not connected. Connect the client with: first-tree-hub connect <token>",
 			connection
 		});
 		if (health === "stale") return reply.status(200).send({
@@ -13904,6 +14198,23 @@ async function agentRoutes(app) {
 	});
 }
 /**
+* Public read-only route for agent avatar images. Mounted outside the
+* member-JWT auth scope so `<img src>` works without bespoke fetch-and-blob
+* plumbing. Reading an avatar leaks no more than the agent's UUID — which
+* is already required to address the route — and the UUID itself is only
+* exposed through authenticated agent-list calls.
+*/
+async function publicAgentAvatarRoutes(app) {
+	app.get("/:uuid/avatar", async (request, reply) => {
+		const image = await getAgentAvatarImage(app.db, request.params.uuid);
+		if (!image) return reply.status(404).send({ error: "Avatar not set" });
+		reply.header("Content-Type", image.mime);
+		reply.header("Cache-Control", "public, max-age=2592000, immutable");
+		reply.header("ETag", `"${image.updatedAt.getTime()}"`);
+		return reply.send(image.data);
+	});
+}
+/**
 * Class C — `/api/v1/agents/:uuid/config`. Runtime config (system prompt,
 * tools, env) is behavior-sensitive — gated on `manage`, not `visible`.
 */
@@ -14949,6 +15260,22 @@ async function listActiveMemberships(db, userId) {
 	}).from(members).innerJoin(organizations, eq(members.organizationId, organizations.id)).where(and(eq(members.userId, userId), eq(members.status, "active"))).orderBy(desc(members.createdAt));
 }
 /**
+* Count ACTIVE members per org, restricted to the given org IDs. Returns a
+* Map keyed by `organizationId`; orgs absent from the result simply have
+* zero active members (shouldn't happen in practice — the caller always
+* passes orgs the user is a member of — but the Map shape lets callers do
+* `counts.get(orgId) ?? 0` defensively). Used by `/me` to surface
+* `orgHasOtherMembers` per membership without N+1 queries.
+*/
+async function countActiveMembersByOrgs(db, organizationIds) {
+	if (organizationIds.length === 0) return /* @__PURE__ */ new Map();
+	const rows = await db.select({
+		organizationId: members.organizationId,
+		count: sql`count(*)::int`
+	}).from(members).where(and(inArray(members.organizationId, organizationIds), eq(members.status, "active"))).groupBy(members.organizationId);
+	return new Map(rows.map((r) => [r.organizationId, r.count]));
+}
+/**
 * Pick the most recently joined active membership — used after OAuth login
 * when the user already has at least one team but no `next` was specified.
 */
@@ -15740,16 +16067,16 @@ function decodeCursor(cursor) {
 		return null;
 	}
 }
-const { ACTIVE, ARCHIVED, DELETED } = CHAT_ENGAGEMENT_STATUSES;
+const { ACTIVE: ACTIVE$1, ARCHIVED: ARCHIVED$1, DELETED } = CHAT_ENGAGEMENT_STATUSES;
 /**
 * SQL predicate for each engagement view tab. `deleted` is never a valid view
 * value — deleted rows are reachable only through `GET /chats/:chatId` + the
 * Restore banner on the chat detail page.
 */
 const ENGAGEMENT_VIEW_PREDICATE = {
-	active: sql`COALESCE(cus.engagement_status, ${ACTIVE}) = ${ACTIVE}`,
-	archived: sql`COALESCE(cus.engagement_status, ${ACTIVE}) = ${ARCHIVED}`,
-	all: sql`COALESCE(cus.engagement_status, ${ACTIVE}) IN (${ACTIVE}, ${ARCHIVED})`
+	active: sql`COALESCE(cus.engagement_status, ${ACTIVE$1}) = ${ACTIVE$1}`,
+	archived: sql`COALESCE(cus.engagement_status, ${ACTIVE$1}) = ${ARCHIVED$1}`,
+	all: sql`COALESCE(cus.engagement_status, ${ACTIVE$1}) IN (${ACTIVE$1}, ${ARCHIVED$1})`
 };
 /**
 * Write the caller's engagement state for this chat. UPSERT into
@@ -15777,7 +16104,26 @@ async function setChatEngagement(db, chatId, agentId, status) {
 */
 async function getCallerEngagement(db, chatId, agentId) {
 	const [row] = await db.select({ engagementStatus: chatUserState.engagementStatus }).from(chatUserState).where(and(eq(chatUserState.chatId, chatId), eq(chatUserState.agentId, agentId))).limit(1);
-	return row?.engagementStatus ?? ACTIVE;
+	return row?.engagementStatus ?? ACTIVE$1;
+}
+const KNOWN_NON_MANUAL_PREDICATE = sql`(
+     (c.metadata->>'source' = 'github' AND c.metadata->>'entityType' IN (${sql.join(GITHUB_ENTITY_TYPES.map((t) => sql`${t}`), sql.raw(", "))}))
+  OR c.metadata->>'source' = 'feishu'
+)`;
+const chatSourceSqlExpression = sql`CASE
+    ${sql.join(GITHUB_ENTITY_TYPES.map((t) => sql`WHEN c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = ${t} THEN ${`github_${t}`}`), sql.raw("\n    "))}
+    WHEN c.metadata->>'source' = 'feishu' THEN 'feishu'
+    ELSE 'manual'
+  END`;
+function sourceFilterSql(source) {
+	switch (source) {
+		case "manual": return sql`(${KNOWN_NON_MANUAL_PREDICATE}) IS NOT TRUE`;
+		case "github_issue": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'issue')`;
+		case "github_pull_request": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'pull_request')`;
+		case "github_discussion": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'discussion')`;
+		case "github_commit": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'commit')`;
+		case "feishu": return sql`(c.metadata->>'source' = 'feishu')`;
+	}
 }
 /**
 * GET /me/chats — cursor-paginated conversation list.
@@ -15803,6 +16149,7 @@ async function listMeChats(db, humanAgentId, organizationId, query) {
 	const filterUnreadOnly = query.filter === "unread";
 	const filterWatchingOnly = query.filter === "watching";
 	const engagementPredicate = ENGAGEMENT_VIEW_PREDICATE[query.engagement];
+	const sourcePredicate = query.source ? sourceFilterSql(query.source) : sql`TRUE`;
 	const cursorTsIso = cursor?.lastMessageAt ? cursor.lastMessageAt.toISOString() : null;
 	const cursorPredicate = !cursor ? sql`TRUE` : cursor.lastMessageAt === null ? sql`(c.last_message_at IS NULL AND c.id < ${cursor.chatId})` : sql`(c.last_message_at IS NULL
              OR c.last_message_at < ${cursorTsIso}::timestamptz
@@ -15819,7 +16166,7 @@ async function listMeChats(db, humanAgentId, organizationId, query) {
         WHERE chat_id = c.id AND access_mode = 'speaker') AS participant_count,
       cm.access_mode AS access_mode,
       COALESCE(cus.unread_mention_count, 0) AS unread_mention_count,
-      COALESCE(cus.engagement_status, ${ACTIVE}) AS engagement_status
+      COALESCE(cus.engagement_status, ${ACTIVE$1}) AS engagement_status
       FROM chats c
       JOIN chat_membership cm
         ON cm.chat_id = c.id AND cm.agent_id = ${humanAgentId}
@@ -15835,6 +16182,7 @@ async function listMeChats(db, humanAgentId, organizationId, query) {
        AND (${!filterUnreadOnly}::bool OR COALESCE(cus.unread_mention_count, 0) > 0)
        AND (${!filterWatchingOnly}::bool OR cm.access_mode = 'watcher')
        AND ${engagementPredicate}
+       AND ${sourcePredicate}
        AND ${cursorPredicate}
      ORDER BY c.last_message_at DESC NULLS LAST, c.id DESC
      LIMIT ${limit + 1}
@@ -15857,24 +16205,29 @@ async function listMeChats(db, humanAgentId, organizationId, query) {
 		agentId: chatMembership.agentId,
 		displayName: agents.displayName,
 		type: agents.type,
-		runtimeState: agentPresence.runtimeState
-	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).leftJoin(agentPresence, eq(agentPresence.agentId, chatMembership.agentId)).where(and(inArray(chatMembership.chatId, chatIds), eq(chatMembership.accessMode, "speaker")));
+		avatarColorToken: agents.avatarColorToken,
+		avatarImageUpdatedAt: agents.avatarImageUpdatedAt,
+		sessionState: agentChatSessions.state
+	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).leftJoin(agentChatSessions, and(eq(agentChatSessions.agentId, chatMembership.agentId), eq(agentChatSessions.chatId, chatMembership.chatId))).where(and(inArray(chatMembership.chatId, chatIds), eq(chatMembership.accessMode, "speaker")));
 	const participantsByChat = /* @__PURE__ */ new Map();
-	const workingByChat = /* @__PURE__ */ new Map();
+	const engagedByChat = /* @__PURE__ */ new Map();
 	for (const p of participantRows) {
 		const list = participantsByChat.get(p.chatId) ?? [];
 		list.push({
 			agentId: p.agentId,
 			displayName: p.displayName,
-			type: p.type
+			type: p.type,
+			avatarColorToken: p.avatarColorToken,
+			avatarImageUrl: agentAvatarImageUrl(p.agentId, p.avatarImageUpdatedAt)
 		});
 		participantsByChat.set(p.chatId, list);
-		if (p.runtimeState === "working") {
-			const working = workingByChat.get(p.chatId) ?? [];
-			working.push(p.agentId);
-			workingByChat.set(p.chatId, working);
+		if (p.sessionState === "active") {
+			const engaged = engagedByChat.get(p.chatId) ?? [];
+			engaged.push(p.agentId);
+			engagedByChat.set(p.chatId, engaged);
 		}
 	}
+	const liveActivityByChat = await deriveLiveActivity(db, chatIds);
 	const firstMessageRows = chatIds.length > 0 ? await db.selectDistinctOn([messages.chatId], {
 		chatId: messages.chatId,
 		content: messages.content
@@ -15902,13 +16255,98 @@ async function listMeChats(db, humanAgentId, organizationId, query) {
 				unreadMentionCount: r.unread_mention_count,
 				canReply: isSpeaker,
 				engagementStatus: r.engagement_status,
-				workingAgentIds: workingByChat.get(r.chat_id) ?? []
+				engagedAgentIds: engagedByChat.get(r.chat_id) ?? [],
+				liveActivity: liveActivityByChat.get(r.chat_id) ?? null
 			};
 		}),
 		nextCursor
 	};
 }
 /**
+* Per-chat live activity, derived from the most recent `session_events` row.
+*
+* Returns a chatId → LiveActivity map; chats with no activity (or where the
+* latest event is terminal / stale) are absent from the map (caller treats
+* absence as null).
+*/
+async function deriveLiveActivity(db, chatIds) {
+	if (chatIds.length === 0) return /* @__PURE__ */ new Map();
+	const chatIdInClause = sql.join(chatIds.map((id) => sql`${id}`), sql`, `);
+	const rows = (await db.execute(sql`
+    SELECT acs.agent_id        AS agent_id,
+           acs.chat_id         AS chat_id,
+           e.kind              AS kind,
+           e.payload           AS payload,
+           e.created_at        AS created_at
+      FROM agent_chat_sessions acs
+      CROSS JOIN LATERAL (
+        SELECT kind, payload, created_at, seq
+          FROM session_events se
+         WHERE se.agent_id = acs.agent_id
+           AND se.chat_id  = acs.chat_id
+         ORDER BY se.seq DESC
+         LIMIT 1
+      ) e
+     WHERE acs.chat_id IN (${chatIdInClause})
+       AND acs.state <> 'evicted'
+  `)).map((r) => ({
+		agent_id: r.agent_id,
+		chat_id: r.chat_id,
+		kind: r.kind,
+		payload: r.payload,
+		created_at: r.created_at
+	}));
+	const now = Date.now();
+	const byChat = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const activity = toLiveActivity(row);
+		if (!activity) continue;
+		const createdAtMs = new Date(row.created_at).getTime();
+		if (now - createdAtMs > 6e4) continue;
+		const existing = byChat.get(row.chat_id);
+		if (!existing || createdAtMs > existing.createdAtMs) byChat.set(row.chat_id, {
+			activity,
+			createdAtMs
+		});
+	}
+	const out = /* @__PURE__ */ new Map();
+	for (const [chatId, { activity }] of byChat) out.set(chatId, activity);
+	return out;
+}
+/**
+* Translate a `session_events` row into a `LiveActivity`, or null when the
+* kind is terminal (`turn_end` / `error`) or unrecognised. Pure & exported
+* for unit testing.
+*/
+function toLiveActivity(row) {
+	const startedAt = new Date(row.created_at).toISOString();
+	switch (row.kind) {
+		case "tool_call": {
+			const payload = row.payload ?? {};
+			const label = typeof payload.name === "string" && payload.name.length > 0 ? payload.name : "Tool";
+			return {
+				agentId: row.agent_id,
+				kind: "tool_call",
+				label,
+				startedAt
+			};
+		}
+		case "thinking": return {
+			agentId: row.agent_id,
+			kind: "thinking",
+			label: "Thinking",
+			startedAt
+		};
+		case "assistant_text": return {
+			agentId: row.agent_id,
+			kind: "assistant_text",
+			label: "Writing",
+			startedAt
+		};
+		default: return null;
+	}
+}
+/**
 * Title resolution priority:
 *
 *   1. `chat.topic` (manual, set via `PATCH /chats/:chatId`)
@@ -16028,6 +16466,66 @@ async function leaveMeChat(db, chatId, humanAgentId) {
 	return result;
 }
 /**
+* Used by future bell-badge / list-pill counts. The partial index
+* `idx_user_state_unread WHERE unread_mention_count > 0` bounds the
+* driving scan; we then join `chat_membership` + `chats` so the badge
+* stays consistent with `listMeChats`.
+*
+* Why the joins (not just a single-table count): per §11.4 a user's
+* `chat_user_state` row is **preserved on detach** so read state
+* survives a leave/rejoin cycle. Without the membership join, any
+* preserved row with `unread_mention_count > 0` would keep
+* contributing to the badge even though the chat no longer appears in
+* the list. The `chats` join applies the same org-scoping +
+* `parent_chat_id IS NULL` filter as `listMeChats` so the two counts
+* cannot drift in the cross-org pollution or nested-chat cases either.
+*
+* Engagement parity: deleted chats are excluded from `listMeChats`
+* (any `engagement` view), so the badge must exclude them too — otherwise
+* the user sees an unread red dot for a chat they've removed from view.
+*/
+/**
+* Per-source aggregate for the conversation-list tag bar.
+*
+* Returns one row per source the caller has at least one chat for, plus an
+* always-present `manual` entry (zero counts when there are no manual chats —
+* the workspace UI uses `manual` as its default tab and must render it even
+* when empty).
+*
+* Filtering matches `listMeChats` for the corresponding tab so the badges
+* cannot drift from the list: same membership join, same `parent_chat_id IS
+* NULL` and `organization_id` scopes, same engagement view, same
+* `chat_user_state.unread_mention_count` source.
+*/
+async function listMeChatSourceCounts(db, humanAgentId, organizationId, query) {
+	const engagementPredicate = ENGAGEMENT_VIEW_PREDICATE[query.engagement];
+	const rows = await db.execute(sql`
+    SELECT
+      ${chatSourceSqlExpression} AS source,
+      count(*)::int AS chat_count,
+      count(*) FILTER (WHERE COALESCE(cus.unread_mention_count, 0) > 0)::int AS unread_chat_count
+      FROM chats c
+      JOIN chat_membership cm
+        ON cm.chat_id = c.id AND cm.agent_id = ${humanAgentId}
+      LEFT JOIN chat_user_state cus
+        ON cus.chat_id = c.id AND cus.agent_id = ${humanAgentId}
+     WHERE c.parent_chat_id IS NULL
+       AND c.organization_id = ${organizationId}
+       AND ${engagementPredicate}
+     GROUP BY 1
+  `);
+	const counts = {};
+	for (const row of rows) counts[row.source] = {
+		chatCount: Number(row.chat_count),
+		unreadChatCount: Number(row.unread_chat_count)
+	};
+	if (!counts.manual) counts.manual = {
+		chatCount: 0,
+		unreadChatCount: 0
+	};
+	return { counts };
+}
+/**
 * Class C — resource-scoped chat routes. Mounted at
 * `/api/v1/chats/:chatId/...`. The chat's `organizationId` locates its
 * org; `requireChatAccess` resolves the caller's membership in that org
@@ -16048,7 +16546,9 @@ async function chatRoutes(app) {
 		const agentRows = participantAgentIds.length > 0 ? await app.db.select({
 			agentId: agents.uuid,
 			displayName: agents.displayName,
-			type: agents.type
+			type: agents.type,
+			avatarColorToken: agents.avatarColorToken,
+			avatarImageUpdatedAt: agents.avatarImageUpdatedAt
 		}).from(agents).where(inArray(agents.uuid, participantAgentIds)) : [];
 		const agentMeta = new Map(agentRows.map((a) => [a.agentId, a]));
 		const participantsForTitle = participants.map((p) => {
@@ -16056,7 +16556,9 @@ async function chatRoutes(app) {
 			return {
 				agentId: p.agentId,
 				displayName: meta?.displayName ?? p.agentId,
-				type: meta?.type ?? "unknown"
+				type: meta?.type ?? "unknown",
+				avatarColorToken: meta?.avatarColorToken ?? null,
+				avatarImageUrl: agentAvatarImageUrl(p.agentId, meta?.avatarImageUpdatedAt ?? null)
 			};
 		});
 		const title = resolveChatTitle(chat.topic, firstMessagePreview, participantsForTitle, scope.humanAgentId);
@@ -16535,6 +17037,9 @@ const WINDOW_DAYS = {
 	"7d": 7,
 	"30d": 30
 };
+function contextTreeSnapshotWindowDays(window) {
+	return WINDOW_DAYS[window];
+}
 const snapshotCache = /* @__PURE__ */ new Map();
 const remoteSyncPromises = /* @__PURE__ */ new Map();
 const remoteLastSyncedAt = /* @__PURE__ */ new Map();
@@ -16578,6 +17083,7 @@ async function getContextTreeSnapshot(binding, window = CONTEXT_TREE_SNAPSHOT_WI
 			snapshotStatus: statusWarning?.stale ? "stale" : "active",
 			contextStatus: contextStatus(statusWarning),
 			summary,
+			usage: emptyUsageSummary(window),
 			updates,
 			nodes: nodesWithGhosts,
 			edges: tree.edges,
@@ -16832,6 +17338,13 @@ function withSnapshotStatus(snapshot, syncedAt, warning) {
 		contextStatus: warning ? contextStatus(warning) : snapshot.contextStatus
 	};
 }
+function emptyUsageSummary(window) {
+	return {
+		windowDays: WINDOW_DAYS[window],
+		agentCount: 0,
+		usageCount: 0
+	};
+}
 function isSafeBranchName(branch) {
 	if (branch.startsWith("-")) return false;
 	if (branch.includes("..") || branch.includes("@{") || branch.includes("\\")) return false;
@@ -16862,6 +17375,7 @@ function unavailableSnapshot(repo, branch, detail) {
 			removedCount: 0,
 			changedNodeCount: 0
 		},
+		usage: emptyUsageSummary(CONTEXT_TREE_SNAPSHOT_WINDOWS.SEVEN_DAYS),
 		updates: [],
 		nodes: [],
 		edges: [],
@@ -17437,11 +17951,16 @@ async function contextTreeSnapshotRoutes(app) {
 		const orgId = await resolveUserPrimaryOrgId(app.db, userId);
 		const binding = orgId ? await getOrgContextTree(app.db, orgId) : {};
 		const githubToken = contextTreeGithubTokenForRepo(binding.repo, app.config.contextTreeSync);
+		const window = query.window ?? "7d";
 		const snapshot = await getContextTreeSnapshot({
 			...binding,
 			githubToken
-		}, query.window ?? "7d");
-		return contextTreeSnapshotSchema.parse(snapshot);
+		}, window);
+		const usage = orgId ? await summarizeContextTreeUsage(app.db, orgId, contextTreeSnapshotWindowDays(window)) : snapshot.usage;
+		return contextTreeSnapshotSchema.parse({
+			...snapshot,
+			usage
+		});
 	});
 }
 function contextTreeGithubTokenForRepo(repo, syncConfig) {
@@ -17570,7 +18089,7 @@ async function healthzRoutes(app) {
 * `api/orgs/invitations.ts` (Class B, admin-gated).
 */
 async function publicInvitationRoutes(app) {
-	const { previewInvitation } = await import("./invitation-C299fxkP-CZgGbsN_.mjs");
+	const { previewInvitation } = await import("./invitation-CNv7gfFF-DOFZ75wb.mjs");
 	app.get("/:token/preview", async (request, reply) => {
 		if (!request.params.token) throw new UnauthorizedError("Token required");
 		const preview = await previewInvitation(app.db, request.params.token);
@@ -17640,7 +18159,8 @@ async function meRoutes(app) {
 			username: users.username,
 			displayName: users.displayName,
 			avatarUrl: users.avatarUrl,
-			onboardingDismissedAt: users.onboardingDismissedAt
+			onboardingDismissedAt: users.onboardingDismissedAt,
+			onboardingCompletedAt: users.onboardingCompletedAt
 		}).from(users).where(eq(users.id, userId)).limit(1);
 		const memberships = await listActiveMemberships(app.db, userId);
 		const defaultMembership = pickDefaultMembership(memberships.map((m) => ({
@@ -17648,6 +18168,7 @@ async function meRoutes(app) {
 			createdAt: m.createdAt
 		})));
 		const defaultOrgId = defaultMembership ? memberships.find((m) => m.memberId === defaultMembership.id)?.organizationId ?? null : null;
+		const memberCounts = await countActiveMembersByOrgs(app.db, memberships.map((mb) => mb.organizationId));
 		let inviteUrl = null;
 		if (defaultOrgId) {
 			if (memberships.find((m) => m.organizationId === defaultOrgId)?.role === "admin") {
@@ -17664,11 +18185,13 @@ async function meRoutes(app) {
 				organizationId: mb.organizationId,
 				organizationName: mb.orgDisplayName,
 				role: mb.role,
-				agentId: mb.agentId
+				agentId: mb.agentId,
+				orgHasOtherMembers: (memberCounts.get(mb.organizationId) ?? 1) > 1
 			})),
 			onboarding: {
 				step: onboardingStep,
-				dismissedAt: user?.onboardingDismissedAt ? user.onboardingDismissedAt.toISOString() : null
+				dismissedAt: user?.onboardingDismissedAt ? user.onboardingDismissedAt.toISOString() : null,
+				completedAt: user?.onboardingCompletedAt ? user.onboardingCompletedAt.toISOString() : null
 			},
 			inviteUrl
 		};
@@ -17694,6 +18217,25 @@ async function meRoutes(app) {
 		return reply.status(200).send({ dismissedAt: u?.onboardingDismissedAt ? u.onboardingDismissedAt.toISOString() : null });
 	});
 	/**
+	* POST /me/onboarding-completed — stamp the terminal-state column when
+	* the user walks Step 3 to success (admin Continue, invitee Confirm /
+	* Continue). Distinct from PATCH /me/onboarding { dismissed: true },
+	* which only hides the stepper UI. Once stamped, the web sidebar drops
+	* the Settings → Onboarding entry point and /settings/onboarding
+	* redirects, so the wizard cannot re-enter.
+	*
+	* Idempotent: only writes when the column is still NULL — re-calling on
+	* an already-completed user is a no-op rather than resetting the stamp.
+	*/
+	app.post("/me/onboarding-completed", async (request, reply) => {
+		const { userId } = requireUser(request);
+		if ((await app.db.update(users).set({ onboardingCompletedAt: /* @__PURE__ */ new Date() }).where(and(eq(users.id, userId), isNull(users.onboardingCompletedAt))).returning({ id: users.id })).length > 0) app.log.info({
+			event: "onboarding.completed",
+			userId
+		}, "onboarding funnel: setup completed");
+		return reply.status(200).send({ ok: true });
+	});
+	/**
 	* POST /me/onboarding/events — web-side onboarding funnel reporter.
 	* Server-side milestones (`team_created` at OAuth, `dismissed` on PATCH)
 	* are emitted directly; this endpoint surfaces the web-driven ones into
@@ -17836,7 +18378,7 @@ async function meRoutes(app) {
 	*/
 	app.get("/me/pinned-agents", async (request) => {
 		const { userId } = requireUser(request);
-		const { listMyPinnedAgents } = await import("./client-DNiLcPEq-db3YS57z.mjs");
+		const { listMyPinnedAgents } = await import("./client-gSnsRu5W-v_mC1sRY.mjs");
 		return listMyPinnedAgents(app.db, { userId });
 	});
 	/**
@@ -17966,6 +18508,80 @@ async function inferOnboardingStep(app, userId) {
 	if (!hasAgent) return "create_agent";
 	return "completed";
 }
+const MAX_DOC_BYTES = 5 * 1024 * 1024;
+async function getMeDocPreview(input) {
+	const workspaceRootReal = await realpathOrNotFound(join(input.workspacesRoot ?? join(DEFAULT_DATA_DIR$1, "workspaces"), input.agentName, input.chatId));
+	const candidate = resolve(workspaceRootReal, join(input.basePath ?? "", input.path));
+	if (extname(assertInsideWorkspace(workspaceRootReal, candidate)).toLowerCase() !== ".md") throw new ForbiddenError("Document preview only supports markdown files in the agent workspace");
+	let fileStat;
+	try {
+		fileStat = await stat(candidate);
+	} catch {
+		throw new NotFoundError("Document not found");
+	}
+	if (!fileStat.isFile()) throw new NotFoundError("Document not found");
+	if (fileStat.size > MAX_DOC_BYTES) throw new AppError(413, "Document is larger than the 5MB preview limit");
+	const fileReal = await realpath(candidate);
+	const normalizedPath = assertInsideWorkspace(workspaceRootReal, fileReal);
+	const refPath = normalizeRefPath(input.path);
+	const normalizedBasePath = input.basePath ? normalizeRefPath(input.basePath) : void 0;
+	return {
+		ref: {
+			type: "workspace",
+			chatId: input.chatId,
+			agentId: input.agentId,
+			...normalizedBasePath ? { basePath: normalizedBasePath } : {},
+			path: refPath
+		},
+		path: normalizedPath,
+		content: await readFile(fileReal, "utf8")
+	};
+}
+async function realpathOrNotFound(path) {
+	try {
+		return await realpath(path);
+	} catch {
+		throw new NotFoundError("Document not found");
+	}
+}
+function assertInsideWorkspace(workspaceRoot, target) {
+	const rel = relative(workspaceRoot, target);
+	if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new ForbiddenError("Document path must stay inside the agent workspace");
+	return rel.split(sep).join("/");
+}
+function normalizeRefPath(path) {
+	const parts = [];
+	for (const part of path.split(/[\\/]/)) {
+		if (!part || part === ".") continue;
+		if (part === "..") {
+			if (parts.length === 0) throw new ForbiddenError("Document path must stay inside the agent workspace");
+			parts.pop();
+			continue;
+		}
+		parts.push(part);
+	}
+	if (parts.length === 0) throw new ForbiddenError("Document path must name a markdown file");
+	return parts.join("/");
+}
+async function meDocsRoutes(app, options = {}) {
+	app.get("/chats/:chatId/docs/preview", async (request) => {
+		await requireChatAccess(request, app.db);
+		const query = getMeDocSchema.parse(request.query);
+		const [participant] = await app.db.select({ agentId: chatMembership.agentId }).from(chatMembership).where(and(eq(chatMembership.chatId, request.params.chatId), eq(chatMembership.agentId, query.agentId), eq(chatMembership.accessMode, "speaker"))).limit(1);
+		if (!participant) throw new NotFoundError("Document not found");
+		const [agent] = await app.db.select({ name: agents.name }).from(agents).where(eq(agents.uuid, query.agentId)).limit(1);
+		if (!agent?.name) throw new NotFoundError("Document not found");
+		const preview = await getMeDocPreview({
+			chatId: request.params.chatId,
+			agentId: query.agentId,
+			agentName: agent.name,
+			basePath: query.basePath,
+			path: query.path,
+			workspacesRoot: options.workspacesRoot
+		});
+		return getMeDocResponseSchema.parse(preview);
+	});
+}
 /**
 * Resolve the caller's active membership in `:orgId` (from the URL) and
 * return the full `OrgScope`. The type signature requires
@@ -18146,7 +18762,7 @@ async function orgAgentRoutes(app) {
 		const { type } = listAgentsFilterSchema.parse(request.query);
 		const result = await listAgentsForMember(app.db, scope, query.limit, query.cursor, type);
 		return {
-			items: result.items.map((a) => ({
+			items: result.items.map(({ avatarImageUpdatedAt, ...a }) => ({
 				...a,
 				managerId: a.managerId ?? null,
 				presenceStatus: a.presenceStatus ?? "offline",
@@ -18155,7 +18771,8 @@ async function orgAgentRoutes(app) {
 				clientId: a.clientId ?? null,
 				runtimeType: a.runtimeType ?? null,
 				runtimeState: a.runtimeState ?? null,
-				activeSessions: a.activeSessions ?? null
+				activeSessions: a.activeSessions ?? null,
+				avatarImageUrl: agentAvatarImageUrl(a.uuid, avatarImageUpdatedAt)
 			})),
 			nextCursor: result.nextCursor
 		};
@@ -18171,7 +18788,7 @@ async function orgAgentRoutes(app) {
 		const query = paginationQuerySchema.parse(request.query);
 		const result = await listAgentsForAdmin(app.db, scope, query.limit, query.cursor);
 		return {
-			items: result.items.map((a) => ({
+			items: result.items.map(({ avatarImageUpdatedAt, ...a }) => ({
 				...a,
 				managerId: a.managerId ?? null,
 				presenceStatus: a.presenceStatus ?? "offline",
@@ -18180,7 +18797,8 @@ async function orgAgentRoutes(app) {
 				clientId: a.clientId ?? null,
 				runtimeType: a.runtimeType ?? null,
 				runtimeState: a.runtimeState ?? null,
-				activeSessions: a.activeSessions ?? null
+				activeSessions: a.activeSessions ?? null,
+				avatarImageUrl: agentAvatarImageUrl(a.uuid, avatarImageUpdatedAt)
 			})),
 			nextCursor: result.nextCursor
 		};
@@ -18273,6 +18891,17 @@ async function orgChatRoutes(app) {
 		return listMeChats(app.db, scope.humanAgentId, scope.organizationId, query);
 	});
 	/**
+	* GET /orgs/:orgId/chats/source-counts — per-source aggregate powering the
+	* conversation-list tag bar (Manual / GitHub PR / GitHub Issue / Feishu).
+	* Returns counts only for sources the caller has chats in, plus an
+	* always-present `manual` entry. Same engagement view filter as the list.
+	*/
+	app.get("/source-counts", async (request) => {
+		const scope = await requireOrgMembership(request, app.db);
+		const query = listMeChatSourceCountsQuerySchema.parse(request.query);
+		return listMeChatSourceCounts(app.db, scope.humanAgentId, scope.organizationId, query);
+	});
+	/**
 	* POST /orgs/:orgId/chats — create a new chat. The :orgId path param
 	* makes the org explicit; visibility of every requested participant is
 	* verified before the service layer touches the DB.
@@ -18326,11 +18955,16 @@ async function orgContextTreeSnapshotRoutes(app) {
 		const scope = await requireOrgMembership(request, app.db);
 		const binding = await getOrgContextTree(app.db, scope.organizationId);
 		const githubToken = contextTreeGithubTokenForRepo(binding.repo, app.config.contextTreeSync);
+		const window = query.window ?? "7d";
 		const snapshot = await getContextTreeSnapshot({
 			...binding,
 			githubToken
-		}, query.window ?? "7d");
-		return contextTreeSnapshotSchema.parse(snapshot);
+		}, window);
+		const usage = await summarizeContextTreeUsage(app.db, scope.organizationId, contextTreeSnapshotWindowDays(window));
+		return contextTreeSnapshotSchema.parse({
+			...snapshot,
+			usage
+		});
 	});
 }
 function orgIdParam(params) {
@@ -18757,6 +19391,12 @@ function orgWsRoutes(notifier, jwtSecret) {
 			...payload
 		});
 	});
+	notifier.onSessionEvent((payload) => {
+		broadcastOrgScoped({
+			type: "session:event",
+			...payload
+		});
+	});
 	notifier.onChatMessage(({ chatId }) => {
 		dispatchChatMessage(chatId);
 	});
@@ -18965,6 +19605,64 @@ const githubEntityChatMappings = pgTable("github_entity_chat_mappings", {
 	table.entityType,
 	table.entityKey
 ] }), index("idx_github_entity_chat_mappings_chat").on(table.chatId)]);
+/**
+* Auto-archive chats when one of their bound pull requests is merged.
+*
+* Trigger: GitHub `pull_request.closed` webhook with `merged === true`. The
+* webhook handler calls this service on a bypass branch — the normalize /
+* audience / deliver pipeline is unaffected (PR closed events still drop in
+* Stage 1).
+*
+* Algorithm: a merged PR flips every chat bound to it into the user's
+* archived view, with no inspection of sibling PR state. Multi-PR chats can
+* be temporarily archived while siblings are still open; any later activity
+* on those siblings produces a normal delivery message, which the existing
+* chat-projection auto-revives back to `active`. This trades perfect timing
+* for zero local state, no GitHub API calls, and no schema changes.
+*
+* Per-user safety: writes use an UPSERT guarded with
+* `setWhere = engagement_status = 'active'`, so only the implicit-active or
+* explicitly-active rows flip. User-manually `deleted` and already-`archived`
+* rows are left alone. Idempotent under GitHub webhook retries.
+*/
+const { ACTIVE, ARCHIVED } = CHAT_ENGAGEMENT_STATUSES;
+async function archiveChatsForMergedPr(db, input) {
+	if (!input.repoFullName || !Number.isFinite(input.prNumber) || input.prNumber <= 0) return {
+		chats: 0,
+		rowsConsidered: 0
+	};
+	const entityKey = `${input.repoFullName}#${input.prNumber}`;
+	const rows = await db.select({
+		chatId: githubEntityChatMappings.chatId,
+		humanAgentId: githubEntityChatMappings.humanAgentId
+	}).from(githubEntityChatMappings).where(and(eq(githubEntityChatMappings.organizationId, input.organizationId), eq(githubEntityChatMappings.entityType, "pull_request"), eq(githubEntityChatMappings.entityKey, entityKey)));
+	if (rows.length === 0) return {
+		chats: 0,
+		rowsConsidered: 0
+	};
+	const seen = /* @__PURE__ */ new Set();
+	const targets = [];
+	for (const row of rows) {
+		const key = `${row.chatId}|${row.humanAgentId}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		targets.push(row);
+	}
+	for (const { chatId, humanAgentId } of targets) await db.insert(chatUserState).values({
+		chatId,
+		agentId: humanAgentId,
+		unreadMentionCount: 0,
+		engagementStatus: ARCHIVED
+	}).onConflictDoUpdate({
+		target: [chatUserState.chatId, chatUserState.agentId],
+		set: { engagementStatus: ARCHIVED },
+		setWhere: eq(chatUserState.engagementStatus, ACTIVE)
+	});
+	return {
+		chats: new Set(targets.map((t) => t.chatId)).size,
+		rowsConsidered: targets.length
+	};
+}
 function evaluateDelegateTarget(target, sourceOrgId) {
 	if (!target) return "not_found";
 	if (target.organizationId !== sourceOrgId) return "cross_org";
@@ -20110,6 +20808,28 @@ async function githubAppWebhookRoutes(app) {
 		};
 		const deliveryHeader = request.headers["x-github-delivery"];
 		const deliveryId = typeof deliveryHeader === "string" && deliveryHeader.length > 0 ? deliveryHeader : null;
+		if (eventType === "pull_request" && isRecord(payload) && payload.action === "closed") {
+			const pr = isRecord(payload.pull_request) ? payload.pull_request : null;
+			const repoFullName = readString$1((isRecord(payload.repository) ? payload.repository : null)?.full_name);
+			const prNumber = readNumber$1(pr?.number);
+			if (pr?.merged === true && repoFullName && prNumber !== null) try {
+				const stats = await archiveChatsForMergedPr(app.db, {
+					organizationId: installation.hubOrganizationId,
+					repoFullName,
+					prNumber
+				});
+				log$1.info({
+					entityKey: `${repoFullName}#${prNumber}`,
+					...stats
+				}, "auto-archived chats on PR merge");
+			} catch (err) {
+				log$1.error({
+					err,
+					repoFullName,
+					prNumber
+				}, "failed to auto-archive chats on PR merge");
+			}
+		}
 		const event = normalizeGithubEvent(eventType, payload, source, deliveryId);
 		if (!event) {
 			log$1.debug({
@@ -21710,12 +22430,14 @@ async function buildApp(config) {
 		await api.register(githubOauthRoutes, { prefix: "/auth/github" });
 		await api.register(publicInvitationRoutes, { prefix: "/invitations" });
 		await api.register(bootstrapConfigRoutes, { prefix: "/bootstrap" });
+		await api.register(publicAgentAvatarRoutes, { prefix: "/agents" });
 		await api.register(userScope("contextTreeScope", async (scope) => {
 			await scope.register(contextTreeInfoRoutes);
 			await scope.register(contextTreeSnapshotRoutes);
 		}), { prefix: "/context-tree" });
 		await api.register(userScope("meRoutesScope", async (scope) => {
 			await scope.register(meRoutes);
+			await scope.register(meDocsRoutes, { workspacesRoot: config.workspace.root });
 		}), { prefix: "" });
 		await api.register(userScope("orgsScope", async (scope) => {
 			await scope.register(orgIdentityRoutes);
@@ -22147,7 +22869,7 @@ const declineUpdate = async () => false;
 * relaunch picks up the new binary.
 *
 * `managed=false` means the process is running standalone (e.g. manual
-* `client start`, `client connect --no-service`, CI without a supervisor).
+* `client start`, `connect <token> --no-service`, CI without a supervisor).
 * Exiting in that mode would leave the client offline until an operator
 * noticed — so the callback instead prints a restart hint, returns
 * `{ installed: true }`, and the UpdateManager stops retrying until the