@agent-team-foundation/first-tree-hub 0.12.4 → 0.12.6

package/dist/{saas-connect-S71rG182.mjs → saas-connect-RCN8zL5e.mjs}

@@ -1,11 +1,11 @@
 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-C_K2CKXC.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-BCZC1ki6.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 runtimeStateMessageSchema, B as isReservedAgentName$1, C as createChatSchema, D as defaultRuntimeConfigPayload, E as createOrgFromMeSchema, F as inboxAckFrameSchema, G as notificationQuerySchema, H as listMeChatsQuerySchema, I as inboxDeliverFrameSchema$1, J as patchOnboardingSchema, K as onboardingEventSchema, L as inboxPollQuerySchema, M as githubDevCallbackQuerySchema, N as githubStartQuerySchema, O as delegateFeishuUserSchema, P as imageInlineContentSchema, Q as refreshTokenSchema, R as isOrgSettingNamespace, S as createAgentSchema, T as createMemberSchema, U as loginSchema, V as joinByInvitationSchema, W as messageSourceSchema$1, Z as rebindAgentSchema, _ as clientRegisterSchema, _t as updateMemberSchema, a as AGENT_VISIBILITY, at as sessionCompletionMessageSchema, b as createAdapterConfigSchema, c as ORG_SETTINGS_NAMESPACES$1, ct as sessionReconcileRequestSchema, d as addParticipantSchema, dt as submitQuestionAnswerSchema, et as safeRedirectPath, f as agentBindRequestSchema, ft as updateAdapterConfigSchema, gt as updateClientCapabilitiesSchema, h as agentTypeSchema$1, ht as updateChatSchema, i as AGENT_STATUSES, it as sendToAgentSchema, j as githubCallbackQuerySchema, k as dryRunAgentRuntimeConfigSchema, l as WS_AUTH_FRAME_TIMEOUT_MS, lt as sessionStateMessageSchema, m as agentRuntimeConfigPayloadSchema$1, mt as updateAgentSchema, n as AGENT_NAME_REGEX$1, nt as selfServiceFeishuBotSchema, ot as sessionEventMessageSchema, p as agentPinnedMessageSchema$1, pt as updateAgentRuntimeConfigSchema, q as paginationQuerySchema, r as AGENT_SELECTOR_HEADER$1, rt as sendMessageSchema, s as MENTION_REGEX, st as sessionEventSchema$1, t as AGENT_BIND_REJECT_REASONS, u as addMeChatParticipantsSchema, ut as stripCode, v as connectTokenExchangeSchema, vt as updateOrganizationSchema, w as createMeChatSchema, x as createAdapterMappingSchema, y as contextTreeSnapshotSchema, yt as wsAuthFrameSchema, z as isRedactedEnvValue } from "./dist-CMhywpXB.mjs";
+import { A as delegateFeishuUserSchema, B as inboxPollQuerySchema, C as createAgentSchema, D as createOrgFromMeSchema, E as createMemberSchema, F as githubDevCallbackQuerySchema, G as listMeChatsQuerySchema, H as isRedactedEnvValue, I as githubStartQuerySchema, J as notificationQuerySchema, K as loginSchema, L as imageInlineContentSchema, N as githubAppInstallationClaimBodySchema, P as githubCallbackQuerySchema, R as inboxAckFrameSchema, S as createAdapterMappingSchema, St as wsAuthFrameSchema, T as createMeChatSchema, U as isReservedAgentName$1, V as isOrgSettingNamespace, W as joinByInvitationSchema, X as paginationQuerySchema, Y as onboardingEventSchema, Z as patchOnboardingSchema, _t as updateAgentSchema, a as AGENT_VISIBILITY, at as selfServiceFeishuBotSchema, b as contextTreeSnapshotSchema, bt as updateMemberSchema, c as ORG_SETTINGS_NAMESPACES$1, ct as sessionCompletionMessageSchema, d as addParticipantSchema, dt as sessionReconcileRequestSchema, et as rebindAgentSchema, f as agentBindRequestSchema, ft as sessionStateMessageSchema, g as chatMetadataSchema$1, gt as updateAgentRuntimeConfigSchema, h as agentTypeSchema$1, ht as updateAdapterConfigSchema, i as AGENT_STATUSES, j as dryRunAgentRuntimeConfigSchema, k as defaultRuntimeConfigPayload, l as WS_AUTH_FRAME_TIMEOUT_MS, lt as sessionEventMessageSchema, m as agentRuntimeConfigPayloadSchema$1, mt as submitQuestionAnswerSchema, n as AGENT_NAME_REGEX$1, nt as runtimeStateMessageSchema, ot as sendMessageSchema, p as agentPinnedMessageSchema$1, pt as stripCode, q as messageSourceSchema$1, r as AGENT_SELECTOR_HEADER$1, rt as safeRedirectPath, s as MENTION_REGEX, st as sendToAgentSchema, t as AGENT_BIND_REJECT_REASONS, tt as refreshTokenSchema, u as addMeChatParticipantsSchema, ut as sessionEventSchema$1, v as clientRegisterSchema, vt as updateChatSchema, w as createChatSchema, x as createAdapterConfigSchema, xt as updateOrganizationSchema, y as connectTokenExchangeSchema, yt as updateClientCapabilitiesSchema, z as inboxDeliverFrameSchema$1 } from "./dist-xP6NpdMp.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 { n as init_esm, r as trace, t as esm_exports } from "./esm-iadMkGbV.mjs";
-import { $ as pendingQuestions, A as heartbeatClient, B as listAgentsWithRuntime, C as findOrCreateDirectChat, D as getClient, E as getChatDetail, F as joinChat, G as listClientsForOrgAdmin, H as listChats, I as leaveAsParticipant, J as markStaleAgents, K as listMessages, L as leaveChat, M as inboxEntries, N as invalidateChatAudience, O as getOnlineCount, P as joinAsParticipant, Q as notifyRecipients, R as listActiveAgentsPinnedToClient, S as ensureParticipant$1, T as getCachedAudience, U as listChatsForMember, V as listChatParticipantsWithNames, W as listClients, X as members, Y as markSupersededByChat, Z as messages, _ as createNotifier, _t as updateClientCapabilities, a as agents, at as removeParticipant, b as editMessage, c as bindAgent, ct as retireClient, d as chats, dt as serverInstances, et as recomputeChatWatchers, f as claimClient, ft as setOffline, g as createChat, gt as unbindAgent, h as clients, ht as touchAgent, i as agentVisibilityCondition, it as registerClient, j as heartbeatInstance, k as getPresence, l as chatParticipants, lt as sendMessage, m as cleanupStalePresence, mt as submitAnswer, n as agentChatSessions, nt as recomputeWatchersForMember, o as assertClientOwner, ot as resetActivity, p as cleanupStaleClients, pt as setRuntimeState, r as agentPresence, rt as registerChatMessageDispatcher, s as assertParticipant, st as resolveChatMembership, t as addParticipant, tt as recomputeWatchersForAgent, u as chatSubscriptions, ut as sendToAgent$1, v as deriveAuthState, vt as upsertSessionState, w as getActivityOverview, x as ensureCanJoin, y as disconnectClient, z as listAgentsManagedByUser } from "./client-D1TDiik_-NV_lkhfI.mjs";
+import { $ as messages, A as getOnlineCount, B as listActiveAgentsPinnedToClient, C as ensureCanJoin, D as getCachedAudience, E as getActivityOverview, F as invalidateChatAudience, G as listChatsForMember, H as listAgentsWithRuntime, I as joinAsParticipant, J as listMessages, K as listClients, L as joinChat, M as heartbeatClient, N as heartbeatInstance, O as getChatDetail, P as inboxEntries, Q as members, R as leaveAsParticipant, S as editMessage, T as findOrCreateDirectChat, U as listChatParticipantsWithNames, V as listAgentsManagedByUser, W as listChats, X as markStaleAgents, Z as markSupersededByChat, _ as clients, _t as touchAgent, a as agentVisibilityCondition, at as registerChatMessageDispatcher, b as deriveAuthState, bt as upsertSessionState, c as assertParticipant, ct as resetActivity, d as chatParticipants, dt as sendMessage, et as notifyRecipients, f as chatSubscriptions, ft as sendToAgent$1, g as cleanupStalePresence, gt as submitAnswer, h as cleanupStaleClients, ht as setRuntimeState, i as agentPresence, it as recomputeWatchersForMember, j as getPresence, k as getClient, l as bindAgent, lt as resolveChatMembership, m as claimClient, mt as setOffline, n as addParticipant, nt as recomputeChatWatchers, o as agents, ot as registerClient, p as chats, pt as serverInstances, q as listClientsForOrgAdmin, r as agentChatSessions, rt as recomputeWatchersForAgent, s as assertClientOwner, st as removeParticipant, t as addChatParticipants, tt as pendingQuestions, u as changeChatType, ut as retireClient, v as createChat, vt as unbindAgent, w as ensureParticipant$1, x as disconnectClient, y as createNotifier, yt as updateClientCapabilities, z as leaveChat } from "./client-B89AKi3Q-DAyGdQSq.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 { createRequire } from "node:module";
 import { ZodError, z } from "zod";
@@ -29,8 +29,8 @@ import { and, asc, count, desc, eq, gt, gte, inArray, isNotNull, isNull, lt, ne,
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import { migrate } from "drizzle-orm/postgres-js/migrator";
-import { boolean, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique, uniqueIndex } from "drizzle-orm/pg-core";
-import { SignJWT, jwtVerify } from "jose";
+import { bigint, boolean, check, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique, uniqueIndex } from "drizzle-orm/pg-core";
+import { SignJWT, importPKCS8, jwtVerify } from "jose";
 import cors from "@fastify/cors";
 import rateLimit from "@fastify/rate-limit";
 import fastifyStatic from "@fastify/static";
@@ -730,6 +730,30 @@ z.object({
 	expiresIn: z.number(),
 	command: z.string()
 });
+const githubEntityTypeSchema = z.enum([
+	"issue",
+	"pull_request",
+	"discussion",
+	"commit"
+]);
+const githubChatMetadataSchema = z.object({
+	source: z.literal("github"),
+	entityType: githubEntityTypeSchema,
+	entityKey: z.string().min(1),
+	entityUrl: z.string().url().optional()
+});
+const feishuChatMetadataSchema = z.object({
+	source: z.literal("feishu"),
+	externalChannelId: z.string().min(1)
+});
+const chatMetadataSchema = z.discriminatedUnion("source", [githubChatMetadataSchema, feishuChatMetadataSchema]);
+/**
+* `createChat` callers may not set metadata at all (admin-created group chats,
+* me-chats, …), so the input schema accepts either an empty object or one of
+* the typed variants. The empty `{}` arm is `.strict()` so a caller cannot
+* sneak through `{ source: "github" }` without the required fields.
+*/
+const optionalChatMetadataSchema = z.union([z.object({}).strict(), chatMetadataSchema]);
 const chatTypeSchema = z.enum([
 	"direct",
 	"group",
@@ -739,7 +763,7 @@ z.object({
 	type: chatTypeSchema,
 	topic: z.string().max(500).optional(),
 	participantIds: z.array(z.string()).min(1),
-	metadata: z.record(z.string(), z.unknown()).optional()
+	metadata: optionalChatMetadataSchema.optional()
 });
 const chatParticipantSchema = z.object({
 	agentId: z.string(),
@@ -767,10 +791,7 @@ z.object({
 	firstMessagePreview: z.string().nullable()
 });
 z.object({ topic: z.string().trim().max(500).nullable() });
-z.object({
-	agentId: z.string().min(1),
-	mode: z.enum(["full", "mention_only"]).default("full")
-});
+z.object({ agentId: z.string().min(1) });
 z.object({ agentId: z.string().min(1) });
 const clientStatusSchema = z.enum(["connected", "disconnected"]);
 /**
@@ -954,6 +975,45 @@ z.object({
 	edges: z.array(contextTreeEdgeSchema),
 	changes: z.array(contextTreeChangeSchema)
 });
+const githubAccountTypeSchema = z.enum(["User", "Organization"]);
+const githubPermissionLevelSchema = z.enum([
+	"read",
+	"write",
+	"admin"
+]);
+/**
+* `installation.permissions` blob from GitHub. Key is the permission name
+* (`contents`, `pull_requests`, `issues`, `members`, …) — we keep this as a
+* free-form `z.record` because GitHub adds new permission keys over time
+* and we don't want a Hub-side `app_id` upgrade just to surface a new key
+* in the integrations panel.
+*/
+const githubAppInstallationPermissionsSchema = z.record(z.string(), githubPermissionLevelSchema);
+/**
+* Subscribed event-name list, e.g. `["issues", "pull_request", "push"]`.
+* Free-form for the same forward-compat reason as `permissions`.
+*/
+const githubAppInstallationEventsSchema = z.array(z.string());
+z.object({
+	login: z.string().optional(),
+	accessToken: z.string().optional(),
+	accessTokenExpiresAt: z.string().datetime({ offset: true }).optional(),
+	refreshToken: z.string().optional(),
+	refreshTokenExpiresAt: z.string().datetime({ offset: true }).optional()
+});
+z.object({ installationId: z.number().int().positive() });
+z.object({
+	installationId: z.number().int().positive(),
+	accountType: githubAccountTypeSchema,
+	accountLogin: z.string(),
+	accountGithubId: z.number().int().positive(),
+	permissions: githubAppInstallationPermissionsSchema,
+	events: githubAppInstallationEventsSchema,
+	suspended: z.boolean(),
+	manageUrl: z.string().url(),
+	createdAt: z.string().datetime({ offset: true }),
+	updatedAt: z.string().datetime({ offset: true })
+});
 /**
 * MIME types the web + client image paths recognise. Kept in sync with
 * Claude's vision API (see packages/client/src/handlers/claude-code.ts).
@@ -1334,14 +1394,24 @@ z.object({
 z.object({ next: z.string().max(256).optional() });
 z.object({
 	code: z.string().min(1),
-	state: z.string().min(1)
+	state: z.string().min(1),
+	installation_id: z.string().regex(/^\d+$/).optional(),
+	setup_action: z.enum([
+		"install",
+		"update",
+		"request"
+	]).optional()
 });
 z.object({
 	githubId: z.string().min(1),
 	login: z.string().min(1),
 	email: z.string().email().optional(),
 	displayName: z.string().optional(),
-	next: z.string().max(256).optional()
+	next: z.string().max(256).optional(),
+	installationId: z.string().regex(/^\d+$/).optional(),
+	installationAccountType: z.enum(["User", "Organization"]).optional(),
+	installationAccountLogin: z.string().min(1).optional(),
+	installationAccountGithubId: z.string().regex(/^\d+$/).optional()
 });
 /**
 * Per-organization settings — schemas, namespaces, and the registry that
@@ -1836,12 +1906,22 @@ defineConfig({
 		}),
 		githubTokenRepos: field(z.string().optional(), { env: "FIRST_TREE_HUB_CONTEXT_TREE_GITHUB_TOKEN_REPOS" })
 	}),
-	oauth: optional({ github: optional({
-		clientId: field(z.string(), { env: "FIRST_TREE_HUB_GITHUB_OAUTH_CLIENT_ID" }),
-		clientSecret: field(z.string(), {
-			env: "FIRST_TREE_HUB_GITHUB_OAUTH_CLIENT_SECRET",
+	oauth: optional({ githubApp: optional({
+		appId: field(z.string().min(1), { env: "FIRST_TREE_HUB_GITHUB_APP_ID" }),
+		clientId: field(z.string().min(1), { env: "FIRST_TREE_HUB_GITHUB_APP_CLIENT_ID" }),
+		clientSecret: field(z.string().min(1), {
+			env: "FIRST_TREE_HUB_GITHUB_APP_CLIENT_SECRET",
 			secret: true
-		})
+		}),
+		privateKeyPem: field(z.string().min(1), {
+			env: "FIRST_TREE_HUB_GITHUB_APP_PRIVATE_KEY",
+			secret: true
+		}),
+		webhookSecret: field(z.string().min(1), {
+			env: "FIRST_TREE_HUB_GITHUB_APP_WEBHOOK_SECRET",
+			secret: true
+		}),
+		slug: field(z.string().min(1).optional(), { env: "FIRST_TREE_HUB_GITHUB_APP_SLUG" })
 	}) }),
 	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
 	trustProxy: field(z.boolean().default(false), { env: "FIRST_TREE_HUB_TRUST_PROXY" }),
@@ -1942,6 +2022,74 @@ async function writeImage(params) {
 	return path;
 }
 const FETCH_TIMEOUT_MS = 15e3;
+/**
+* Node-level error codes (undici / DNS / TCP) treated as transient by the
+* `doFetch` retry layer. The set covers the failure modes that a *brief*
+* network blip can produce mid-request:
+*
+*   - `ECONNRESET`     — TCP RST mid-stream (commonly a keep-alive idle
+*                        connection closed by the peer and reused before we
+*                        noticed)
+*   - `ETIMEDOUT`      — kernel-level connect/read timeout (peer slow, not
+*                        absent)
+*   - `ENETUNREACH`    — transient routing-table flap (local network reload,
+*                        wifi roam)
+*   - `EAI_AGAIN`      — DNS resolver returned a temporary failure; the
+*                        resolver itself tells us to retry
+*   - `UND_ERR_SOCKET` — undici's internal socket-level error, wrapping the
+*                        above when the request happens through its
+*                        connection pool
+*
+* Deliberately **not** retried at this layer:
+*   - `ECONNREFUSED` — peer is reachable but refusing; retrying immediately
+*                      won't fix anything, and the caller's higher-level
+*                      reconnect logic is the right response
+*   - `ENOTFOUND`    — DNS reports the host doesn't exist (typo or rotated
+*                      record); a 1s retry isn't going to materialise the
+*                      record
+*   - other 4xx-class HTTP statuses — handled by the caller, never reach
+*                                     this set
+*/
+const RETRYABLE_NETWORK_CODES = new Set([
+	"ECONNRESET",
+	"ETIMEDOUT",
+	"ENETUNREACH",
+	"EAI_AGAIN",
+	"UND_ERR_SOCKET"
+]);
+function sleep$1(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Decide whether an error thrown by `fetch()` represents a transient
+* network-layer failure that the caller should retry.
+*
+* Walks the `cause` chain (undici nests the real reason one level deep via
+* `TypeError("fetch failed").cause`) and checks each link for:
+*   - `message` containing `"fetch failed"` (undici's signature)
+*   - `name === "AbortError"` (our 15s `AbortSignal.timeout`)
+*   - `code` ∈ `RETRYABLE_NETWORK_CODES`
+*
+* `unknown` input is intentional: this function is the gatekeeper for the
+* retry decision in `doFetch`'s catch block, where TS sees `unknown`.
+*
+* Depth is bounded (~5) to defend against the pathological case of a
+* self-referencing cause chain.
+*/
+function isTransientNetworkError(err) {
+	let current = err;
+	let depth = 0;
+	while (current !== null && current !== void 0 && depth < 5) {
+		if (typeof current !== "object") return false;
+		const obj = current;
+		if (typeof obj.message === "string" && obj.message.includes("fetch failed")) return true;
+		if (obj.name === "AbortError") return true;
+		if (typeof obj.code === "string" && RETRYABLE_NETWORK_CODES.has(obj.code)) return true;
+		current = obj.cause;
+		depth++;
+	}
+	return false;
+}
 var FirstTreeHubSDK = class {
 	_baseUrl;
 	getAccessToken;
@@ -2063,7 +2211,58 @@ var FirstTreeHubSDK = class {
 		if (!response.ok) throw await this.toSdkError(response);
 		return await response.json();
 	}
+	/**
+	* Retry transient network-layer failures and HTTP 5xx with a fixed backoff
+	* schedule. Short-term fix for the chat-visible `Result forward failed:
+	* fetch failed` errors (see docs/sdk-fetch-retry-design.md): undici's
+	* "fetch failed" / `AbortError` / `ECONNRESET`-class errors and any 5xx
+	* response trigger up to two retries with `[0, 500ms, 1000ms]` spacing,
+	* adding at most ~1.5s of latency beyond the per-attempt 15s timeout.
+	*
+	* 4xx responses and non-network exceptions are returned/thrown unchanged
+	* — they indicate a deterministic failure that retrying cannot fix.
+	*
+	* Idempotency caveat: `sendMessage` is not natively idempotent, so a
+	* `fetch failed` from a request the server actually committed will
+	* produce a duplicate message on retry. The design accepts this for now
+	* (small window, low rate, mitigated long-term by an Outbox pattern with
+	* client-generated UUIDs).
+	*
+	* The retry signature and externally-visible behaviour match `doFetch`'s
+	* pre-retry contract: callers see the same Response on success or the
+	* same error type on terminal failure.
+	*/
 	async doFetch(path, init) {
+		const delays = [
+			0,
+			500,
+			1e3
+		];
+		let lastErr;
+		for (let attempt = 0; attempt < delays.length; attempt++) {
+			const delay = delays[attempt];
+			if (delay !== void 0 && delay > 0) await sleep$1(delay);
+			try {
+				const response = await this.doFetchOnce(path, init);
+				const isLastAttempt = attempt === delays.length - 1;
+				if (response.status >= 500 && !isLastAttempt) {
+					console.warn(`sdk: retry attempt=${attempt + 1} reason=http-${response.status} path=${path}`);
+					lastErr = /* @__PURE__ */ new Error(`HTTP ${response.status}`);
+					continue;
+				}
+				return response;
+			} catch (err) {
+				lastErr = err;
+				if (!isTransientNetworkError(err)) throw err;
+				if (!(attempt === delays.length - 1)) {
+					const reason = err instanceof Error ? err.name === "AbortError" ? "timeout" : err.message.slice(0, 60) : "unknown";
+					console.warn(`sdk: retry attempt=${attempt + 1} reason=${reason} path=${path}`);
+				}
+			}
+		}
+		throw lastErr;
+	}
+	async doFetchOnce(path, init) {
 		const url = `${this._baseUrl}${path}`;
 		const headers = { Authorization: `Bearer ${await this.getAccessToken()}` };
 		if (this._agentId) headers[AGENT_SELECTOR_HEADER] = this._agentId;
@@ -3031,7 +3230,8 @@ function generateToolsDoc() {
 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: sender-id]\` header so you know who sent it
+- 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
 - **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
@@ -3046,8 +3246,8 @@ These are injected automatically when the agent process starts:
 |----------|-------------|
 | \`FIRST_TREE_HUB_SERVER_URL\` | Server address for API calls |
 | \`FIRST_TREE_HUB_ACCESS_TOKEN\` | User member access JWT (short-lived) |
-| \`FIRST_TREE_HUB_AGENT_ID\` | Your agent UUID — send as \`X-Agent-Id\` |
-| \`FIRST_TREE_HUB_CHAT_ID\` | Current chat context ID |
+| \`FIRST_TREE_HUB_AGENT_ID\` | YOUR own agent UUID. The CLI reads it to identify you as the sender — never pass it as a \`send\` target. |
+| \`FIRST_TREE_HUB_CHAT_ID\` | The chat this session is currently bound to. The CLI uses it to route messages — you don't need to pass it manually. |
 
 The \`first-tree-hub\` CLI reads these automatically — no extra setup needed.
 
@@ -3057,13 +3257,18 @@ Use the \`first-tree-hub agent send\` CLI — it reads the env vars above and
 attaches the \`Authorization\` + \`X-Agent-Id\` headers automatically:
 
 \`\`\`bash
-# Send to another agent — target is the agent NAME, NOT a uuid.
-# Names are stable (set on creation, immutable, unique in the org).
+# Send to another agent — first positional argument is the recipient's NAME
+# (NOT a uuid; uuids in chat history / participant lists are not accepted).
 # Run \`first-tree-hub agent list\` to see available names.
+#
+# Routing: if the recipient is a participant of your current chat (typically
+# 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"
 
-# Send to a chat (target is a chat UUID; use this when replying into a
-# specific chat, e.g. a group where you were mentioned)
+# 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"
 
 # Send markdown (default format is text)
@@ -6922,6 +7127,36 @@ function resolveReplyToFromEnv(env, override) {
 		replyToChat: override.replyToChat ?? (envComplete ? envChatId : void 0)
 	};
 }
+function resolveSenderName(input) {
+	const { override, envAgentId, agents } = input;
+	if (agents.size === 0) return { kind: "none" };
+	if (override) return {
+		kind: "ok",
+		name: override
+	};
+	if (envAgentId) {
+		for (const [name, cfg] of agents) if (cfg.agentId === envAgentId) return {
+			kind: "ok",
+			name
+		};
+		return {
+			kind: "envMismatch",
+			envAgentId,
+			available: [...agents.keys()]
+		};
+	}
+	if (agents.size === 1) {
+		const [only] = [...agents.keys()];
+		if (only) return {
+			kind: "ok",
+			name: only
+		};
+	}
+	return {
+		kind: "ambiguous",
+		available: [...agents.keys()]
+	};
+}
 //#endregion
 //#region src/core/admin.ts
 /**
@@ -9091,7 +9326,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-tkZS0vvL.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-CsfadBKa.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 {
@@ -10304,7 +10539,7 @@ function createFeedbackHandler(config) {
 	return { handle };
 }
 //#endregion
-//#region ../server/dist/app-D4vCx0C0.mjs
+//#region ../server/dist/app-DFZ1LKZa.mjs
 var import_fastify_opentelemetry = /* @__PURE__ */ __toESM(require_fastify_opentelemetry(), 1);
 init_esm();
 var __defProp = Object.defineProperty;
@@ -10689,7 +10924,7 @@ async function deleteAdapterConfig(db, id) {
 	const [row] = await db.delete(adapterConfigs).where(eq(adapterConfigs.id, id)).returning();
 	if (!row) throw new NotFoundError(`Adapter config "${id}" not found`);
 }
-const log$5 = createLogger$1("Adapters");
+const log$6 = createLogger$1("Adapters");
 function parseId(raw) {
 	const id = Number(raw);
 	if (!Number.isInteger(id) || id <= 0) throw new BadRequestError(`Invalid adapter ID: "${raw}"`);
@@ -10715,7 +10950,7 @@ async function adapterRoutes(app) {
 		const existing = await getAdapterConfig(app.db, id);
 		await assertAgentManageableByUser(app.db, userId, existing.agentId);
 		const config = await updateAdapterConfig(app.db, id, body, app.config.secrets.encryptionKey);
-		app.adapterManager.reload().catch((err) => log$5.error({ err }, "adapter reload failed after update"));
+		app.adapterManager.reload().catch((err) => log$6.error({ err }, "adapter reload failed after update"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return {
 			...config,
@@ -10729,7 +10964,7 @@ async function adapterRoutes(app) {
 		const existing = await getAdapterConfig(app.db, id);
 		await assertAgentManageableByUser(app.db, userId, existing.agentId);
 		await deleteAdapterConfig(app.db, id);
-		app.adapterManager.reload().catch((err) => log$5.error({ err }, "adapter reload failed after delete"));
+		app.adapterManager.reload().catch((err) => log$6.error({ err }, "adapter reload failed after delete"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return reply.status(204).send();
 	});
@@ -10745,6 +10980,7 @@ function requireAgent(request) {
 	if (!agent) throw new UnauthorizedError("Agent authentication required");
 	return agent;
 }
+const log$5 = createLogger$1("AgentChatsRoute");
 function serializeChat(chat) {
 	return {
 		...chat,
@@ -10806,6 +11042,15 @@ async function agentChatRoutes(app) {
 	});
 	app.post("/:chatId/participants", async (request, reply) => {
 		const identity = requireAgent(request);
+		if (request.body !== null && typeof request.body === "object" && "mode" in request.body) {
+			log$5.warn({
+				code: "MODE_FIELD_DEPRECATED",
+				chatId: request.params.chatId,
+				senderAgentId: identity.uuid,
+				userAgent: request.headers["user-agent"] ?? "unknown"
+			}, "Rejected: addParticipant body contains deprecated `mode` field");
+			return reply.status(400).send({ error: "MODE_FIELD_DEPRECATED: the `mode` field is no longer accepted. Participant mode is derived server-side from chat type + agent type. Remove this field from your request." });
+		}
 		const body = addParticipantSchema.parse(request.body);
 		const participants = await addParticipant(app.db, request.params.chatId, identity.uuid, body);
 		return reply.status(201).send(participants.map((p) => ({
@@ -11470,34 +11715,28 @@ async function findOrCreateChatForChannel(db, data) {
 	return db.transaction(async (tx) => {
 		const [botAgent] = await tx.select({ organizationId: agents.organizationId }).from(agents).where(eq(agents.uuid, data.botAgentId)).limit(1);
 		const orgId = botAgent?.organizationId ?? await resolveDefaultOrgId(db);
+		const metadata = chatMetadataSchema$1.parse({
+			source: data.platform,
+			externalChannelId: data.externalChannelId
+		});
 		await tx.insert(chats).values({
 			id: chatId,
 			organizationId: orgId,
 			type: internalType,
 			topic: data.topic ?? null,
 			lifecyclePolicy: "adapter_managed",
-			metadata: {
-				source: data.platform,
-				externalChannelId: data.externalChannelId
-			}
+			metadata
 		});
-		const participants = data.botAgentId === data.senderAgentId ? [{
-			chatId,
+		await addChatParticipants(tx, chatId, data.botAgentId === data.senderAgentId ? [{
 			agentId: data.botAgentId,
-			role: "member",
-			mode: "full"
+			role: "member"
 		}] : [{
-			chatId,
 			agentId: data.botAgentId,
-			role: "member",
-			mode: "full"
+			role: "member"
 		}, {
-			chatId,
 			agentId: data.senderAgentId,
-			role: "member",
-			mode: "full"
-		}];
-		await tx.insert(chatParticipants).values(participants);
+			role: "member"
+		}]);
 		await tx.insert(adapterChatMappings).values({
 			platform: data.platform,
 			externalChannelId: data.externalChannelId,
@@ -11508,14 +11747,18 @@ async function findOrCreateChatForChannel(db, data) {
 		return chatId;
 	});
 }
-/** Ensure an agent is a participant of a chat (no-op if already). */
+/**
+* Ensure an agent is a participant of a chat (no-op if already). Mode is
+* derived via the canonical entrypoint — pre-fix this also wrote `mode:`
+* implicitly via schema default `'full'`, which is wrong for non-human
+* agents in a group chat (the bug §1.1 of the Phase 1 design doc fixes).
+*/
 async function ensureParticipant(db, chatId, agentId) {
 	const [exists] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, agentId))).limit(1);
-	if (!exists) await db.insert(chatParticipants).values({
-		chatId,
+	if (!exists) await addChatParticipants(db, chatId, [{
 		agentId,
 		role: "member"
-	}).onConflictDoNothing();
+	}], { onConflictDoNothing: true });
 }
 /** Store a cross-reference between internal and external message. */
 async function createMessageReference(db, data) {
@@ -13684,6 +13927,12 @@ const authIdentities = pgTable("auth_identities", {
 * 32-byte random string. The bcrypt comparison in `authService.login`
 * treats it as a plain string and rejects every password — that's the
 * intended behaviour: SaaS users cannot fall back to password login.
+*
+* `tokens` carries the full App user-to-server bundle when called from the
+* App OAuth callback, or just `encryptedAccessToken` when called from the
+* legacy OAuth callback or `dev-callback`. Missing fields are simply not
+* written — service code that reads `metadata` MUST tolerate the legacy
+* shape (only `accessToken`), per `auth-identities.ts` jsdoc.
 */
 async function findOrCreateUserFromGithub(db, profile, opts = {}) {
 	const [existing] = await db.select({
@@ -13693,10 +13942,10 @@ async function findOrCreateUserFromGithub(db, profile, opts = {}) {
 	if (existing) {
 		const patch = {};
 		if (profile.email) patch.email = profile.email;
-		if (opts.encryptedAccessToken) patch.metadata = {
+		const tokenPatch = buildTokenMetadataPatch(profile, opts);
+		if (tokenPatch) patch.metadata = {
 			...existing.metadata ?? {},
-			accessToken: opts.encryptedAccessToken,
-			login: profile.login
+			...tokenPatch
 		};
 		if (Object.keys(patch).length > 0) await db.update(authIdentities).set({
 			...patch,
@@ -13716,7 +13965,7 @@ async function findOrCreateUserFromGithub(db, profile, opts = {}) {
 			avatarUrl: profile.avatarUrl ?? null
 		});
 		const metadata = { login: profile.login };
-		if (opts.encryptedAccessToken) metadata.accessToken = opts.encryptedAccessToken;
+		Object.assign(metadata, buildTokenMetadataPatch(profile, opts) ?? {});
 		await tx.insert(authIdentities).values({
 			id: uuidv7(),
 			userId,
@@ -13729,8 +13978,50 @@ async function findOrCreateUserFromGithub(db, profile, opts = {}) {
 	});
 	return { userId };
 }
+/**
+* Decrypt the GitHub user-to-server access token persisted on this user's
+* `auth_identities.metadata`, or `null` when there's no GitHub identity,
+* no captured token (e.g. `dev-callback` sign-in), or the ciphertext can't
+* be decoded.
+*
+* Does NOT refresh an expired App token — callers that need a guaranteed-
+* fresh token (the Step 2 repo picker) do the refresh dance inline; callers
+* that just want a best-effort identity check (the manual install-claim
+* endpoint) tolerate a stale token failing the downstream GitHub call.
+*/
+async function getStoredGithubAccessToken(db, userId, encryptionKey) {
+	const [identity] = await db.select({ metadata: authIdentities.metadata }).from(authIdentities).where(and(eq(authIdentities.provider, "github"), eq(authIdentities.userId, userId))).limit(1);
+	const meta = identity?.metadata && typeof identity.metadata === "object" ? identity.metadata : null;
+	const encrypted = meta && typeof meta.accessToken === "string" && meta.accessToken ? meta.accessToken : null;
+	if (!encrypted) return null;
+	try {
+		return decryptValue(encrypted, encryptionKey);
+	} catch {
+		return null;
+	}
+}
+/**
+* Pluck the token-related keys out of `opts` into the shape that lands on
+* `auth_identities.metadata`. Returns `null` when no token data was
+* supplied so the caller can skip the metadata write entirely.
+*
+* `login` is always refreshed when any token field is touched, so a user
+* who renames their GitHub account gets the new login snapshot on next
+* sign-in.
+*/
+function buildTokenMetadataPatch(profile, opts) {
+	if (!opts.encryptedAccessToken) return null;
+	const patch = {
+		login: profile.login,
+		accessToken: opts.encryptedAccessToken
+	};
+	if (opts.accessTokenExpiresAt) patch.accessTokenExpiresAt = opts.accessTokenExpiresAt;
+	if (opts.encryptedRefreshToken) patch.refreshToken = opts.encryptedRefreshToken;
+	if (opts.refreshTokenExpiresAt) patch.refreshTokenExpiresAt = opts.refreshTokenExpiresAt;
+	return patch;
+}
 /** Postgres `unique_violation` SQLSTATE — emitted when a UNIQUE constraint trips. */
-const PG_UNIQUE_VIOLATION$1 = "23505";
+const PG_UNIQUE_VIOLATION$2 = "23505";
 /**
 * Pick a candidate username, attempt the caller's INSERT in a transaction,
 * and retry under a fresh disambiguator if the UNIQUE(users.username)
@@ -13749,7 +14040,7 @@ async function insertWithUsernameRetry(db, base, insert) {
 		});
 		return;
 	} catch (err) {
-		if ((err?.code ?? err?.cause?.code) !== PG_UNIQUE_VIOLATION$1) throw err;
+		if ((err?.code ?? err?.cause?.code) !== PG_UNIQUE_VIOLATION$2) throw err;
 		candidate = `${base}-${randomBytes(2).toString("hex")}`;
 	}
 	candidate = `${base}-${uuidv7().slice(0, 12)}`;
@@ -13757,47 +14048,297 @@ async function insertWithUsernameRetry(db, base, insert) {
 		await insert(tx, candidate);
 	});
 }
-const TOKEN_URL = "https://github.com/login/oauth/access_token";
-const USER_URL = "https://api.github.com/user";
-const USER_EMAILS_URL = "https://api.github.com/user/emails";
 /**
-* Exchange an OAuth code for an access token + fetch the user profile.
+* GitHub App service helpers. Two surfaces that ride on top of an App's
+* private key + OAuth client credentials:
+*
+*   App-private-key (server-to-server):
+*   - `createAppJwt`           — short-lived (≤10min) JWT identifying
+*                                 Hub-as-this-App to GitHub.
+*   - `mintInstallationToken`  — exchange the App JWT for a per-installation
+*                                 token (~1h TTL). Used when Hub acts as the
+*                                 App on a tenant's repos (Phase 4 identity
+*                                 convergence — not yet wired into request
+*                                 paths).
+*
+*   App-OAuth (user-to-server, replaces the legacy OAuth App flow):
+*   - `buildAppAuthorizeUrl`         — the start URL for the combined OAuth
+*                                       + install flow (design doc D1).
+*   - `exchangeCodeForAppUserProfile` — callback-side token exchange that
+*                                       returns the user's profile, the
+*                                       access + refresh tokens, and their
+*                                       absolute expiries.
+*   - `refreshAppUserToken`           — slide an expiring access token by
+*                                       trading in its refresh token.
+*
+* Design context: `docs/github-app-design-zh.md` §3 ("one installation,
+* three capabilities") + §5.4 ("services/github-app.ts").
+*
+* Stateless by construction: no DB / config singletons. Callers thread
+* credentials in explicitly so the module is trivially safe under
+* concurrent request handlers.
+*/
+const APP_JWT_ALG = "RS256";
+/**
+* GitHub rejects App JWTs past 10 minutes; we ride 9 minutes so callers
+* don't trip the upper bound from clock skew. Generous-but-safe — the JWT
+* is cheap to mint (one RS256 signature) so caching is unnecessary.
+*/
+const APP_JWT_EXPIRY = "9m";
+/**
+* GitHub allows a small backdated `iat` to absorb clock skew on the
+* caller's side; the docs recommend 60 seconds. We mirror that.
+*/
+const APP_JWT_IAT_SKEW_SECONDS = 60;
+const APP_INSTALLATION_URL = (id) => `https://api.github.com/app/installations/${id}`;
+const OAUTH_TOKEN_URL = "https://github.com/login/oauth/access_token";
+const OAUTH_AUTHORIZE_URL = "https://github.com/login/oauth/authorize";
+const USER_API_URL = "https://api.github.com/user";
+const USER_EMAILS_API_URL = "https://api.github.com/user/emails";
+const USER_INSTALLATIONS_API_URL = "https://api.github.com/user/installations";
+/**
+* Errors from any GitHub API call this module makes. Carries the HTTP
+* status so route layers can disambiguate auth/permission failures (401 /
+* 403 / 404) from transient upstream errors (5xx / network).
+*
+* Distinct from `github-oauth.ts`'s `GithubApiError` because the App API
+* surface is a different concern (App-private-key vs. OAuth client
+* credentials) and we want logs / metrics to tell them apart at a glance.
+*/
+var GithubAppApiError = class extends Error {
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+		this.name = "GithubAppApiError";
+	}
+};
+/**
+* Mint an App JWT. RS256-signed; identifies Hub-as-this-App to GitHub for
+* the next ~9 minutes. Use this directly for `/app/...` endpoints and as
+* the input to `mintInstallationToken` for `/installation/...` endpoints.
+*
+* The PEM is imported on every call. The cost is negligible (microseconds)
+* and avoids a global mutable cache — keeps this module trivially safe to
+* call from parallel request handlers without locking. If profiling ever
+* shows this is a hotspot, add a per-key memoization at the caller side.
+*/
+async function createAppJwt(creds) {
+	const key = await importPKCS8(creds.privateKeyPem, APP_JWT_ALG);
+	const now = Math.floor(Date.now() / 1e3);
+	return new SignJWT({}).setProtectedHeader({ alg: APP_JWT_ALG }).setIssuer(creds.appId).setIssuedAt(now - APP_JWT_IAT_SKEW_SECONDS).setExpirationTime(APP_JWT_EXPIRY).sign(key);
+}
+/**
+* Fetch the installation metadata. Used by the OAuth callback path to
+* resolve the bare `installation_id` query param into a full row before
+* UPSERTing into `github_app_installations` — so the callback doesn't
+* depend on the `installation: created` webhook arriving first
+* (delivery order between callback and webhook is not guaranteed).
+*
+* The webhook handler skips this call entirely because the payload it
+* receives already carries the same shape.
+*/
+async function fetchInstallation(appJwt, installationId, opts = {}) {
+	const res = await (opts.fetcher ?? fetch)(APP_INSTALLATION_URL(installationId), { headers: {
+		Authorization: `Bearer ${appJwt}`,
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28"
+	} });
+	if (!res.ok) throw new GithubAppApiError(res.status, `GitHub App installation fetch failed (${res.status})`);
+	const body = await res.json();
+	return {
+		id: body.id,
+		accountType: body.account.type,
+		accountLogin: body.account.login,
+		accountGithubId: body.account.id,
+		permissions: body.permissions ?? {},
+		events: body.events ?? [],
+		suspendedAt: body.suspended_at ?? null
+	};
+}
+/**
+* List the installation IDs the authenticated GitHub user can administer.
+* Wraps `GET /user/installations` — GitHub's documented "what installs is
+* this user allowed to touch" endpoint. Covers both User-type installs
+* (the user owns the personal account) and Organization-type installs
+* (the user has admin rights on the org).
+*
+* Critical security primitive: the OAuth callback uses this to verify
+* that an `installation_id` query parameter — which arrives over an
+* insecure channel (the user's browser address bar) — actually belongs
+* to the authenticated user. Without this check, any signed-in user
+* could attach an arbitrary installation_id to their callback URL and
+* bind another team's installation to their own Hub org (installation
+* IDs are NOT secrets — they appear in webhook URLs, GitHub-side
+* Settings pages, and the install dialog's post-install redirect).
+*
+* Returns the bare ID set so callers can do O(1) membership checks. The
+* full installation metadata is fetched separately via `fetchInstallation`
+* once authorization has cleared.
+*/
+async function listUserAccessibleInstallationIds(userAccessToken, opts = {}) {
+	const fetcher = opts.fetcher ?? fetch;
+	const perPage = opts.perPage ?? 100;
+	const maxPages = opts.maxPages ?? 5;
+	const out = /* @__PURE__ */ new Set();
+	for (let page = 1; page <= maxPages; page++) {
+		const res = await fetcher(`${USER_INSTALLATIONS_API_URL}?per_page=${perPage}&page=${page}`, { headers: {
+			Authorization: `Bearer ${userAccessToken}`,
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28"
+		} });
+		if (!res.ok) throw new GithubAppApiError(res.status, `GitHub /user/installations failed (${res.status})`);
+		const installs = (await res.json()).installations ?? [];
+		for (const inst of installs) if (typeof inst.id === "number") out.add(inst.id);
+		if (installs.length < perPage) break;
+	}
+	return out;
+}
+/**
+* Trade an expiring user-to-server access token for a fresh pair using
+* its refresh token. Thrown on:
+*   - Network / 5xx           — `GithubAppApiError(status, …)`
+*   - 4xx with no JSON body   — `GithubAppApiError(status, …)`
+*   - 200 with `error` field  — `GithubAppApiError(401, …)` (GitHub returns
+*     200 OK for an unusable refresh token but signals the error in the
+*     body; we normalize to 401 so route layers can map to "re-login")
 *
-* The default `fetch` is overridable via `opts.fetcher` so tests can mock
-* the GitHub round-trip without standing up a fake server. The contract
-* the test fake must honor:
-*   - First call: POST `${TOKEN_URL}` → returns `{ access_token: string }`
-*   - Then GET `${USER_URL}` with `Authorization: Bearer …`
-*   - Then GET `${USER_EMAILS_URL}` (only if `/user` returned no email)
-*/
-async function exchangeCodeForProfile(config, code, redirectUri, opts = {}) {
+* Designed to be called from the OAuth callback / token-refresh path
+* landing in PR-C. The caller decrypts the stored refresh token, hands
+* the plaintext in here, encrypts the returned pair, and writes both
+* tokens + expiries back to `auth_identities.metadata`.
+*/
+async function refreshAppUserToken(clientId, clientSecret, refreshToken, opts = {}) {
 	const fetcher = opts.fetcher ?? fetch;
-	const tokenRes = await fetcher(TOKEN_URL, {
+	const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+	const res = await fetcher(OAUTH_TOKEN_URL, {
+		method: "POST",
+		headers: {
+			Accept: "application/json",
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({
+			client_id: clientId,
+			client_secret: clientSecret,
+			grant_type: "refresh_token",
+			refresh_token: refreshToken
+		})
+	});
+	if (!res.ok) throw new GithubAppApiError(res.status, `GitHub user-token refresh failed (${res.status})`);
+	const body = await res.json();
+	if (body.error || !body.access_token || !body.refresh_token) throw new GithubAppApiError(401, `GitHub user-token refresh rejected: ${body.error_description ?? body.error ?? "missing access_token / refresh_token"}`);
+	if (typeof body.expires_in !== "number" || typeof body.refresh_token_expires_in !== "number") throw new GithubAppApiError(500, "GitHub user-token refresh response missing expires_in fields — App likely has user-token expiration disabled");
+	const issuedAt = now();
+	const accessExpiresAt = new Date(issuedAt.getTime() + body.expires_in * 1e3);
+	const refreshExpiresAt = new Date(issuedAt.getTime() + body.refresh_token_expires_in * 1e3);
+	return {
+		accessToken: body.access_token,
+		accessTokenExpiresAt: accessExpiresAt.toISOString(),
+		refreshToken: body.refresh_token,
+		refreshTokenExpiresAt: refreshExpiresAt.toISOString(),
+		scope: body.scope ?? ""
+	};
+}
+/**
+* Build the App's combined OAuth + install authorization URL. Per design
+* doc D1 ("login → install in one redirect"), this is the SAME endpoint
+* GitHub uses for both flows when the App has "Request user authorization
+* (OAuth) during installation" enabled — first install lands the user on
+* the install dialog → consents → GitHub bounces back to `redirect_uri`
+* with both `code` (OAuth) and `installation_id` (the new install).
+* Returning users skip the install dialog and just receive `code`.
+*
+* `state` is the signed JWT minted by `oauth-state.ts` — same CSRF defense
+* as the legacy OAuth flow.
+*
+* Permissions are NOT in the URL — the App declares them once in its
+* GitHub-side settings (design doc D0b) and the install dialog renders
+* them automatically. Asking again in the URL would let an attacker
+* craft a downgrade prompt.
+*/
+function buildAppAuthorizeUrl(opts) {
+	const url = new URL(OAUTH_AUTHORIZE_URL);
+	url.searchParams.set("client_id", opts.clientId);
+	url.searchParams.set("redirect_uri", opts.redirectUri);
+	url.searchParams.set("state", opts.state);
+	url.searchParams.set("allow_signup", "true");
+	return url.toString();
+}
+const APP_INSTALL_URL = (slug) => `https://github.com/apps/${encodeURIComponent(slug)}/installations/new`;
+/**
+* Build the App's `installations/new` URL — the one that actually surfaces
+* GitHub's install dialog (repo picker + permission review). Distinct from
+* `buildAppAuthorizeUrl`:
+*
+*   - `authorize` (login URL) → for a user who already has the App
+*     installed, returns `code`. For one who DOESN'T, it only triggers
+*     OAuth consent — no install dialog, no `installation_id` ever comes
+*     back. So "Install on GitHub" CTAs that point at `authorize` silently
+*     never produce an install (codex P1-1).
+*   - `installations/new` → always shows the install picker. After the
+*     user confirms, GitHub redirects to the App's configured callback /
+*     setup URL with `installation_id` and (because the App has "Request
+*     user authorization (OAuth) during installation" enabled, D1) also
+*     `code` + the `state` we threaded through here.
+*
+* `state` is the same signed JWT minted by `oauth-state.ts` — GitHub
+* round-trips it on the post-install redirect, so the callback can verify
+* CSRF + recover `next` + (codex P1-3) the target org to bind to.
+*/
+function buildAppInstallUrl(opts) {
+	const url = new URL(APP_INSTALL_URL(opts.appSlug));
+	url.searchParams.set("state", opts.state);
+	return url.toString();
+}
+/**
+* App-flavoured `exchangeCodeForProfile`: trade the callback `code` for
+* the user's profile + a full token pair (access + refresh + expiries).
+*
+* Why this exists alongside `github-oauth.ts.exchangeCodeForProfile`:
+*   - Same endpoint (`/login/oauth/access_token`) but with App
+*     client_id/secret instead of OAuth App credentials.
+*   - Response carries `refresh_token` + `expires_in` +
+*     `refresh_token_expires_in` (8h / 6mo TTLs) that the OAuth-only
+*     version doesn't return.
+*   - The token-rotation semantics (`refresh_token` will be reissued on
+*     every refresh) mean the caller MUST persist all four fields, not
+*     just `accessToken`.
+*
+* The OAuth-only helper stays put for the brief window between this
+* commit and the OAuth-flow rewrite; D3 cutover deletes it outright.
+*/
+async function exchangeCodeForAppUserProfile(opts, callOpts = {}) {
+	const fetcher = callOpts.fetcher ?? fetch;
+	const now = callOpts.now ?? (() => /* @__PURE__ */ new Date());
+	const tokenRes = await fetcher(OAUTH_TOKEN_URL, {
 		method: "POST",
 		headers: {
 			Accept: "application/json",
 			"Content-Type": "application/json"
 		},
 		body: JSON.stringify({
-			client_id: config.clientId,
-			client_secret: config.clientSecret,
-			code,
-			redirect_uri: redirectUri
+			client_id: opts.clientId,
+			client_secret: opts.clientSecret,
+			code: opts.code,
+			redirect_uri: opts.redirectUri
 		})
 	});
-	if (!tokenRes.ok) throw new Error(`GitHub token exchange failed (${tokenRes.status})`);
-	const tokenJson = await tokenRes.json();
-	if (!tokenJson.access_token) throw new Error(tokenJson.error ?? "GitHub token exchange returned no access_token");
-	const userRes = await fetcher(USER_URL, { headers: {
-		Authorization: `Bearer ${tokenJson.access_token}`,
+	if (!tokenRes.ok) throw new GithubAppApiError(tokenRes.status, `GitHub App user-token exchange failed (${tokenRes.status})`);
+	const body = await tokenRes.json();
+	if (body.error || !body.access_token || !body.refresh_token) throw new GithubAppApiError(401, `GitHub App user-token exchange rejected: ${body.error_description ?? body.error ?? "missing access_token / refresh_token"}`);
+	if (typeof body.expires_in !== "number" || typeof body.refresh_token_expires_in !== "number") throw new GithubAppApiError(500, "GitHub App user-token exchange missing expires_in — App must have user-token expiration enabled");
+	const issuedAt = now();
+	const accessExpiresAt = new Date(issuedAt.getTime() + body.expires_in * 1e3);
+	const refreshExpiresAt = new Date(issuedAt.getTime() + body.refresh_token_expires_in * 1e3);
+	const userRes = await fetcher(USER_API_URL, { headers: {
+		Authorization: `Bearer ${body.access_token}`,
 		Accept: "application/vnd.github+json"
 	} });
-	if (!userRes.ok) throw new Error(`GitHub user fetch failed (${userRes.status})`);
+	if (!userRes.ok) throw new GithubAppApiError(userRes.status, `GitHub /user fetch failed (${userRes.status})`);
 	const user = await userRes.json();
 	let email = user.email ?? null;
 	if (!email) {
-		const emailsRes = await fetcher(USER_EMAILS_URL, { headers: {
-			Authorization: `Bearer ${tokenJson.access_token}`,
+		const emailsRes = await fetcher(USER_EMAILS_API_URL, { headers: {
+			Authorization: `Bearer ${body.access_token}`,
 			Accept: "application/vnd.github+json"
 		} });
 		if (emailsRes.ok) {
@@ -13813,49 +14354,186 @@ async function exchangeCodeForProfile(config, code, redirectUri, opts = {}) {
 			displayName: user.name ?? null,
 			avatarUrl: user.avatar_url ?? null
 		},
-		accessToken: tokenJson.access_token
+		accessToken: body.access_token,
+		accessTokenExpiresAt: accessExpiresAt.toISOString(),
+		refreshToken: body.refresh_token,
+		refreshTokenExpiresAt: refreshExpiresAt.toISOString(),
+		scope: body.scope ?? "",
+		installationId: opts.installationId
 	};
 }
 /**
-* Thrown when GitHub's API returns a non-2xx for a token-scoped call.
-* Carries the HTTP status so callers can distinguish auth failures (401 /
-* 403 — typically a stale token or a missing scope after we expanded to
-* `repo`) from transient upstream errors.
+* GitHub App installation records — one row per (GitHub account → Hub team)
+* binding. Replaces the per-repo OAuth + webhook-secret model that lived in
+* `organization_settings.github_integration.webhookSecretCipher`.
+*
+* One installation simultaneously unlocks three capabilities (see design
+* doc `docs/github-app-design-zh.md` §3):
+*   1. User OAuth (user-to-server access + refresh tokens) — persisted on
+*      `auth_identities.metadata` for the signing-in user, not here.
+*   2. Webhook stream — `installation_id` resolves the inbound webhook to
+*      the bound Hub org by joining on this table.
+*   3. Installation token (server-to-server) — minted on demand from the
+*      App private key; not persisted (1h TTL, cheap to re-issue).
+*
+* The (GitHub account ↔ Hub team) binding is 1:1 (D2 / §8 Q1). The
+* `hub_organization_id` UNIQUE constraint enforces that; the column is
+* nullable solely to accommodate the install-callback handler inserting
+* the row before the owning Hub team exists (fresh-signup flow). Once a
+* binding exists it never moves — re-installing the App on the same GitHub
+* account UPDATEs this row by `installation_id`.
+*
+* ON DELETE SET NULL on `hub_organization_id` rather than CASCADE because
+* the GitHub-side installation still exists upstream when a Hub team is
+* deleted — keeping the row lets a future re-binding flow recover without
+* a re-install dance.
 */
-var GithubApiError = class extends Error {
-	constructor(status, message) {
-		super(message);
-		this.status = status;
-		this.name = "GithubApiError";
-	}
-};
+const githubAppInstallations = pgTable("github_app_installations", {
+	id: text("id").primaryKey(),
+	installationId: bigint("installation_id", { mode: "number" }).notNull(),
+	accountType: text("account_type").$type().notNull(),
+	accountLogin: text("account_login").notNull(),
+	accountGithubId: bigint("account_github_id", { mode: "number" }).notNull(),
+	hubOrganizationId: text("hub_organization_id").references(() => organizations.id, { onDelete: "set null" }),
+	permissions: jsonb("permissions").$type().notNull(),
+	events: jsonb("events").$type().notNull(),
+	suspendedAt: timestamp("suspended_at", { withTimezone: true }),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	uniqueIndex("uq_github_app_installations_installation_id").on(table.installationId),
+	uniqueIndex("uq_github_app_installations_hub_org").on(table.hubOrganizationId),
+	index("idx_github_app_installations_account").on(table.accountGithubId),
+	check("ck_github_app_installations_account_type", sql`${table.accountType} IN ('User', 'Organization')`)
+]);
+/** Postgres `unique_violation` SQLSTATE — emitted on UNIQUE constraint trips. */
+const PG_UNIQUE_VIOLATION$1 = "23505";
+function isUniqueViolation(err) {
+	return (err?.code ?? err?.cause?.code) === PG_UNIQUE_VIOLATION$1;
+}
 /**
-* Fetch the authenticated user's accessible repositories. Used by the
-* Step 2 repo picker. Walks paginated GitHub API responses up to the cap.
+* UPSERT by `installation_id`. INSERTs a new row when the installation
+* is unseen; UPDATEs the metadata fields on re-install / permission
+* change / event-subscription change.
+*
+* Does NOT touch `hub_organization_id` on UPDATE — that column is
+* managed by `bindInstallationToOrg`. Otherwise a webhook arriving
+* after a manual rebind could clobber the binding back to null.
 */
-async function listUserRepos(accessToken, opts = {}) {
-	const fetcher = opts.fetcher ?? fetch;
-	const perPage = opts.perPage ?? 100;
-	const maxPages = opts.maxPages ?? 3;
-	const out = [];
-	for (let page = 1; page <= maxPages; page++) {
-		const res = await fetcher(`https://api.github.com/user/repos?affiliation=owner,collaborator,organization_member&sort=pushed&per_page=${perPage}&page=${page}`, { headers: {
-			Authorization: `Bearer ${accessToken}`,
-			Accept: "application/vnd.github+json"
-		} });
-		if (!res.ok) throw new GithubApiError(res.status, `GitHub repo list failed (${res.status})`);
-		const rows = await res.json();
-		for (const r of rows) out.push({
-			fullName: r.full_name,
-			cloneUrl: r.clone_url,
-			htmlUrl: r.html_url,
-			private: r.private,
-			defaultBranch: r.default_branch ?? null,
-			pushedAt: r.pushed_at ?? null
-		});
-		if (rows.length < perPage) break;
+async function upsertInstallationFromMetadata(db, input) {
+	const now = /* @__PURE__ */ new Date();
+	const suspendedAt = input.installation.suspendedAt ? new Date(input.installation.suspendedAt) : null;
+	const values = {
+		id: uuidv7(),
+		installationId: input.installation.id,
+		accountType: input.installation.accountType,
+		accountLogin: input.installation.accountLogin,
+		accountGithubId: input.installation.accountGithubId,
+		hubOrganizationId: input.hubOrganizationId ?? null,
+		permissions: input.installation.permissions,
+		events: input.installation.events,
+		suspendedAt,
+		createdAt: now,
+		updatedAt: now
+	};
+	const [row] = await db.insert(githubAppInstallations).values(values).onConflictDoUpdate({
+		target: githubAppInstallations.installationId,
+		set: {
+			accountType: values.accountType,
+			accountLogin: values.accountLogin,
+			accountGithubId: values.accountGithubId,
+			permissions: values.permissions,
+			events: values.events,
+			suspendedAt: values.suspendedAt,
+			updatedAt: now
+		}
+	}).returning();
+	if (!row) throw new Error("upsertInstallationFromMetadata: INSERT returned no row");
+	return row;
+}
+/**
+* Bind an installation to a Hub team. Idempotent: re-binding to the same
+* org is a no-op at the row level.
+*
+* Race-safe (codex P0-3): the previous SELECT-then-UPDATE implementation
+* had a TOCTOU window — two concurrent callbacks for the same unbound
+* installation but different Hub orgs could both see `hubOrganizationId
+* IS NULL`, both pass the in-memory validation, and then the second
+* UPDATE would silently rebind. This implementation:
+*
+*   1. Runs a conditional UPDATE: WHERE installation_id = $1 AND
+*      (hub_organization_id IS NULL OR hub_organization_id = $2).
+*      Postgres serializes the rowlock so the second concurrent caller
+*      sees the freshly-set value and the WHERE clause filters it out
+*      — the UPDATE matches 0 rows for the loser.
+*   2. On 0 rows updated, SELECTs the current row to decide which
+*      structured error to throw (not-found vs. already-bound-elsewhere).
+*   3. Catches the 23505 path that fires when two ROWS get rebound to
+*      the SAME hub_organization_id (covers the case where org A
+*      already has installation X bound and a different callback tries
+*      to bind installation Y to org A — the UPDATE on Y succeeds the
+*      WHERE filter but violates UNIQUE(hub_organization_id)).
+*      Surfaces as a clean ConflictError instead of a 23505 leaking
+*      through the route layer.
+*
+* Throws:
+*   - NotFoundError if no installation row exists with installationId.
+*   - ConflictError if (a) the installation is already bound to a
+*     different Hub team (D2 1:1), or (b) the target Hub team is
+*     already bound to a different installation.
+*
+* Returns `true` on any successful UPDATE — fresh bind and idempotent
+* re-bind both succeed identically and we don't pay the extra SELECT to
+* tell them apart. The boolean exists for forward-compat with callers
+* that may want to surface a "freshly bound" log line; today both paths
+* leave the row in the same state, so the value is advisory.
+*/
+async function bindInstallationToOrg(db, installationId, hubOrganizationId) {
+	let updatedCount;
+	try {
+		updatedCount = (await db.update(githubAppInstallations).set({
+			hubOrganizationId,
+			updatedAt: /* @__PURE__ */ new Date()
+		}).where(and(eq(githubAppInstallations.installationId, installationId), or(isNull(githubAppInstallations.hubOrganizationId), eq(githubAppInstallations.hubOrganizationId, hubOrganizationId)))).returning({ id: githubAppInstallations.id })).length;
+	} catch (err) {
+		if (isUniqueViolation(err)) throw new ConflictError("Hub team is already bound to a different GitHub installation. Uninstall the existing one from GitHub first, or transfer the binding from Settings.");
+		throw err;
 	}
-	return out;
+	if (updatedCount === 0) {
+		const [row] = await db.select({ hubOrganizationId: githubAppInstallations.hubOrganizationId }).from(githubAppInstallations).where(eq(githubAppInstallations.installationId, installationId)).limit(1);
+		if (!row) throw new NotFoundError(`No installation row for installation_id=${installationId}`);
+		throw new ConflictError(`Installation ${installationId} is already bound to a different Hub team — refusing to rebind (D2 1:1).`);
+	}
+	return true;
+}
+/**
+* Lookup the installation bound to a Hub team. Used by Settings →
+* Integrations to render the connected-account panel. Returns null when
+* no install is bound.
+*
+* `LIMIT 1` is belt-and-braces — UNIQUE(hub_organization_id) already
+* guarantees at most one row.
+*/
+async function findInstallationByOrg(db, hubOrganizationId) {
+	const [row] = await db.select().from(githubAppInstallations).where(eq(githubAppInstallations.hubOrganizationId, hubOrganizationId)).limit(1);
+	return row ?? null;
+}
+/**
+* List the installations for a GitHub account that aren't bound to any Hub
+* team yet. Newest-first.
+*
+* The orphan-recovery path (codex P1-5 + H1): if the OAuth callback's
+* `upsertInstallationFromMetadata` lands but the follow-up
+* `bindInstallationToOrg` fails (transient DB error, a racing invite that
+* errors out, …), the row sits unbound forever — GitHub only puts
+* `installation_id` in the redirect on the *initial* install, so a later
+* sign-in never re-attempts the bind. On every subsequent sign-in we sweep
+* for unbound rows whose `accountGithubId` matches the user's own GitHub
+* account and auto-claim the single one (and surface a manual "Claim
+* install" button when there are several).
+*/
+async function findUnboundInstallationsByAccount(db, accountGithubId) {
+	return db.select().from(githubAppInstallations).where(and(eq(githubAppInstallations.accountGithubId, accountGithubId), isNull(githubAppInstallations.hubOrganizationId))).orderBy(desc(githubAppInstallations.createdAt));
 }
 /** Insert (or reactivate) a `members` row for `userId` in `organizationId`. */
 async function ensureMembership(db, data) {
@@ -13987,6 +14665,22 @@ async function pickPrimaryMembership(db, userId) {
 	return (await listActiveMemberships(db, userId))[0] ?? null;
 }
 /**
+* Look up a user's ACTIVE membership in a specific org. Returns null when
+* the user isn't a member there (or their row is soft-deleted `left`).
+*
+* Used by the OAuth callback to re-check that a `targetOrganizationId`
+* carried in the signed state still names an org the user can administer
+* before binding a GitHub App installation to it (codex P1-3) — the state
+* JWT lives ~10min, long enough for a membership to be revoked.
+*/
+async function findActiveMembership(db, userId, organizationId) {
+	const [row] = await db.select({
+		memberId: members.id,
+		role: members.role
+	}).from(members).where(and(eq(members.userId, userId), eq(members.organizationId, organizationId), eq(members.status, "active"))).limit(1);
+	return row ?? null;
+}
+/**
 * Mark `members.status='left'` for the given member. v1 simplification:
 * no "must transfer admin" check — the proposal accepts the trade-off
 * (last admin allowed to leave, leaves an orphan team) and the cleanup is
@@ -14060,14 +14754,16 @@ const OAUTH_STATE_COOKIE = "oauth_state_nonce";
 * Sign a fresh state token + return the matching cookie nonce. Caller is
 * responsible for setting the cookie (HttpOnly + Secure in prod).
 */
-async function signOAuthState(jwtSecret, next) {
+async function signOAuthState(jwtSecret, next, opts = {}) {
 	const nonce = randomBytes(NONCE_BYTES).toString("base64url");
 	const secret = new TextEncoder().encode(jwtSecret);
+	const claims = {
+		nonce,
+		next
+	};
+	if (opts.targetOrganizationId) claims.targetOrganizationId = opts.targetOrganizationId;
 	return {
-		token: await new SignJWT({
-			nonce,
-			next
-		}).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(STATE_EXPIRY).sign(secret),
+		token: await new SignJWT({ ...claims }).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(STATE_EXPIRY).sign(secret),
 		nonce
 	};
 }
@@ -14091,8 +14787,12 @@ async function verifyOAuthState(jwtSecret, token, cookieNonce) {
 		throw new Error("Invalid or expired OAuth state");
 	}
 	if (typeof payload.nonce !== "string" || typeof payload.next !== "string") throw new Error("OAuth state payload malformed");
+	if (payload.targetOrganizationId !== void 0 && typeof payload.targetOrganizationId !== "string") throw new Error("OAuth state payload malformed");
 	if (!cookieNonce || cookieNonce !== payload.nonce) throw new Error("OAuth state nonce / cookie mismatch");
-	return { next: payload.next };
+	return {
+		next: payload.next,
+		...payload.targetOrganizationId ? { targetOrganizationId: payload.targetOrganizationId } : {}
+	};
 }
 /**
 * Resolve the hub's public-facing base URL.
@@ -14144,7 +14844,15 @@ function buildCookie(opts) {
 	return parts.join("; ");
 }
 /**
-* GitHub OAuth surface. All routes are public (no member JWT required).
+* GitHub sign-in surface. All routes are public (no member JWT required).
+*
+* Single flow post-D3 cutover: the GitHub App authorize URL drives both
+* sign-in and install (D1). Returning users with an existing install
+* skip the install dialog and just get `code + state`; first-time
+* installers get `code + state + installation_id`. The legacy OAuth-App
+* path that lived alongside this until D3 has been removed.
+*
+* `dev-callback` bypasses GitHub entirely; gated to non-production.
 *
 * Routes:
 *   - GET /auth/github/start         — sign state JWT + cookie + 302 to GitHub
@@ -14152,15 +14860,15 @@ function buildCookie(opts) {
 *   - GET /auth/github/dev-callback  — dev-only stub (no GitHub round-trip)
 */
 async function githubOauthRoutes(app) {
-	const oauthCfg = app.config.oauth?.github;
-	if (!oauthCfg) app.log.info("GitHub OAuth not configured — /auth/github/start will return 503. Set FIRST_TREE_HUB_GITHUB_OAUTH_CLIENT_ID/_SECRET to enable.");
+	const appCfg = app.config.oauth?.githubApp;
+	if (!appCfg) app.log.info("GitHub App not configured — /auth/github/start will return 503. Set FIRST_TREE_HUB_GITHUB_APP_* to enable.");
 	app.get("/start", { config: { rateLimit: {
 		max: 20,
 		timeWindow: "1 minute"
 	} } }, async (request, reply) => {
 		const { next } = githubStartQuerySchema.parse(request.query);
 		const safeNext = safeRedirectPath(next ?? null);
-		if (!oauthCfg) return reply.status(503).send({ error: "GitHub OAuth is not configured on this hub" });
+		if (!appCfg) return reply.status(503).send({ error: "GitHub App is not configured on this hub" });
 		const { token, nonce } = await signOAuthState(app.config.secrets.jwtSecret, safeNext);
 		const isProd = process.env.NODE_ENV === "production";
 		reply.header("Set-Cookie", buildCookie({
@@ -14170,22 +14878,22 @@ async function githubOauthRoutes(app) {
 			secure: isProd
 		}));
 		const redirectUri = `${resolvePublicUrl(app, request)}/api/v1/auth/github/callback`;
-		const params = new URLSearchParams({
-			client_id: oauthCfg.clientId,
-			redirect_uri: redirectUri,
-			state: token,
-			scope: "read:user user:email repo",
-			allow_signup: "true"
-		});
-		return reply.redirect(`https://github.com/login/oauth/authorize?${params}`, 302);
+		return reply.redirect(buildAppAuthorizeUrl({
+			clientId: appCfg.clientId,
+			redirectUri,
+			state: token
+		}), 302);
 	});
 	app.get("/callback", async (request, reply) => {
-		if (!oauthCfg) return reply.status(503).send({ error: "GitHub OAuth is not configured on this hub" });
-		const { code, state } = githubCallbackQuerySchema.parse(request.query);
+		if (!appCfg) return reply.status(503).send({ error: "GitHub App is not configured on this hub" });
+		const { code, state, installation_id: installationIdRaw } = githubCallbackQuerySchema.parse(request.query);
 		const cookieNonce = parseCookieHeader(request.headers.cookie, OAUTH_STATE_COOKIE);
 		let next;
+		let targetOrganizationId = null;
 		try {
-			next = (await verifyOAuthState(app.config.secrets.jwtSecret, state, cookieNonce)).next;
+			const verified = await verifyOAuthState(app.config.secrets.jwtSecret, state, cookieNonce);
+			next = verified.next;
+			targetOrganizationId = verified.targetOrganizationId ?? null;
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : "OAuth state rejected";
 			return reply.status(401).send({ error: msg });
@@ -14198,40 +14906,128 @@ async function githubOauthRoutes(app) {
 		}));
 		const redirectUri = `${resolvePublicUrl(app, request)}/api/v1/auth/github/callback`;
 		let profile;
-		let accessToken;
+		let tokens;
+		let plaintextUserAccessToken;
+		let installationId = null;
 		try {
-			const result = await exchangeCodeForProfile({
-				clientId: oauthCfg.clientId,
-				clientSecret: oauthCfg.clientSecret
-			}, code, redirectUri);
+			const result = await exchangeCodeForAppUserProfile({
+				clientId: appCfg.clientId,
+				clientSecret: appCfg.clientSecret,
+				code,
+				redirectUri,
+				installationId: installationIdRaw ? Number(installationIdRaw) : null
+			});
 			profile = result.profile;
-			accessToken = result.accessToken;
+			plaintextUserAccessToken = result.accessToken;
+			tokens = {
+				encryptedAccessToken: encryptValue(result.accessToken, app.config.secrets.encryptionKey),
+				accessTokenExpiresAt: result.accessTokenExpiresAt,
+				encryptedRefreshToken: encryptValue(result.refreshToken, app.config.secrets.encryptionKey),
+				refreshTokenExpiresAt: result.refreshTokenExpiresAt
+			};
+			installationId = result.installationId;
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : "GitHub exchange failed";
-			app.log.warn({ err }, "github oauth code exchange failed");
+			app.log.warn({ err }, "github sign-in code exchange failed");
 			return reply.status(401).send({ error: msg });
 		}
-		return completeOauthFlow(app, request, reply, profile, next, accessToken);
+		if (installationId !== null) try {
+			const allowedIds = await listUserAccessibleInstallationIds(plaintextUserAccessToken);
+			if (!allowedIds.has(installationId)) {
+				app.log.warn({
+					event: "github_app.installation_id_unauthorized",
+					installationId,
+					githubId: profile.githubId,
+					allowedCount: allowedIds.size
+				}, "callback installation_id is not in /user/installations — refusing to bind (attempted hijack?)");
+				installationId = null;
+			}
+		} catch (err) {
+			app.log.warn({
+				err,
+				installationId,
+				githubId: profile.githubId
+			}, "github app /user/installations check failed — refusing to bind to be safe");
+			installationId = null;
+		}
+		if (installationId !== null && appCfg) try {
+			const installation = await fetchInstallation(await createAppJwt({
+				appId: appCfg.appId,
+				privateKeyPem: appCfg.privateKeyPem
+			}), installationId);
+			await upsertInstallationFromMetadata(app.db, { installation });
+		} catch (err) {
+			app.log.warn({
+				err,
+				installationId,
+				githubId: profile.githubId
+			}, "github app install fetch/upsert failed — clearing installation_id, user can retry from Settings");
+			installationId = null;
+		}
+		return completeOauthFlow(app, request, reply, profile, next, tokens, installationId, targetOrganizationId);
 	});
 	app.get("/dev-callback", async (request, reply) => {
 		if (process.env.NODE_ENV === "production") return reply.status(404).send({ error: "Not found" });
+		const devCallbackOptIn = process.env.FIRST_TREE_HUB_DEV_CALLBACK_ENABLED;
+		if (devCallbackOptIn !== "1" && devCallbackOptIn !== "true") {
+			app.log.info({ url: request.url }, "dev-callback request refused — FIRST_TREE_HUB_DEV_CALLBACK_ENABLED is not set");
+			return reply.status(404).send({ error: "Not found" });
+		}
 		const params = githubDevCallbackQuerySchema.parse(request.query);
 		const next = safeRedirectPath(params.next ?? null);
-		return completeOauthFlow(app, request, reply, {
+		const profile = {
 			githubId: params.githubId,
 			login: params.login,
 			email: params.email ?? null,
 			displayName: params.displayName ?? params.login,
 			avatarUrl: null
-		}, next, process.env.DEV_GITHUB_PAT?.trim() || null);
-	});
+		};
+		const devPat = process.env.DEV_GITHUB_PAT?.trim() || null;
+		const tokens = devPat ? { encryptedAccessToken: encryptValue(devPat, app.config.secrets.encryptionKey) } : {};
+		let devInstallationId = null;
+		if (params.installationId) {
+			devInstallationId = Number(params.installationId);
+			try {
+				await upsertInstallationFromMetadata(app.db, { installation: {
+					id: devInstallationId,
+					accountType: params.installationAccountType ?? "User",
+					accountLogin: params.installationAccountLogin ?? params.login,
+					accountGithubId: Number(params.installationAccountGithubId ?? params.githubId),
+					permissions: {
+						contents: "write",
+						pull_requests: "write",
+						issues: "read",
+						metadata: "read",
+						members: "read"
+					},
+					events: [
+						"issues",
+						"issue_comment",
+						"pull_request",
+						"pull_request_review",
+						"push",
+						"installation",
+						"installation_repositories",
+						"member"
+					],
+					suspendedAt: null
+				} });
+			} catch (err) {
+				app.log.warn({
+					err,
+					installationId: devInstallationId
+				}, "dev-callback installation stub upsert failed");
+			}
+		}
+		return completeOauthFlow(app, request, reply, profile, next, tokens, devInstallationId, null);
+	});
 }
-async function completeOauthFlow(app, request, reply, profile, next, rawAccessToken) {
-	const encryptedAccessToken = rawAccessToken ? encryptValue(rawAccessToken, app.config.secrets.encryptionKey) : void 0;
-	const { userId } = await findOrCreateUserFromGithub(app.db, profile, { encryptedAccessToken });
+async function completeOauthFlow(app, request, reply, profile, next, oauthTokens, installationId, targetOrganizationId) {
+	const { userId } = await findOrCreateUserFromGithub(app.db, profile, oauthTokens);
 	let joinPath = "returning";
 	const inviteMatch = /^\/invite\/([^/?#]+)/.exec(next);
 	let resolved = false;
+	let resolvedOrganizationId = null;
 	if (inviteMatch?.[1]) {
 		const token = inviteMatch[1];
 		const inv = await findActiveByToken(app.db, token);
@@ -14251,24 +15047,69 @@ async function completeOauthFlow(app, request, reply, profile, next, rawAccessTo
 		});
 		joinPath = "invite";
 		resolved = true;
+		resolvedOrganizationId = inv.organizationId;
 		next = "/";
-	} else if (await pickPrimaryMembership(app.db, userId)) resolved = true;
-	else {
-		const personal = await createPersonalTeam(app.db, {
-			userId,
-			loginSeed: profile.login,
-			teamDisplayName: `${profile.login}'s team`,
-			userDisplayName: profile.displayName?.trim() || profile.login
-		});
-		joinPath = "solo";
+	} else if (targetOrganizationId) {
+		const membership = await findActiveMembership(app.db, userId, targetOrganizationId);
+		if (!membership || membership.role !== "admin") return reply.status(403).send({ error: "Not an admin of the organization this installation targets" });
 		resolved = true;
-		next = "/";
-		app.log.info({
-			event: "onboarding.team_created",
-			userId,
-			organizationId: personal.organizationId,
-			source: "oauth-bootstrap"
-		}, "onboarding funnel: team auto-created at OAuth bootstrap");
+		resolvedOrganizationId = targetOrganizationId;
+	} else {
+		const primary = await pickPrimaryMembership(app.db, userId);
+		if (primary) {
+			resolved = true;
+			resolvedOrganizationId = primary.organizationId;
+		} else {
+			const personal = await createPersonalTeam(app.db, {
+				userId,
+				loginSeed: profile.login,
+				teamDisplayName: `${profile.login}'s team`,
+				userDisplayName: profile.displayName?.trim() || profile.login
+			});
+			joinPath = "solo";
+			resolved = true;
+			resolvedOrganizationId = personal.organizationId;
+			next = "/";
+			app.log.info({
+				event: "onboarding.team_created",
+				userId,
+				organizationId: personal.organizationId,
+				source: "oauth-bootstrap"
+			}, "onboarding funnel: team auto-created at OAuth bootstrap");
+		}
+	}
+	if (installationId !== null && resolvedOrganizationId) try {
+		await bindInstallationToOrg(app.db, installationId, resolvedOrganizationId);
+	} catch (err) {
+		app.log.warn({
+			err,
+			installationId,
+			hubOrganizationId: resolvedOrganizationId,
+			userId
+		}, "github app install bind-to-org failed — sign-in continues; reconcile in Settings");
+	}
+	if (resolvedOrganizationId) try {
+		const orphans = await findUnboundInstallationsByAccount(app.db, Number(profile.githubId));
+		if (orphans.length === 1) {
+			const orphan = orphans[0];
+			if (orphan) await bindInstallationToOrg(app.db, orphan.installationId, resolvedOrganizationId).catch((err) => {
+				app.log.warn({
+					err,
+					installationId: orphan.installationId,
+					hubOrganizationId: resolvedOrganizationId,
+					userId
+				}, "orphan install reclaim failed — operator can retry via POST /claim (UI tracked in #318)");
+			});
+		} else if (orphans.length > 1) app.log.info({
+			count: orphans.length,
+			accountGithubId: Number(profile.githubId),
+			userId
+		}, "multiple unbound installs match this account — skipping auto-claim; operator must POST /claim to pick (UI #318)");
+	} catch (err) {
+		app.log.warn({
+			err,
+			userId
+		}, "orphan install reclaim sweep failed");
 	}
 	if (!resolved) return reply.status(500).send({ error: "Failed to resolve membership" });
 	const tokens = await signTokensForUser(app.config.secrets.jwtSecret, userId, app.config.auth);
@@ -14727,7 +15568,6 @@ async function createMeChat(db, humanAgentId, organizationId, body) {
 	const crossOrg = found.filter((a) => a.organizationId !== organizationId);
 	if (crossOrg.length > 0) throw new BadRequestError(`Cross-organization chat not allowed: ${crossOrg.map((a) => a.uuid).join(", ")}`);
 	const chatType = distinctIds.length === 1 ? "direct" : "group";
-	const isDirectAgentOnly = chatType === "direct" && found.every((a) => a.type !== "human");
 	const chatId = randomUUID();
 	const topic = body.topic ?? null;
 	await db.transaction(async (tx) => {
@@ -14737,11 +15577,9 @@ async function createMeChat(db, humanAgentId, organizationId, body) {
 			type: chatType,
 			topic
 		});
-		await tx.insert(chatParticipants).values(allIds.map((agentId) => ({
-			chatId,
+		await addChatParticipants(tx, chatId, allIds.map((agentId) => ({
 			agentId,
-			role: agentId === humanAgentId ? "owner" : "member",
-			...isDirectAgentOnly ? { mode: "mention_only" } : {}
+			role: agentId === humanAgentId ? "owner" : "member"
 		})));
 		await recomputeChatWatchers(tx, chatId);
 	});
@@ -14779,37 +15617,24 @@ async function addMeChatParticipants(db, chatId, callerHumanAgentId, callerOrgan
 			await recomputeChatWatchers(tx, chatId);
 			return;
 		}
-		const isUpgradingToGroup = existing.length + toInsert.length >= 3 && chat.type === "direct";
-		const isAlreadyGroup = chat.type === "group";
-		const isGroupAfter = isUpgradingToGroup || isAlreadyGroup;
-		if (isUpgradingToGroup) {
-			await tx.update(chats).set({
-				type: "group",
-				updatedAt: /* @__PURE__ */ new Date()
-			}).where(eq(chats.id, chatId));
-			const nonHumanIds = (await tx.select({ uuid: agents.uuid }).from(agents).where(and(inArray(agents.uuid, existing.map((e) => e.agentId)), sql`${agents.type} <> 'human'`))).map((a) => a.uuid);
-			if (nonHumanIds.length > 0) await tx.update(chatParticipants).set({ mode: "mention_only" }).where(and(eq(chatParticipants.chatId, chatId), inArray(chatParticipants.agentId, nonHumanIds)));
-		}
+		if (existing.length + toInsert.length >= 3 && chat.type === "direct") await changeChatType(tx, chatId, "group");
 		const carriedRows = await tx.delete(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), inArray(chatSubscriptions.agentId, toInsert))).returning({
 			agentId: chatSubscriptions.agentId,
 			lastReadAt: chatSubscriptions.lastReadAt,
 			unreadMentionCount: chatSubscriptions.unreadMentionCount
 		});
 		const carriedByAgent = new Map(carriedRows.map((r) => [r.agentId, r]));
-		const typeByAgent = new Map(found.map((a) => [a.uuid, a.type]));
-		await tx.insert(chatParticipants).values(toInsert.map((agentId) => {
-			const agentType = typeByAgent.get(agentId);
-			const mode = isGroupAfter && agentType !== "human" ? "mention_only" : "full";
+		await addChatParticipants(tx, chatId, toInsert.map((agentId) => {
 			const carried = carriedByAgent.get(agentId);
 			return {
-				chatId,
 				agentId,
 				role: "member",
-				mode,
-				lastReadAt: carried?.lastReadAt ?? null,
-				unreadMentionCount: carried?.unreadMentionCount ?? 0
+				carriedReadState: carried ? {
+					lastReadAt: carried.lastReadAt,
+					unreadMentionCount: carried.unreadMentionCount
+				} : void 0
 			};
-		})).onConflictDoNothing();
+		}), { onConflictDoNothing: true });
 		await recomputeChatWatchers(tx, chatId);
 	});
 	invalidateChatAudience(chatId);
@@ -16403,7 +17228,7 @@ async function healthzRoutes(app) {
 * `api/orgs/invitations.ts` (Class B, admin-gated).
 */
 async function publicInvitationRoutes(app) {
-	const { previewInvitation } = await import("./invitation-C299fxkP-CZRV665C.mjs");
+	const { previewInvitation } = await import("./invitation-C299fxkP-DFBBuUcj.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);
@@ -16411,6 +17236,52 @@ async function publicInvitationRoutes(app) {
 	});
 }
 /**
+* Thrown when GitHub's API returns a non-2xx for a token-scoped call.
+* Carries the HTTP status so callers can distinguish auth failures (401 /
+* 403 — typically a stale token or a missing scope) from transient upstream
+* errors.
+*/
+var GithubApiError = class extends Error {
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+		this.name = "GithubApiError";
+	}
+};
+/**
+* Fetch the authenticated user's accessible repositories. Used by the
+* Step 2 repo picker. Walks paginated GitHub API responses up to the cap.
+*
+* Takes a Bearer-style access token — works the same way whether that
+* token is a legacy OAuth grant (single-scope `repo`) or an App
+* user-to-server token (scope is whatever the App declared on its
+* settings page). The picker has no business distinguishing them.
+*/
+async function listUserRepos(accessToken, opts = {}) {
+	const fetcher = opts.fetcher ?? fetch;
+	const perPage = opts.perPage ?? 100;
+	const maxPages = opts.maxPages ?? 3;
+	const out = [];
+	for (let page = 1; page <= maxPages; page++) {
+		const res = await fetcher(`https://api.github.com/user/repos?affiliation=owner,collaborator,organization_member&sort=pushed&per_page=${perPage}&page=${page}`, { headers: {
+			Authorization: `Bearer ${accessToken}`,
+			Accept: "application/vnd.github+json"
+		} });
+		if (!res.ok) throw new GithubApiError(res.status, `GitHub repo list failed (${res.status})`);
+		const rows = await res.json();
+		for (const r of rows) out.push({
+			fullName: r.full_name,
+			cloneUrl: r.clone_url,
+			htmlUrl: r.html_url,
+			private: r.private,
+			defaultBranch: r.default_branch ?? null,
+			pushedAt: r.pushed_at ?? null
+		});
+		if (rows.length < perPage) break;
+	}
+	return out;
+}
+/**
 * `/me` and self-service organization routes (Class A — User-scoped).
 * Mounted under `requireUser` so the JWT only needs `sub = userId`.
 *
@@ -16513,11 +17384,19 @@ async function meRoutes(app) {
 	* 503 if the user has no GitHub identity bound or the token wasn't
 	* captured (e.g. dev-callback sign-in or pre-redesign user). The web
 	* client falls back to a "Reconnect GitHub" hint in that case.
+	*
+	* codex P1-4: GitHub App user-to-server tokens have an ~8h TTL. If
+	* the stored `accessTokenExpiresAt` is past (or within a 60-second
+	* buffer of expiring), trade in the persisted refresh token for a
+	* fresh pair before calling GitHub. Legacy rows without expiry
+	* fields fall through unchanged — the never-expiring OAuth-App token
+	* still works as-is.
 	*/
 	app.get("/me/github/repos", async (request, reply) => {
 		const { userId } = requireUser(request);
 		const [identity] = await app.db.select({ metadata: authIdentities.metadata }).from(authIdentities).where(and(eq(authIdentities.userId, userId), eq(authIdentities.provider, "github"))).limit(1);
-		const encrypted = identity?.metadata && typeof identity.metadata === "object" && "accessToken" in identity.metadata ? identity.metadata.accessToken : void 0;
+		const metadata = identity?.metadata && typeof identity.metadata === "object" ? identity.metadata : null;
+		const encrypted = metadata && "accessToken" in metadata ? metadata.accessToken : void 0;
 		if (typeof encrypted !== "string" || !encrypted) return reply.status(503).send({ error: "GitHub access token unavailable — please reconnect your account" });
 		let token;
 		try {
@@ -16525,6 +17404,38 @@ async function meRoutes(app) {
 		} catch {
 			return reply.status(503).send({ error: "GitHub access token could not be decoded — please reconnect" });
 		}
+		const appCfg = app.config.oauth?.githubApp;
+		const expiresAtRaw = metadata && "accessTokenExpiresAt" in metadata ? metadata.accessTokenExpiresAt : void 0;
+		const encryptedRefresh = metadata && "refreshToken" in metadata ? metadata.refreshToken : void 0;
+		if (typeof expiresAtRaw === "string" && typeof encryptedRefresh === "string" && encryptedRefresh && appCfg) {
+			const expiresAt = Date.parse(expiresAtRaw);
+			if (!Number.isNaN(expiresAt) && expiresAt - 6e4 <= Date.now()) try {
+				const refreshPlain = decryptValue(encryptedRefresh, app.config.secrets.encryptionKey);
+				const refreshed = await refreshAppUserToken(appCfg.clientId, appCfg.clientSecret, refreshPlain);
+				const nextMetadata = {
+					...metadata ?? {},
+					accessToken: encryptValue(refreshed.accessToken, app.config.secrets.encryptionKey),
+					accessTokenExpiresAt: refreshed.accessTokenExpiresAt,
+					refreshToken: encryptValue(refreshed.refreshToken, app.config.secrets.encryptionKey),
+					refreshTokenExpiresAt: refreshed.refreshTokenExpiresAt
+				};
+				await app.db.update(authIdentities).set({
+					metadata: nextMetadata,
+					updatedAt: /* @__PURE__ */ new Date()
+				}).where(and(eq(authIdentities.userId, userId), eq(authIdentities.provider, "github")));
+				token = refreshed.accessToken;
+			} catch (err) {
+				app.log.warn({
+					err,
+					userId
+				}, "github app user-token refresh failed");
+				if ((err instanceof GithubAppApiError ? err.status : 503) === 401) return reply.status(403).send({
+					error: "Your GitHub session has expired. Please sign in again.",
+					code: "refresh_failed"
+				});
+				return reply.status(503).send({ error: "Couldn't refresh GitHub credentials. Try again, or reconnect your GitHub account." });
+			}
+		}
 		try {
 			return { repos: await listUserRepos(token) };
 		} catch (err) {
@@ -16583,7 +17494,7 @@ async function meRoutes(app) {
 	*/
 	app.get("/me/pinned-agents", async (request) => {
 		const { userId } = requireUser(request);
-		const { listMyPinnedAgents } = await import("./client-0RrgrMjR-CylTJGEb.mjs");
+		const { listMyPinnedAgents } = await import("./client-GOgUQxVe-Dqk9oZf9.mjs");
 		return listMyPinnedAgents(app.db, { userId });
 	});
 	/**
@@ -17086,6 +17997,94 @@ function orgIdParam(params) {
 	return typeof orgId === "string" ? orgId : null;
 }
 /**
+* Where the post-install OAuth callback lands the user once the install
+* dialog is done — back on the Settings → GitHub panel so it can
+* re-render with the now-bound installation. The callback resolves the
+* actual destination from the signed state JWT, not from a query param,
+* so this is tamper-proof.
+*/
+const POST_INSTALL_NEXT = "/settings/github";
+/**
+* Class B — `/api/v1/orgs/:orgId/github-app-installation`.
+*
+* Read-only admin view of the GitHub App installation bound to this Hub
+* team. Powers the Settings → Integrations panel. 404 when no install is
+* bound (the panel renders the "Install on GitHub" prompt in that case).
+*
+* Distinct from `/orgs/:orgId/settings/:namespace` because installations
+* aren't editable through the same PUT/DELETE shape — the row's lifecycle
+* is driven by GitHub events (install / uninstall / suspend) and the
+* OAuth callback. The Settings panel surfaces it for visibility but the
+* write path is upstream.
+*
+* Admin-only: the installation block exposes account-level metadata
+* (login, permissions, events) that a regular member doesn't need.
+* Mirrors the readPolicy="admin" choice for `github_integration` in the
+* legacy settings.
+*/
+async function orgGithubAppRoutes(app) {
+	app.get("/", async (request) => {
+		const scope = await requireOrgAdmin(request, app.db);
+		const row = await findInstallationByOrg(app.db, scope.organizationId);
+		if (!row) throw new NotFoundError("No GitHub App installation is bound to this team");
+		const accountType = row.accountType;
+		const manageUrl = accountType === "Organization" ? `https://github.com/organizations/${encodeURIComponent(row.accountLogin)}/settings/installations/${row.installationId}` : `https://github.com/settings/installations/${row.installationId}`;
+		return {
+			installationId: row.installationId,
+			accountType,
+			accountLogin: row.accountLogin,
+			accountGithubId: row.accountGithubId,
+			permissions: row.permissions,
+			events: row.events,
+			suspended: row.suspendedAt !== null,
+			manageUrl,
+			createdAt: row.createdAt.toISOString(),
+			updatedAt: row.updatedAt.toISOString()
+		};
+	});
+	app.get("/install-url", async (request, reply) => {
+		const scope = await requireOrgAdmin(request, app.db);
+		const appCfg = app.config.oauth?.githubApp;
+		if (!appCfg?.slug) return reply.status(503).send({ error: "GitHub App install URL is unavailable — FIRST_TREE_HUB_GITHUB_APP_SLUG is not configured." });
+		const { token, nonce } = await signOAuthState(app.config.secrets.jwtSecret, POST_INSTALL_NEXT, { targetOrganizationId: scope.organizationId });
+		reply.header("Set-Cookie", buildCookie({
+			name: OAUTH_STATE_COOKIE,
+			value: nonce,
+			maxAge: 600,
+			secure: process.env.NODE_ENV === "production"
+		}));
+		return { installUrl: buildAppInstallUrl({
+			appSlug: appCfg.slug,
+			state: token
+		}) };
+	});
+	app.post("/claim", async (request) => {
+		const scope = await requireOrgAdmin(request, app.db);
+		const { installationId } = githubAppInstallationClaimBodySchema.parse(request.body);
+		const githubToken = await getStoredGithubAccessToken(app.db, scope.userId, app.config.secrets.encryptionKey);
+		if (!githubToken) throw new ForbiddenError("No GitHub access token on file — sign in with GitHub again before claiming an install");
+		let accessible;
+		try {
+			accessible = await listUserAccessibleInstallationIds(githubToken);
+		} catch (err) {
+			if ((err instanceof GithubAppApiError ? err.status : 0) === 401) throw new ForbiddenError("Your GitHub session has expired — sign in with GitHub again, then retry the claim");
+			app.log.warn({
+				err,
+				installationId,
+				userId: scope.userId
+			}, "claim: /user/installations check failed");
+			throw new ForbiddenError("Couldn't verify GitHub access for this installation — try again in a moment");
+		}
+		if (!accessible.has(installationId)) throw new ForbiddenError("You don't administer this installation on GitHub");
+		await bindInstallationToOrg(app.db, installationId, scope.organizationId);
+		return {
+			installationId,
+			organizationId: scope.organizationId,
+			bound: true
+		};
+	});
+}
+/**
 * Class B — `/api/v1/orgs/:orgId` itself: read & rename the org row.
 * Replaces the deleted `/admin/organizations/:id` GET/PATCH pair.
 */
@@ -17616,58 +18615,379 @@ async function sessionRoutes(app) {
 		});
 	});
 }
-const log$1 = createLogger$1("GithubWebhook");
-const GITHUB_ADAPTER_ID = "github-adapter";
-function verifySignature(secret, rawBody, signatureHeader) {
-	const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
-	const expectedBuf = Buffer.from(expected, "utf8");
-	const receivedBuf = Buffer.from(signatureHeader, "utf8");
-	if (expectedBuf.length !== receivedBuf.length || !timingSafeEqual(expectedBuf, receivedBuf)) throw new UnauthorizedError("Invalid webhook signature");
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-async function ensureGitHubAdapterAgent(db, organizationId) {
-	const [existing] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, organizationId), eq(agents.name, GITHUB_ADAPTER_ID))).limit(1);
-	if (existing) return existing.uuid;
-	try {
-		return (await createAgent(db, {
-			name: GITHUB_ADAPTER_ID,
-			type: "autonomous_agent",
-			displayName: "GitHub Adapter",
-			organizationId,
-			metadata: {
-				source: "github",
-				managed: true
-			}
-		})).uuid;
-	} catch (err) {
-		if (err instanceof ConflictError) {
-			const [created] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, organizationId), eq(agents.name, GITHUB_ADAPTER_ID))).limit(1);
-			if (created) return created.uuid;
+/** Pull `repository.full_name` ("owner/repo") from a webhook payload, or null. */
+function repoFullName(payload) {
+	if (!isRecord(payload)) return null;
+	const repo = isRecord(payload.repository) ? payload.repository : null;
+	return typeof repo?.full_name === "string" && repo.full_name.length > 0 ? repo.full_name : null;
+}
+function readNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function readString(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+* Resolve the entity that a GitHub webhook event belongs to.
+*
+* Returns `null` when the event isn't a clustering candidate (event type
+* outside the §4.1 "core" list, malformed payload). Caller is expected to
+* skip such events.
+*
+* Notes
+* - `commit_comment` falls back to a `commit` entity keyed on `<repo>@<sha>`
+*   when no associated PR is in the payload — the design hedges on "optionally
+*   resolve to a PR", but doing so requires an extra GitHub API call which we
+*   defer to Phase 1+.
+*/
+function extractEventEntity(eventType, payload) {
+	if (!isRecord(payload)) return null;
+	const repo = repoFullName(payload);
+	if (!repo) return null;
+	switch (eventType) {
+		case "issues":
+		case "issue_comment": {
+			const issue = isRecord(payload.issue) ? payload.issue : null;
+			const number = readNumber(issue?.number);
+			if (number === null) return null;
+			return {
+				type: "issue",
+				key: `${repo}#${number}`,
+				title: readString(issue?.title) ?? void 0,
+				url: readString(issue?.html_url) ?? void 0
+			};
 		}
-		throw err;
+		case "pull_request":
+		case "pull_request_review":
+		case "pull_request_review_comment": {
+			const pr = isRecord(payload.pull_request) ? payload.pull_request : null;
+			const number = readNumber(pr?.number);
+			if (number === null) return null;
+			return {
+				type: "pull_request",
+				key: `${repo}#${number}`,
+				title: readString(pr?.title) ?? void 0,
+				url: readString(pr?.html_url) ?? void 0
+			};
+		}
+		case "discussion":
+		case "discussion_comment": {
+			const disc = isRecord(payload.discussion) ? payload.discussion : null;
+			const number = readNumber(disc?.number);
+			if (number === null) return null;
+			return {
+				type: "discussion",
+				key: `${repo}#discussion-${number}`,
+				title: readString(disc?.title) ?? void 0,
+				url: readString(disc?.html_url) ?? void 0
+			};
+		}
+		case "commit_comment": {
+			const comment = isRecord(payload.comment) ? payload.comment : null;
+			const sha = readString(comment?.commit_id);
+			if (!sha) return null;
+			return {
+				type: "commit",
+				key: `${repo}@${sha}`,
+				url: readString(comment?.html_url) ?? void 0
+			};
+		}
+		default: return null;
 	}
 }
-async function findTargetAgent(db, organizationId, repoFullName) {
-	const allAgents = await db.select({
-		id: agents.uuid,
-		name: agents.name,
-		metadata: agents.metadata,
-		type: agents.type
-	}).from(agents).where(and(eq(agents.organizationId, organizationId), eq(agents.status, "active")));
-	for (const agent of allAgents) {
-		if (agent.name === GITHUB_ADAPTER_ID) continue;
-		const meta = agent.metadata;
-		if (meta && typeof meta === "object" && "github" in meta) {
-			const github = meta.github;
-			if (isRecord(github) && "repos" in github) {
-				const repos = github.repos;
-				if (Array.isArray(repos) && repos.includes(repoFullName)) return agent.id;
-			}
-		}
+/**
+* Closing-keyword regex from
+* https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue
+* — `close[sd]? | fix(es|ed)? | resolve[sd]?`. Cross-repo `org/repo#N` is
+* deliberately excluded (out of scope for Phase 0; see §4.5).
+*/
+const FIXES_KEYWORDS_RE = /\b(?:close[sd]?|fix(?:es|ed)?|resolve[sd]?)\s+#(\d+)\b/gi;
+/**
+* Parse `Fixes #N` / `Closes #N` / `Resolves #N` references out of a PR body.
+* Returns ordered, deduplicated entity references for issues in the same repo
+* (cross-repo refs ignored per §4.5).
+*
+* Caller is expected to pass `repoFullName` so we can build the entity key.
+*/
+function parseFixesRefs(text, repoFullName) {
+	if (!text) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const match of text.matchAll(FIXES_KEYWORDS_RE)) {
+		const num = match[1];
+		if (!num) continue;
+		const key = `${repoFullName}#${num}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push({
+			type: "issue",
+			key
+		});
 	}
-	return null;
+	return out;
 }
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Pick a chat-title prefix from (entity, eventType, action).
+*
+* PR review-flow events (`pull_request.review_requested`,
+* `pull_request_review.*`, `pull_request_review_comment.*`) collapse into a
+* single "PR Review" prefix so a chat first-touched by a review event is
+* visibly distinct from one first-touched by `pull_request.opened`. Everything
+* else just renders the entity type.
+*
+* Note: chat titles are written once at chat creation (see
+* `github-entity-chat.ts::createEntityChat`) — subsequent events for the same
+* entity reuse the existing title even if their (event, action) maps to a
+* different prefix. This matches the "entity is the container" semantic.
+*/
+function entityTitlePrefix(entity, eventType, action) {
+	if (eventType === "pull_request" && action === "review_requested") return "PR Review";
+	if (eventType === "pull_request_review") return "PR Review";
+	if (eventType === "pull_request_review_comment") return "PR Review";
+	switch (entity.type) {
+		case "issue": return "Issue";
+		case "pull_request": return "PR";
+		case "discussion": return "Discussion";
+		case "commit": return "Commit";
+	}
+}
+/**
+* Strip the leading `owner/` segment from an entity key so the chat title
+* stays compact. `owner/repo#42` → `repo#42`; `owner/repo@abc1234` →
+* `repo@abc1234`. The full `owner/repo#N` form is still used as the
+* clustering primary key (`github_entity_chat_mappings.entity_key`); only the
+* display string is shortened.
+*/
+function shortEntityKey(key) {
+	const slash = key.indexOf("/");
+	return slash === -1 ? key : key.slice(slash + 1);
+}
+/**
+* Render a chat topic from an entity. Used as the chat title; kept short so
+* the chat-list row doesn't truncate aggressively.
+*
+*   formatEntityTitle({ type: "pull_request", key: "owner/repo#307", title: "Improve overview" }, "pull_request", "opened")
+*     → "PR repo#307: Improve overview"
+*   formatEntityTitle(<same>, "pull_request", "review_requested")
+*     → "PR Review repo#307: Improve overview"
+*/
+function formatEntityTitle(entity, eventType, action) {
+	const head = `${entityTitlePrefix(entity, eventType, action)} ${shortEntityKey(entity.key)}`;
+	if (entity.title && entity.title.length > 0) return `${head}: ${entity.title}`;
+	return head;
+}
+const SILENT_EVENT_TYPES = new Set([
+	"workflow_run",
+	"workflow_job",
+	"check_run",
+	"check_suite",
+	"status",
+	"push",
+	"create",
+	"delete",
+	"fork",
+	"watch",
+	"release",
+	"label",
+	"label_created",
+	"label_deleted",
+	"reaction",
+	"member",
+	"membership",
+	"team",
+	"team_add",
+	"organization",
+	"org_block",
+	"project",
+	"project_card",
+	"project_column"
+]);
+/**
+* Per-event-type action-level filters. Frequent low-signal actions that would
+* otherwise spam an entity chat. `synchronize` (PR branch push) is the most
+* common offender — it fires on every commit push to a PR branch and never
+* carries new conversation.
+*/
+const SILENT_ACTIONS = {
+	issues: new Set([
+		"labeled",
+		"unlabeled",
+		"milestoned",
+		"demilestoned",
+		"pinned",
+		"unpinned"
+	]),
+	pull_request: new Set([
+		"labeled",
+		"unlabeled",
+		"auto_merge_enabled",
+		"auto_merge_disabled",
+		"synchronize"
+	])
+};
+/** True iff the event should be silently 200-OKed without further routing. */
+function shouldSilent(eventType, payload) {
+	if (SILENT_EVENT_TYPES.has(eventType)) return true;
+	if (!isRecord(payload)) return false;
+	if (readString((isRecord(payload.sender) ? payload.sender : null)?.type) === "Bot") return true;
+	const action = readString(payload.action);
+	if (!action) return false;
+	return SILENT_ACTIONS[eventType]?.has(action) ?? false;
+}
+/**
+* GitHub-specific webhook entity → chat clustering (Phase 0).
+*
+* Each `(organization, human_agent, delegate_agent, entity)` tuple resolves to
+* exactly one chat. Future external sources (Linear, Slack, …) get their own
+* tables — their entity models differ enough that a generic table would slip
+* back into untyped jsonb.
+*
+* `bound_via` distinguishes the first-touch row (`direct`) from a row written
+* by the `Fixes #N` linker (`fixes_link`). Routing logic ignores the
+* distinction; it exists for audit and future strategy tweaks.
+*/
+const githubEntityChatMappings = pgTable("github_entity_chat_mappings", {
+	organizationId: text("organization_id").notNull().references(() => organizations.id),
+	humanAgentId: text("human_agent_id").notNull().references(() => agents.uuid, { onDelete: "cascade" }),
+	delegateAgentId: text("delegate_agent_id").notNull().references(() => agents.uuid, { onDelete: "cascade" }),
+	entityType: text("entity_type").notNull(),
+	entityKey: text("entity_key").notNull(),
+	chatId: text("chat_id").notNull().references(() => chats.id, { onDelete: "cascade" }),
+	boundAt: timestamp("bound_at", { withTimezone: true }).notNull().defaultNow(),
+	boundVia: text("bound_via").notNull()
+}, (table) => [primaryKey({ columns: [
+	table.organizationId,
+	table.humanAgentId,
+	table.delegateAgentId,
+	table.entityType,
+	table.entityKey
+] }), index("idx_github_entity_chat_mappings_chat").on(table.chatId)]);
+/**
+* Resolve which chat a GitHub event for (human, delegate, entity) belongs to.
+*
+* Three-step strategy from docs/webhook-routing-design.md §4.4:
+*   a. Direct hit — entity already bound; reuse that chat.
+*   b. Fixes-link — any related entity (parsed from `Fixes #N` in a PR body)
+*      already bound; write a `fixes_link` row for this entity pointing at
+*      the same chat, return it.
+*   c. Miss — create a fresh chat via the canonical `createChat` entrypoint
+*      and write a `direct` mapping row.
+*
+* Concurrent webhook deliveries for a never-before-seen entity race on (c);
+* the composite primary key + ON CONFLICT DO NOTHING ensures only one row
+* survives. The losing caller falls back to a re-read so the chat stays
+* unique.
+*/
+async function resolveTargetChat(db, params) {
+	const { organizationId, humanAgentId, delegateAgentId, entity, relatedEntities, eventType, action } = params;
+	const direct = await lookupMapping(db, organizationId, humanAgentId, delegateAgentId, entity);
+	if (direct) return {
+		chatId: direct.chatId,
+		created: false,
+		boundVia: direct.boundVia
+	};
+	for (const ref of relatedEntities) {
+		const linked = await lookupMapping(db, organizationId, humanAgentId, delegateAgentId, ref);
+		if (!linked) continue;
+		const inserted = await insertMappingIfAbsent(db, {
+			organizationId,
+			humanAgentId,
+			delegateAgentId,
+			entity,
+			chatId: linked.chatId,
+			boundVia: "fixes_link"
+		});
+		return {
+			chatId: inserted.chatId,
+			created: false,
+			boundVia: inserted.boundVia
+		};
+	}
+	const chat = await createEntityChat(db, humanAgentId, delegateAgentId, entity, eventType, action);
+	const inserted = await insertMappingIfAbsent(db, {
+		organizationId,
+		humanAgentId,
+		delegateAgentId,
+		entity,
+		chatId: chat.id,
+		boundVia: "direct"
+	});
+	return {
+		chatId: inserted.chatId,
+		created: inserted.chatId === chat.id,
+		boundVia: inserted.boundVia
+	};
+}
+async function lookupMapping(db, organizationId, humanAgentId, delegateAgentId, entity) {
+	const [row] = await db.select({
+		chatId: githubEntityChatMappings.chatId,
+		boundVia: githubEntityChatMappings.boundVia
+	}).from(githubEntityChatMappings).where(and(eq(githubEntityChatMappings.organizationId, organizationId), eq(githubEntityChatMappings.humanAgentId, humanAgentId), eq(githubEntityChatMappings.delegateAgentId, delegateAgentId), eq(githubEntityChatMappings.entityType, entity.type), eq(githubEntityChatMappings.entityKey, entity.key))).limit(1);
+	if (!row) return null;
+	return {
+		chatId: row.chatId,
+		boundVia: row.boundVia === "fixes_link" ? "fixes_link" : "direct"
+	};
+}
+async function insertMappingIfAbsent(db, params) {
+	const [inserted] = await db.insert(githubEntityChatMappings).values({
+		organizationId: params.organizationId,
+		humanAgentId: params.humanAgentId,
+		delegateAgentId: params.delegateAgentId,
+		entityType: params.entity.type,
+		entityKey: params.entity.key,
+		chatId: params.chatId,
+		boundVia: params.boundVia
+	}).onConflictDoNothing({ target: [
+		githubEntityChatMappings.organizationId,
+		githubEntityChatMappings.humanAgentId,
+		githubEntityChatMappings.delegateAgentId,
+		githubEntityChatMappings.entityType,
+		githubEntityChatMappings.entityKey
+	] }).returning({
+		chatId: githubEntityChatMappings.chatId,
+		boundVia: githubEntityChatMappings.boundVia
+	});
+	if (inserted) return {
+		chatId: inserted.chatId,
+		boundVia: inserted.boundVia === "fixes_link" ? "fixes_link" : "direct"
+	};
+	const winner = await lookupMapping(db, params.organizationId, params.humanAgentId, params.delegateAgentId, params.entity);
+	if (!winner) throw new Error("Unexpected: mapping insert conflicted but row not visible on re-read");
+	return winner;
+}
+/**
+* Create a fresh chat for a (human, delegate, entity) tuple. Goes through the
+* canonical `createChat` so:
+*   - cross-org participants are rejected (BadRequestError)
+*   - direct agent-only chats automatically get `mode=mention_only`
+*   - watcher rows are recomputed
+*   - a future addParticipant call would upgrade the chat to `group` via
+*     the server's `changeChatType` service instead of raw INSERT shortcuts
+*/
+async function createEntityChat(db, humanAgentId, delegateAgentId, entity, eventType, action) {
+	const metadata = chatMetadataSchema$1.parse({
+		source: "github",
+		entityType: entity.type,
+		entityKey: entity.key,
+		...entity.url ? { entityUrl: entity.url } : {}
+	});
+	return { id: (await createChat(db, humanAgentId, {
+		type: "direct",
+		participantIds: [delegateAgentId],
+		topic: formatEntityTitle(entity, eventType, action),
+		metadata
+	})).id };
+}
+const log$1 = createLogger$1("GithubWebhook");
+function verifySignature(secret, rawBody, signatureHeader) {
+	const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+	const expectedBuf = Buffer.from(expected, "utf8");
+	const receivedBuf = Buffer.from(signatureHeader, "utf8");
+	if (expectedBuf.length !== receivedBuf.length || !timingSafeEqual(expectedBuf, receivedBuf)) throw new UnauthorizedError("Invalid webhook signature");
 }
 /** Extract unique @mentions from text. Returns lowercase usernames.
 * Excludes email patterns (user@example.com) and team mentions (@org/team). */
@@ -17708,10 +19028,18 @@ function evaluateDelegateTarget(target, sourceOrgId) {
 }
 /**
 * Route @mentions to delegate agents.
-* For each mentioned user who has delegate_mention configured,
-* send a card message from the mentioned user to their delegate.
+*
+* For each mentioned GitHub user who maps to an agent with `delegate_mention`
+* configured, resolve which chat the event belongs to (via §4.4's
+* entity-clustering rules) and post a card from the human-bound agent to its
+* delegate.
+*
+* The entity argument is the §4.2 entity for the current event; `relatedRefs`
+* is the parsed `Fixes #N` list (empty for non-PR events). Both are
+* pre-computed by the caller so the heavy parsing doesn't run once per
+* mention.
 */
-async function routeMentionDelegations(app, organizationId, mentionedNames, ctx) {
+async function routeMentionDelegations(app, organizationId, mentionedNames, ctx, entity, relatedRefs) {
 	if (mentionedNames.length === 0) return 0;
 	const delegates = await app.db.select({
 		id: agents.uuid,
@@ -17740,8 +19068,24 @@ async function routeMentionDelegations(app, organizationId, mentionedNames, ctx)
 			continue;
 		}
 		try {
-			const chat = await findOrCreateDirectChat(app.db, agent.id, agent.delegateMention);
-			const { message: msg, recipients } = await sendMessage(app.db, chat.id, agent.id, {
+			const resolved = await resolveTargetChat(app.db, {
+				organizationId,
+				humanAgentId: agent.id,
+				delegateAgentId: agent.delegateMention,
+				entity,
+				relatedEntities: relatedRefs,
+				eventType: ctx.event,
+				action: ctx.action ?? ""
+			});
+			log$1.info({
+				chatId: resolved.chatId,
+				entityType: entity.type,
+				entityKey: entity.key,
+				boundVia: resolved.boundVia,
+				created: resolved.created,
+				humanAgent: agent.name
+			}, "resolved entity chat");
+			const { message: msg, recipients } = await sendMessage(app.db, resolved.chatId, agent.id, {
 				format: "card",
 				content: {
 					type: "github_mention",
@@ -17752,13 +19096,20 @@ async function routeMentionDelegations(app, organizationId, mentionedNames, ctx)
 					sender: ctx.sender,
 					title: ctx.title,
 					body: ctx.body,
-					url: ctx.url
+					url: ctx.url,
+					entity: {
+						type: entity.type,
+						key: entity.key,
+						url: entity.url ?? null
+					}
 				},
 				metadata: {
 					source: "github",
 					event: "mention_delegation",
 					mentionedUser: agent.name,
-					action: ctx.action
+					action: ctx.action,
+					entityType: entity.type,
+					entityKey: entity.key
 				}
 			});
 			notifyRecipients(app.notifier, recipients, msg.id);
@@ -17773,43 +19124,6 @@ async function routeMentionDelegations(app, organizationId, mentionedNames, ctx)
 	}
 	return routed;
 }
-function parseIssuesPayload(body) {
-	if (!isRecord(body)) throw new BadRequestError("Invalid payload: expected object");
-	if (typeof body.action !== "string") throw new BadRequestError("Invalid payload: missing action");
-	if (!isRecord(body.issue)) throw new BadRequestError("Invalid payload: missing issue");
-	if (!isRecord(body.repository)) throw new BadRequestError("Invalid payload: missing repository");
-	if (!isRecord(body.sender)) throw new BadRequestError("Invalid payload: missing sender");
-	const issue = body.issue;
-	const labels = Array.isArray(issue.labels) ? issue.labels.filter((l) => isRecord(l) && typeof l.name === "string") : [];
-	return {
-		action: body.action,
-		issue: {
-			number: typeof issue.number === "number" ? issue.number : 0,
-			title: typeof issue.title === "string" ? issue.title : "",
-			body: typeof issue.body === "string" ? issue.body : null,
-			html_url: typeof issue.html_url === "string" ? issue.html_url : "",
-			labels,
-			state: typeof issue.state === "string" ? issue.state : "open"
-		},
-		repository: { full_name: typeof body.repository.full_name === "string" ? body.repository.full_name : "" },
-		sender: { login: typeof body.sender.login === "string" ? body.sender.login : "" }
-	};
-}
-function parseIssueCommentPayload(body) {
-	const base = parseIssuesPayload(body);
-	if (!isRecord(body)) throw new BadRequestError("Invalid payload: expected object");
-	if (!isRecord(body.comment)) throw new BadRequestError("Invalid payload: missing comment");
-	const comment = body.comment;
-	const commentUser = isRecord(comment.user) ? comment.user : { login: "" };
-	return {
-		...base,
-		comment: {
-			body: typeof comment.body === "string" ? comment.body : "",
-			html_url: typeof comment.html_url === "string" ? comment.html_url : "",
-			user: { login: typeof commentUser.login === "string" ? commentUser.login : "" }
-		}
-	};
-}
 async function githubWebhookRoutes(app) {
 	app.addContentTypeParser("application/json", { parseAs: "buffer" }, (_request, body, done) => {
 		done(null, body);
@@ -17839,6 +19153,11 @@ async function githubWebhookRoutes(app) {
 			ok: true,
 			event: "ping"
 		});
+		if (shouldSilent(eventType, payload)) return reply.status(200).send({
+			ok: true,
+			event: eventType,
+			silent: true
+		});
 		const deliveryHeader = request.headers["x-github-delivery"];
 		const deliveryId = typeof deliveryHeader === "string" && deliveryHeader.length > 0 ? deliveryHeader : null;
 		if (deliveryId) {
@@ -17855,16 +19174,17 @@ async function githubWebhookRoutes(app) {
 			}
 		}
 		try {
-			if (eventType === "issues") return await handleIssuesEvent(app, orgId, eventType, payload, reply);
-			if (eventType === "issue_comment") return await handleIssueCommentEvent(app, orgId, eventType, payload, reply);
-			let mentionsRouted = 0;
-			const allowedActions = MENTION_ACTIONS[eventType];
 			const action = isRecord(payload) && typeof payload.action === "string" ? payload.action : void 0;
-			if (allowedActions && action && allowedActions.includes(action)) mentionsRouted = await handleMentionDelegation(app, orgId, eventType, payload);
+			const allowedActions = MENTION_ACTIONS[eventType];
+			if (!allowedActions || !action || !allowedActions.includes(action)) return reply.status(200).send({
+				ok: true,
+				event: eventType,
+				handled: false
+			});
+			const mentionsRouted = await handleMentionDelegation(app, orgId, eventType, payload);
 			return reply.status(200).send({
 				ok: true,
 				event: eventType,
-				handled: mentionsRouted > 0,
 				mentionsRouted
 			});
 		} catch (err) {
@@ -18036,9 +19356,15 @@ async function handleMentionDelegation(app, organizationId, eventType, payload)
 	const textMentions = extractMentions$1(extractEventText(eventType, payload));
 	const structuralMentions = extractStructuralMentions(eventType, payload);
 	const mentions = [...new Set([...textMentions, ...structuralMentions])];
-	const mentionCtx = extractEventContext(eventType, payload);
-	if (mentions.length > 0 && mentionCtx) return routeMentionDelegations(app, organizationId, mentions, mentionCtx);
-	return 0;
+	if (mentions.length === 0) return 0;
+	const ctx = extractEventContext(eventType, payload);
+	if (!ctx) return 0;
+	const entity = extractEventEntity(eventType, payload);
+	if (!entity) {
+		log$1.warn({ eventType }, "mention extracted but no entity resolvable; skipping fan-out");
+		return 0;
+	}
+	return routeMentionDelegations(app, organizationId, mentions, ctx, entity, eventType === "pull_request" && ctx.repository.length > 0 ? parseFixesRefs(ctx.body, ctx.repository) : []);
 }
 /** Actions that represent new/changed content (worth scanning for @mentions).
 * Note: `pull_request.review_requested` doesn't carry an @mention in any
@@ -18059,123 +19385,39 @@ const MENTION_ACTIONS = {
 	discussion_comment: ["created"],
 	commit_comment: ["created"]
 };
-async function handleIssuesEvent(app, organizationId, eventType, payload, reply) {
-	const data = parseIssuesPayload(payload);
-	if (MENTION_ACTIONS.issues?.includes(data.action)) await handleMentionDelegation(app, organizationId, eventType, payload);
-	if (![
-		"opened",
-		"edited",
-		"labeled"
-	].includes(data.action)) return reply.status(200).send({
-		ok: true,
-		event: "issues",
-		action: data.action,
-		handled: false
-	});
-	const [senderId, targetAgentId] = await Promise.all([ensureGitHubAdapterAgent(app.db, organizationId), findTargetAgent(app.db, organizationId, data.repository.full_name)]);
-	if (!targetAgentId) {
-		log$1.warn({
-			repo: data.repository.full_name,
-			event: "issue"
-		}, "no target agent found for GitHub event");
-		return reply.status(200).send({
-			ok: true,
-			event: "issues",
-			action: data.action,
-			routed: false
-		});
-	}
-	const content = {
-		type: "github_issue",
-		action: data.action,
-		issue: {
-			number: data.issue.number,
-			title: data.issue.title,
-			body: data.issue.body,
-			url: data.issue.html_url,
-			labels: data.issue.labels.map((l) => l.name),
-			state: data.issue.state
-		},
-		repository: data.repository.full_name,
-		sender: data.sender.login
-	};
-	const metadata = {
-		source: "github",
-		event: "issues",
-		action: data.action
-	};
-	const chat = await findOrCreateDirectChat(app.db, senderId, targetAgentId);
-	const { message: msg, recipients } = await sendMessage(app.db, chat.id, senderId, {
-		format: "card",
-		content,
-		metadata
-	});
-	notifyRecipients(app.notifier, recipients, msg.id);
-	return reply.status(200).send({
-		ok: true,
-		event: "issues",
-		action: data.action,
-		routed: true
-	});
-}
-async function handleIssueCommentEvent(app, organizationId, eventType, payload, reply) {
-	const data = parseIssueCommentPayload(payload);
-	if (MENTION_ACTIONS.issue_comment?.includes(data.action)) await handleMentionDelegation(app, organizationId, eventType, payload);
-	if (data.action !== "created") return reply.status(200).send({
-		ok: true,
-		event: "issue_comment",
-		action: data.action,
-		handled: false
-	});
-	const [senderId, targetAgentId] = await Promise.all([ensureGitHubAdapterAgent(app.db, organizationId), findTargetAgent(app.db, organizationId, data.repository.full_name)]);
-	if (!targetAgentId) {
-		log$1.warn({
-			repo: data.repository.full_name,
-			event: "issue_comment"
-		}, "no target agent found for GitHub event");
-		return reply.status(200).send({
-			ok: true,
-			event: "issue_comment",
-			action: data.action,
-			routed: false
-		});
-	}
-	const content = {
-		type: "github_issue_comment",
-		action: data.action,
-		issue: {
-			number: data.issue.number,
-			title: data.issue.title,
-			url: data.issue.html_url,
-			labels: data.issue.labels.map((l) => l.name),
-			state: data.issue.state
-		},
-		comment: {
-			body: data.comment.body,
-			url: data.comment.html_url,
-			author: data.comment.user.login
-		},
-		repository: data.repository.full_name,
-		sender: data.sender.login
-	};
-	const metadata = {
-		source: "github",
-		event: "issue_comment",
-		action: data.action
+/**
+* Boot-time configuration sanity checks. Called from `buildApp` so BOTH
+* server entry points are covered:
+*   - `packages/server/src/index.ts` (the standalone bin)
+*   - `packages/command/src/core/server.ts` (the CLI `server start` path)
+*
+* The previous incarnation lived in `index.ts` and was only run by the
+* standalone bin — the CLI path could boot a misconfigured prod with no
+* surface complaint (codex P1-8).
+*
+* Throws on misconfiguration; never returns a value.
+*/
+function assertBootConfigValid(config) {
+	assertProductionRequiresPublicUrl(config);
+	assertGithubAppConfigComplete(config);
+}
+function assertProductionRequiresPublicUrl(config) {
+	if (process.env.NODE_ENV === "production" && !config.server.publicUrl) throw new Error("FIRST_TREE_HUB_PUBLIC_URL is required in production — set the public-facing hub URL.");
+}
+function assertGithubAppConfigComplete(config) {
+	const ghApp = config.oauth?.githubApp;
+	if (!ghApp) return;
+	const required = {
+		FIRST_TREE_HUB_GITHUB_APP_ID: ghApp.appId,
+		FIRST_TREE_HUB_GITHUB_APP_CLIENT_ID: ghApp.clientId,
+		FIRST_TREE_HUB_GITHUB_APP_CLIENT_SECRET: ghApp.clientSecret,
+		FIRST_TREE_HUB_GITHUB_APP_PRIVATE_KEY: ghApp.privateKeyPem,
+		FIRST_TREE_HUB_GITHUB_APP_WEBHOOK_SECRET: ghApp.webhookSecret
 	};
-	const chat = await findOrCreateDirectChat(app.db, senderId, targetAgentId);
-	const { message: msg, recipients } = await sendMessage(app.db, chat.id, senderId, {
-		format: "card",
-		content,
-		metadata
-	});
-	notifyRecipients(app.notifier, recipients, msg.id);
-	return reply.status(200).send({
-		ok: true,
-		event: "issue_comment",
-		action: data.action,
-		routed: true
-	});
+	const missing = Object.entries(required).filter(([, v]) => !v || v.trim().length === 0).map(([k]) => k);
+	if (missing.length > 0 && missing.length < Object.keys(required).length) throw new Error(`GitHub App is half-configured — missing env vars: ${missing.join(", ")}. Set all five or none.`);
+	if (missing.length === Object.keys(required).length) throw new Error("GitHub App env block is present but every value is empty — unset the FIRST_TREE_HUB_GITHUB_APP_* vars to disable App sign-in.");
+	if (ghApp.privateKeyPem && !ghApp.privateKeyPem.includes("-----BEGIN PRIVATE KEY-----")) throw new Error("FIRST_TREE_HUB_GITHUB_APP_PRIVATE_KEY does not look like a PKCS#8 PEM — expected `-----BEGIN PRIVATE KEY-----` header. If the value came from a single-line env file, replace literal `\\n` with real newlines.");
 }
 var schema_exports = /* @__PURE__ */ __exportAll({
 	adapterAgentMappings: () => adapterAgentMappings,
@@ -18191,6 +19433,8 @@ var schema_exports = /* @__PURE__ */ __exportAll({
 	chatSubscriptions: () => chatSubscriptions,
 	chats: () => chats,
 	clients: () => clients,
+	githubAppInstallations: () => githubAppInstallations,
+	githubEntityChatMappings: () => githubEntityChatMappings,
 	inboxEntries: () => inboxEntries,
 	invitationRedemptions: () => invitationRedemptions,
 	invitations: () => invitations,
@@ -19524,6 +20768,7 @@ async function buildApp(config) {
 		const msg = err instanceof Error ? err.message : String(err);
 		throw new Error(`${msg} — check FIRST_TREE_HUB_AUTH_*_EXPIRY env vars (got access=${config.auth.accessTokenExpiry}, refresh=${config.auth.refreshTokenExpiry}, connect=${config.auth.connectTokenExpiry}).`);
 	}
+	assertBootConfigValid(config);
 	applyLoggerConfig({
 		level: config.observability.logging.level,
 		format: config.observability.logging.format,
@@ -19700,6 +20945,7 @@ async function buildApp(config) {
 			await scope.register(orgInvitationRoutes, { prefix: "/invitations" });
 			await scope.register(orgMemberRoutes, { prefix: "/members" });
 			await scope.register(orgSettingsRoutes, { prefix: "/settings" });
+			await scope.register(orgGithubAppRoutes, { prefix: "/github-app-installation" });
 			await scope.register(orgContextTreeSnapshotRoutes, { prefix: "/context-tree" });
 		}), { prefix: "/orgs/:orgId" });
 		await api.register(orgWsRoutes(notifier, config.secrets.jwtSecret), { prefix: "/orgs/:orgId/ws" });
@@ -20330,4 +21576,4 @@ function registerSaaSConnectCommand(program) {
 	});
 }
 //#endregion
-export { formatStaleReason as $, checkDocker as A, isServiceSupported as B, createApiNameResolver as C, checkBackgroundService as D, checkAgentConfigs as E, checkWebSocket as F, uninstallClientService as G, restartClientService as H, printResults as I, stopPostgres as J, ensurePostgres as K, reconcileAgentConfigs as L, checkServerConfig as M, checkServerHealth as N, checkClientConfig as O, checkServerReachable as P, findStaleAliases as Q, getClientServiceStatus as R, runHomeMigration as S, runMigrations as T, startClientService as U, resolveCliInvocation as V, stopClientService as W, handleClientOrgMismatch as X, ClientRuntime as Y, rotateClientIdWithBackup as Z, formatCheckReport as _, declineUpdate as a, success as at, onboardCreate as b, detectInstallMode as c, FirstTreeHubSDK as ct, startServer as d, cleanWorkspaces as dt, removeLocalAgent as et, reconcileLocalRuntimeProviders as f, probeCapabilities as ft, promptMissingFields as g, promptAddAgent as h, createExecuteUpdate as i, fail as it, checkNodeVersion as j, checkDatabase as k, fetchLatestVersion as l, SdkError as lt, isInteractive as m, configureClientLoggerForService as mt, deriveHubUrlFromToken as n, hasUser as nt, promptUpdate as o, ClientOrgMismatchError as ot, uploadClientCapabilities as p, applyClientLoggerConfig as pt, isDockerAvailable as q, registerSaaSConnectCommand as r, resolveReplyToFromEnv as rt, PACKAGE_NAME as s, ClientUserMismatchError as st, HubUrlDerivationError as t, createOwner as tt, installGlobalLatest as u, SessionRegistry as ut, loadOnboardState as v, migrateLocalAgentDirs as w, saveOnboardState as x, onboardCheck as y, installClientService as z };
+export { formatStaleReason as $, checkDocker as A, isServiceSupported as B, createApiNameResolver as C, checkBackgroundService as D, checkAgentConfigs as E, checkWebSocket as F, uninstallClientService as G, restartClientService as H, printResults as I, stopPostgres as J, ensurePostgres as K, reconcileAgentConfigs as L, checkServerConfig as M, checkServerHealth as N, checkClientConfig as O, checkServerReachable as P, findStaleAliases as Q, getClientServiceStatus as R, runHomeMigration as S, runMigrations as T, startClientService as U, resolveCliInvocation as V, stopClientService as W, handleClientOrgMismatch as X, ClientRuntime as Y, rotateClientIdWithBackup as Z, formatCheckReport as _, declineUpdate as a, fail as at, onboardCreate as b, detectInstallMode as c, ClientUserMismatchError as ct, startServer as d, SessionRegistry as dt, removeLocalAgent as et, reconcileLocalRuntimeProviders as f, cleanWorkspaces as ft, promptMissingFields as g, promptAddAgent as h, configureClientLoggerForService as ht, createExecuteUpdate as i, resolveSenderName as it, checkNodeVersion as j, checkDatabase as k, fetchLatestVersion as l, FirstTreeHubSDK as lt, isInteractive as m, applyClientLoggerConfig as mt, deriveHubUrlFromToken as n, hasUser as nt, promptUpdate as o, success as ot, uploadClientCapabilities as p, probeCapabilities as pt, isDockerAvailable as q, registerSaaSConnectCommand as r, resolveReplyToFromEnv as rt, PACKAGE_NAME as s, ClientOrgMismatchError as st, HubUrlDerivationError as t, createOwner as tt, installGlobalLatest as u, SdkError as ut, loadOnboardState as v, migrateLocalAgentDirs as w, saveOnboardState as x, onboardCheck as y, installClientService as z };