@agent-team-foundation/first-tree-hub 0.12.5 → 0.12.7

package/dist/{saas-connect-DYjvx5yr.mjs → saas-connect-CY2NxeKx.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 refreshTokenSchema, A as dryRunAgentRuntimeConfigSchema, B as isRedactedEnvValue, C as createAgentSchema, D as createOrgFromMeSchema, E as createMemberSchema, F as imageInlineContentSchema, G as messageSourceSchema$1, H as joinByInvitationSchema, I as inboxAckFrameSchema, J as paginationQuerySchema, K as notificationQuerySchema, L as inboxDeliverFrameSchema$1, M as githubCallbackQuerySchema, N as githubDevCallbackQuerySchema, O as defaultRuntimeConfigPayload, P as githubStartQuerySchema, Q as rebindAgentSchema, R as inboxPollQuerySchema, S as createAdapterMappingSchema, T as createMeChatSchema, U as listMeChatsQuerySchema, V as isReservedAgentName$1, W as loginSchema, Y as patchOnboardingSchema, _t as updateClientCapabilitiesSchema, a as AGENT_VISIBILITY, at as sendToAgentSchema, b as contextTreeSnapshotSchema, bt as wsAuthFrameSchema, c as ORG_SETTINGS_NAMESPACES$1, ct as sessionEventSchema$1, d as addParticipantSchema, dt as stripCode, et as runtimeStateMessageSchema, f as agentBindRequestSchema, ft as submitQuestionAnswerSchema, g as chatMetadataSchema$1, gt as updateChatSchema, h as agentTypeSchema$1, ht as updateAgentSchema, i as AGENT_STATUSES, it as sendMessageSchema, k as delegateFeishuUserSchema, l as WS_AUTH_FRAME_TIMEOUT_MS, lt as sessionReconcileRequestSchema, m as agentRuntimeConfigPayloadSchema$1, mt as updateAgentRuntimeConfigSchema, n as AGENT_NAME_REGEX$1, ot as sessionCompletionMessageSchema, p as agentPinnedMessageSchema$1, pt as updateAdapterConfigSchema, q as onboardingEventSchema, r as AGENT_SELECTOR_HEADER$1, rt as selfServiceFeishuBotSchema, s as MENTION_REGEX, st as sessionEventMessageSchema, t as AGENT_BIND_REJECT_REASONS, tt as safeRedirectPath, u as addMeChatParticipantsSchema, ut as sessionStateMessageSchema, v as clientRegisterSchema, vt as updateMemberSchema, w as createChatSchema, x as createAdapterConfigSchema, y as connectTokenExchangeSchema, yt as updateOrganizationSchema, z as isOrgSettingNamespace } from "./dist-BwPlBZWi.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-CTkhS6p5.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-DL5vHhvQ-CnYGq2x-.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-h5l7mi0m-OEX7MOBg.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";
@@ -570,10 +570,15 @@ const runtimeStateSchema = z.enum([
 z.enum([
 	"active",
 	"suspended",
-	"evicted"
+	"evicted",
+	"errored"
 ]);
 /** Wire-level states a client may report. `evicted` from a stale client is rejected. */
-const clientSessionStateSchema = z.enum(["active", "suspended"]);
+const clientSessionStateSchema = z.enum([
+	"active",
+	"suspended",
+	"errored"
+]);
 z.object({
 	chatId: z.string().min(1),
 	state: clientSessionStateSchema
@@ -791,10 +796,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"]);
 /**
@@ -978,6 +980,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).
@@ -1358,14 +1399,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
@@ -1860,12 +1911,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" }),
@@ -1966,6 +2027,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;
@@ -2087,7 +2216,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;
@@ -3178,8 +3358,26 @@ function normalizePath(rawPath) {
 function shortHash(input) {
 	return createHash("sha256").update(input).digest("hex").slice(0, 8);
 }
-function deriveSessionBranchName(sessionKey, url) {
-	return `${SESSION_BRANCH_PREFIX}-${shortHash(sessionKey)}-${shortHash(url)}`;
+/**
+* Branch name a session's worktree attaches to. The hash inputs include the
+* agent dimension because `(chat, url)` alone is not unique: two agents that
+* share a chat each open their own worktree at
+* `<workspaces>/<agent>/<chatId>/...`, and git refuses to point two worktrees
+* at the same branch (`fatal: '<branch>' is already used by worktree at …`).
+* Hash inputs are joined with `:` so `(chatA, agentB)` cannot collide with
+* `(chatAB, "")`.
+*
+* The caller picks `agentName`. Prefer the operator-stable name
+* (`config.yaml::agents.<name>`); fall back to `agent.agentId` (a UUID,
+* globally unique) when the stable name isn't available. Anything stable
+* across `start` and `resume` for the same `(agent, chat)` pair will do —
+* the contract is "no collision with a peer agent in the same chat", not
+* "human-readable in the branch name".
+*
+* See docs/workspace-session-branch-collision-fix-design.md §3.2.
+*/
+function deriveSessionBranchName(sessionKey, agentName, url) {
+	return `${SESSION_BRANCH_PREFIX}-${shortHash(`${sessionKey}:${agentName}`)}-${shortHash(url)}`;
 }
 /**
 * A value is SHA-like when it's a 7–40 character hex string. Used to decide
@@ -3591,12 +3789,12 @@ function createGitMirrorManager(opts) {
 				}
 			});
 		},
-		createWorktree({ url, ref, targetPath, sessionKey }) {
+		createWorktree({ url, ref, targetPath, sessionKey, agentName }) {
 			return withUrlLock(url, async () => {
 				const mirror = mirrorDir(url);
 				if (!existsSync(join(mirror, "HEAD"))) throw new GitMirrorError(`Cannot create worktree — no mirror exists for "${url}"`);
 				const absTarget = resolve(targetPath);
-				const branchName = deriveSessionBranchName(sessionKey, url);
+				const branchName = deriveSessionBranchName(sessionKey, agentName, url);
 				if (existsSync(absTarget) && !isHubManagedWorktree(absTarget)) {
 					log?.warn({
 						gitUrl: url,
@@ -3937,15 +4135,53 @@ var InputController = class {
 };
 const DEFAULT_WORKSPACE_TTL_MS = 10080 * 60 * 1e3;
 /**
+* Sentinel that flags "stage-2 of session bootstrap (git worktree
+* materialisation) completed successfully". Distinct from the
+* `FIRST_TREE_WORKSPACE_MARKER` (`.first-tree-workspace`) which is the
+* "agent workspace boundary" — Codex's `project_root_markers` uses that one
+* to stop walking up the filesystem when looking for `AGENTS.md`. Splitting
+* the two so the boundary marker can be written eagerly (stage 1) while the
+* completion sentinel only appears after stage 2 lets `acquireWorkspace`
+* detect half-baked directories from a previous failed start and self-heal.
+*
+* See docs/workspace-session-branch-collision-fix-design.md §3.4.
+*/
+const INIT_COMPLETE_SENTINEL_REL = join(".agent", "init-complete");
+/**
 * Acquire a per-chat workspace directory.
-* Creates the directory if it does not exist; returns the path if it does.
+*
+* Healing rule: if the directory exists AND carries the boundary marker
+* (`.first-tree-workspace`, written in stage 1) AND is missing the
+* completion sentinel (`.agent/init-complete`, written after stage 2), the
+* previous session start crashed between the two writes — wipe it so the
+* fresh start gets a clean slate. The boundary marker alone (without the
+* sentinel) is the unambiguous shape of a half-baked workspace: only stage 1
+* writes it, and only stage 2 writes the sentinel.
 */
 function acquireWorkspace(workspaceRoot, chatId) {
 	const dir = join(workspaceRoot, chatId);
+	if (existsSync(dir) && existsSync(join(dir, ".first-tree-workspace")) && !existsSync(join(dir, INIT_COMPLETE_SENTINEL_REL))) rmSync(dir, {
+		recursive: true,
+		force: true
+	});
 	mkdirSync(dir, { recursive: true });
 	return dir;
 }
 /**
+* Write the stage-2 completion sentinel. Callers must invoke this AFTER all
+* pre-handler-spawn setup (workspace bootstrap, git worktrees, first-tree
+* integration) succeeded, so a process that crashes earlier leaves a
+* half-baked workspace the next acquireWorkspace can heal.
+*/
+function markWorkspaceInitComplete(workspaceCwd) {
+	const path = join(workspaceCwd, INIT_COMPLETE_SENTINEL_REL);
+	mkdirSync(join(workspaceCwd, ".agent"), { recursive: true });
+	writeFileSync(path, JSON.stringify({
+		completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		schemaVersion: 1
+	}), "utf-8");
+}
+/**
 * Clean stale workspace directories for an agent.
 *
 * A workspace is considered stale when:
@@ -4689,12 +4925,13 @@ const createClaudeCodeHandler = (config) => {
 			const mirror = await gitMirrorManager.ensureMirror(repo.url);
 			if (mirror.cloned) sessionCtx.log(`Git: cloned ${repo.url} in ${mirror.elapsedMs}ms`);
 			await gitMirrorManager.fetchMirror(repo.url);
+			const branchAgentKey = agentName ?? sessionCtx.agent.agentId;
 			if (existsSync(targetPath) && isHubWorktreeMarker(targetPath)) {
 				sessionCtx.log(`Git: reusing existing worktree at ${localPath}`);
 				ownedWorktrees.push({
 					url: repo.url,
 					path: targetPath,
-					branchName: deriveSessionBranchName(sessionCtx.chatId, repo.url)
+					branchName: deriveSessionBranchName(sessionCtx.chatId, branchAgentKey, repo.url)
 				});
 				continue;
 			}
@@ -4702,7 +4939,8 @@ const createClaudeCodeHandler = (config) => {
 				url: repo.url,
 				ref: repo.ref,
 				targetPath,
-				sessionKey: sessionCtx.chatId
+				sessionKey: sessionCtx.chatId,
+				agentName: branchAgentKey
 			});
 			ownedWorktrees.push({
 				url: repo.url,
@@ -4751,6 +4989,7 @@ const createClaudeCodeHandler = (config) => {
 			runBootstrap(cwd, sessionCtx);
 			const payload = agentConfigCache?.get(sessionCtx.agent.agentId)?.payload;
 			await prepareGitWorktrees(cwd, payload, sessionCtx);
+			markWorkspaceInitComplete(cwd);
 			sessionCtx.log(`Starting session (${claudeSessionId}), cwd=${cwd}, permissionMode=${config.permissionMode ?? "bypassPermissions"}`);
 			spawnQuery(claudeSessionId, sessionCtx);
 			const sdkMsg = await toSDKUserMessage(message, sessionCtx, claudeSessionId);
@@ -4763,9 +5002,10 @@ const createClaudeCodeHandler = (config) => {
 			claudeSessionId = sessionId;
 			retryCount = 0;
 			cwd = acquireWorkspace(workspaceRoot, sessionCtx.chatId);
-			if (!existsSync(join(cwd, ".agent", "identity.json"))) runBootstrap(cwd, sessionCtx);
+			if (!existsSync(join(cwd, INIT_COMPLETE_SENTINEL_REL))) runBootstrap(cwd, sessionCtx);
 			const payload = agentConfigCache?.get(sessionCtx.agent.agentId)?.payload;
 			await prepareGitWorktrees(cwd, payload, sessionCtx);
+			markWorkspaceInitComplete(cwd);
 			sessionCtx.log(`Resuming session (${sessionId}), cwd=${cwd}`);
 			spawnQuery(sessionId, sessionCtx, sessionId);
 			if (message) inputController?.push(await toSDKUserMessage(message, sessionCtx, sessionId));
@@ -4982,8 +5222,9 @@ const createCodexHandler = (config) => {
 	function toCodexInput(message, sessionCtx) {
 		return sessionCtx.formatInboundContent(message).then((text) => text);
 	}
-	async function prepareGitWorktrees(payload, workspaceCwd, chatId) {
+	async function prepareGitWorktrees(payload, workspaceCwd, sessionCtx) {
 		if (!gitMirrorManager) return;
+		const branchAgentKey = agentName ?? sessionCtx.agent.agentId;
 		for (const repo of payload.gitRepos) {
 			const localPath = repo.localPath ?? deriveRepoLocalPath(repo.url);
 			if (!localPath) continue;
@@ -4996,7 +5237,8 @@ const createCodexHandler = (config) => {
 					url: repo.url,
 					ref: repo.ref,
 					targetPath,
-					sessionKey: chatId
+					sessionKey: sessionCtx.chatId,
+					agentName: branchAgentKey
 				});
 				ownedWorktrees.push({
 					url: repo.url,
@@ -5238,7 +5480,8 @@ const createCodexHandler = (config) => {
 				}
 			});
 			ensureFirstTreeBinding(cwd, sessionCtx);
-			await prepareGitWorktrees(payload, cwd, sessionCtx.chatId);
+			await prepareGitWorktrees(payload, cwd, sessionCtx);
+			markWorkspaceInitComplete(cwd);
 			codex = new Codex({
 				env: buildEnv(sessionCtx),
 				config: buildCodexConfig(payload)
@@ -5262,7 +5505,7 @@ const createCodexHandler = (config) => {
 				env: [],
 				gitRepos: []
 			};
-			if (!existsSync(join(cwd, ".agent", "identity.json"))) {
+			if (!existsSync(join(cwd, INIT_COMPLETE_SENTINEL_REL))) {
 				bootstrapWorkspace({
 					workspacePath: cwd,
 					identity: sessionCtx.agent,
@@ -5276,7 +5519,8 @@ const createCodexHandler = (config) => {
 				});
 				ensureFirstTreeBinding(cwd, sessionCtx);
 			}
-			await prepareGitWorktrees(payload, cwd, sessionCtx.chatId);
+			await prepareGitWorktrees(payload, cwd, sessionCtx);
+			markWorkspaceInitComplete(cwd);
 			codex = new Codex({
 				env: buildEnv(sessionCtx),
 				config: buildCodexConfig(payload)
@@ -5936,11 +6180,24 @@ var SessionManager = class {
 			this.persistRegistry();
 			this.notifySessionState(chatId, "active");
 		} catch (err) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			const phase = evicted ? "resume" : "start";
 			this.config.log.error({
 				chatId,
 				err,
-				phase: evicted ? "resume" : "start"
+				phase
 			}, "session start/resume failed");
+			this.notifySessionState(chatId, "errored");
+			try {
+				const preview = errMsg.slice(0, 800);
+				const userMsg = `⚠️ Session ${phase} failed (${this.config.agentIdentity.displayName ?? this.config.agentIdentity.agentId}): ${preview}`;
+				await ctx.forwardResult(userMsg);
+			} catch (forwardErr) {
+				this.config.log.warn({
+					chatId,
+					forwardErr
+				}, "session error forward failed");
+			}
 			this.sessions.delete(chatId);
 			this.sessionRuntimeStates.delete(chatId);
 			this.recomputeRuntimeState();
@@ -5972,11 +6229,25 @@ var SessionManager = class {
 			this.persistRegistry();
 			this.notifySessionState(entry.chatId, "active");
 		} catch (err) {
-			this.config.log.warn({
+			const errMsg = err instanceof Error ? err.message : String(err);
+			this.config.log.error({
 				chatId: entry.chatId,
 				err
 			}, "resume failed");
-			entry.status = "suspended";
+			this.notifySessionState(entry.chatId, "errored");
+			try {
+				const preview = errMsg.slice(0, 800);
+				const userMsg = `⚠️ Session resume failed (${this.config.agentIdentity.displayName ?? this.config.agentIdentity.agentId}): ${preview}`;
+				await ctx.forwardResult(userMsg);
+			} catch (forwardErr) {
+				this.config.log.warn({
+					chatId: entry.chatId,
+					forwardErr
+				}, "session error forward failed");
+			}
+			this.sessions.delete(entry.chatId);
+			this.sessionRuntimeStates.delete(entry.chatId);
+			this.recomputeRuntimeState();
 			this._activeCount--;
 		}
 	}
@@ -9151,7 +9422,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-CKGzIamp.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-DJm0EaZP.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 {
@@ -10364,7 +10635,7 @@ function createFeedbackHandler(config) {
 	return { handle };
 }
 //#endregion
-//#region ../server/dist/app-kJNM9Cf1.mjs
+//#region ../server/dist/app-BGjMcVXo.mjs
 var import_fastify_opentelemetry = /* @__PURE__ */ __toESM(require_fastify_opentelemetry(), 1);
 init_esm();
 var __defProp = Object.defineProperty;
@@ -10749,7 +11020,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}"`);
@@ -10775,7 +11046,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,
@@ -10789,7 +11060,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();
 	});
@@ -10805,6 +11076,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,
@@ -10866,6 +11138,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) => ({
@@ -11542,23 +11823,16 @@ async function findOrCreateChatForChannel(db, data) {
 			lifecyclePolicy: "adapter_managed",
 			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,
@@ -11569,14 +11843,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) {
@@ -13745,6 +14023,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({
@@ -13754,10 +14038,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,
@@ -13777,7 +14061,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,
@@ -13790,8 +14074,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)
@@ -13810,7 +14136,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)}`;
@@ -13818,47 +14144,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).
 *
-* 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 = {}) {
+* 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 tokenRes = await fetcher(TOKEN_URL, {
+	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")
+*
+* 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 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: config.clientId,
-			client_secret: config.clientSecret,
-			code,
-			redirect_uri: redirectUri
+			client_id: clientId,
+			client_secret: clientSecret,
+			grant_type: "refresh_token",
+			refresh_token: refreshToken
 		})
 	});
-	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 (!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: opts.clientId,
+			client_secret: opts.clientSecret,
+			code: opts.code,
+			redirect_uri: opts.redirectUri
+		})
+	});
+	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) {
@@ -13874,49 +14450,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) {
@@ -14048,6 +14761,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
@@ -14121,14 +14850,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
 	};
 }
@@ -14152,8 +14883,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.
@@ -14205,7 +14940,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
@@ -14213,15 +14956,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({
@@ -14231,22 +14974,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 });
@@ -14259,40 +15002,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);
@@ -14312,24 +15143,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);
@@ -14788,7 +15664,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) => {
@@ -14798,11 +15673,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);
 	});
@@ -14840,37 +15713,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);
@@ -16464,7 +17324,7 @@ async function healthzRoutes(app) {
 * `api/orgs/invitations.ts` (Class B, admin-gated).
 */
 async function publicInvitationRoutes(app) {
-	const { previewInvitation } = await import("./invitation-C299fxkP-Dts66QTU.mjs");
+	const { previewInvitation } = await import("./invitation-C299fxkP-jQiGR5fl.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);
@@ -16472,6 +17332,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`.
 *
@@ -16574,11 +17480,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 {
@@ -16586,6 +17500,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) {
@@ -16644,7 +17590,7 @@ async function meRoutes(app) {
 	*/
 	app.get("/me/pinned-agents", async (request) => {
 		const { userId } = requireUser(request);
-		const { listMyPinnedAgents } = await import("./client-DSM_opoz-BH5eegXb.mjs");
+		const { listMyPinnedAgents } = await import("./client-93HZWg84-MIPzQD9A.mjs");
 		return listMyPinnedAgents(app.db, { userId });
 	});
 	/**
@@ -16830,7 +17776,8 @@ async function orgActivityRoutes(app) {
 				activeSessions: a.activeSessions,
 				totalSessions: a.totalSessions,
 				runtimeUpdatedAt: a.runtimeUpdatedAt?.toISOString() ?? null,
-				type: "type" in a ? a.type : null
+				type: "type" in a ? a.type : null,
+				managedByMe: "managerId" in a ? a.managerId === scope.memberId : false
 			}))
 		};
 	});
@@ -17147,6 +18094,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.
 */
@@ -18028,7 +19063,7 @@ async function insertMappingIfAbsent(db, params) {
 *   - direct agent-only chats automatically get `mode=mention_only`
 *   - watcher rows are recomputed
 *   - a future addParticipant call would upgrade the chat to `group` via
-*     `maybeUpgradeDirectToGroup` instead of raw INSERT shortcuts
+*     the server's `changeChatType` service instead of raw INSERT shortcuts
 */
 async function createEntityChat(db, humanAgentId, delegateAgentId, entity, eventType, action) {
 	const metadata = chatMetadataSchema$1.parse({
@@ -18447,6 +19482,40 @@ const MENTION_ACTIONS = {
 	discussion_comment: ["created"],
 	commit_comment: ["created"]
 };
+/**
+* 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 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,
 	adapterChatMappings: () => adapterChatMappings,
@@ -18461,6 +19530,7 @@ var schema_exports = /* @__PURE__ */ __exportAll({
 	chatSubscriptions: () => chatSubscriptions,
 	chats: () => chats,
 	clients: () => clients,
+	githubAppInstallations: () => githubAppInstallations,
 	githubEntityChatMappings: () => githubEntityChatMappings,
 	inboxEntries: () => inboxEntries,
 	invitationRedemptions: () => invitationRedemptions,
@@ -19795,6 +20865,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,
@@ -19971,6 +21042,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" });