@agent-team-foundation/first-tree-hub 0.10.1 → 0.10.3

package/dist/{core-BgiFGT7Y.mjs → saas-connect-3p-vBkuY.mjs}

@@ -1,7 +1,8 @@
 import { m as __toESM } from "./esm-CYu4tXXn.mjs";
-import { _ as withSpan, a as endWsConnectionSpan, b as require_pino, c as messageAttrs, d as rootLogger$1, g as startWsConnectionSpan, i as currentTraceId, n as applyLoggerConfig, o as getFastifyOtelPlugin, p as setWsConnectionAttrs, r as createLogger$1, t as adapterAttrs, u as observabilityPlugin, v as withWsMessageSpan, y as FIRST_TREE_HUB_ATTR } from "./observability-DV_fQKqV-oxfXX6Z2.mjs";
-import { C as serverConfigSchema, S as resolveConfigReadonly, _ as loadAgents, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, v as migrateLegacyHome, w as setConfigValue } from "./bootstrap-CtVqQA8a.mjs";
-import { $ as sessionEventMessageSchema, A as createChatSchema, B as isReservedAgentName$1, C as agentRuntimeConfigPayloadSchema$1, D as createAdapterConfigSchema, E as connectTokenExchangeSchema, F as dryRunAgentRuntimeConfigSchema, G as paginationQuerySchema, H as loginSchema, I as extractMentions, J as scanMentionTokens, K as refreshTokenSchema, L as imageInlineContentSchema, M as createOrganizationSchema, N as createTaskSchema, O as createAdapterMappingSchema, P as delegateFeishuUserSchema, Q as sessionCompletionMessageSchema, R as inboxPollQuerySchema, S as agentPinnedMessageSchema$1, T as clientRegisterSchema, U as messageSourceSchema$1, V as linkTaskChatSchema, W as notificationQuerySchema, X as sendMessageSchema, Y as selfServiceFeishuBotSchema, Z as sendToAgentSchema, _ as WS_AUTH_FRAME_TIMEOUT_MS, a as AGENT_NAME_REGEX$1, at as updateAgentRuntimeConfigSchema, b as adminUpdateTaskSchema, c as AGENT_STATUSES, ct as updateMemberSchema, d as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, dt as updateTaskStatusSchema, et as sessionEventSchema$1, f as SYSTEM_CONFIG_DEFAULTS, ft as wsAuthFrameSchema, g as TASK_TERMINAL_STATUSES, h as TASK_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as updateAdapterConfigSchema, j as createMemberSchema, k as createAgentSchema, l as AGENT_TYPES, lt as updateOrganizationSchema, m as TASK_HEALTH_SIGNALS, nt as sessionStateMessageSchema, o as AGENT_SELECTOR_HEADER$1, ot as updateAgentSchema, p as TASK_CREATOR_TYPES, q as runtimeStateMessageSchema, rt as taskListQuerySchema, s as AGENT_SOURCES, st as updateChatSchema, tt as sessionReconcileRequestSchema, u as AGENT_VISIBILITY, ut as updateSystemConfigSchema, v as addParticipantSchema, w as agentTypeSchema$1, x as agentBindRequestSchema, y as adminCreateTaskSchema, z as isRedactedEnvValue } from "./feishu-DEmwoNn_.mjs";
+import { _ as withSpan, a as endWsConnectionSpan, b as require_pino, c as messageAttrs, d as rootLogger$1, g as startWsConnectionSpan, i as currentTraceId, n as applyLoggerConfig, o as getFastifyOtelPlugin, p as setWsConnectionAttrs, r as createLogger$1, t as adapterAttrs, u as observabilityPlugin, v as withWsMessageSpan, y as FIRST_TREE_HUB_ATTR } from "./observability-DPyf745N-BSc8QNcR.mjs";
+import { C as serverConfigSchema, S as resolveConfigReadonly, _ as loadAgents, b as resetConfig, c as saveCredentials, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, v as migrateLegacyHome, w as setConfigValue, x as resetConfigMeta } from "./bootstrap-CBAVWQUT.mjs";
+import { $ as safeRedirectPath, A as createOrgFromMeSchema, B as imageInlineContentSchema, C as clientRegisterSchema, D as createAgentSchema, E as createAdapterMappingSchema, F as dryRunAgentRuntimeConfigSchema, G as linkTaskChatSchema, H as isRedactedEnvValue, I as extractMentions, J as notificationQuerySchema, K as loginSchema, L as githubCallbackQuerySchema, M as createTaskSchema, N as defaultRuntimeConfigPayload, O as createChatSchema, P as delegateFeishuUserSchema, Q as runtimeStateMessageSchema, R as githubDevCallbackQuerySchema, S as clientCapabilitiesSchema$1, T as createAdapterConfigSchema, U as isReservedAgentName$1, V as inboxPollQuerySchema, W as joinByInvitationSchema, X as rebindAgentSchema, Y as paginationQuerySchema, Z as refreshTokenSchema, _ as adminUpdateTaskSchema, _t as updateOrganizationSchema, a as AGENT_STATUSES, at as sessionEventMessageSchema, b as agentRuntimeConfigPayloadSchema$1, bt as wsAuthFrameSchema, ct as sessionStateMessageSchema, d as TASK_HEALTH_SIGNALS, dt as updateAdapterConfigSchema, et as scanMentionTokens, f as TASK_STATUSES, ft as updateAgentRuntimeConfigSchema, g as adminCreateTaskSchema, gt as updateMemberSchema, h as addParticipantSchema, ht as updateClientCapabilitiesSchema, i as AGENT_SOURCES, it as sessionCompletionMessageSchema, j as createOrganizationSchema, k as createMemberSchema, l as SYSTEM_CONFIG_DEFAULTS, lt as switchOrgSchema, m as WS_AUTH_FRAME_TIMEOUT_MS, mt as updateChatSchema, n as AGENT_NAME_REGEX$1, nt as sendMessageSchema, o as AGENT_TYPES, ot as sessionEventSchema$1, p as TASK_TERMINAL_STATUSES, pt as updateAgentSchema, q as messageSourceSchema$1, r as AGENT_SELECTOR_HEADER$1, rt as sendToAgentSchema, s as AGENT_VISIBILITY, st as sessionReconcileRequestSchema, t as AGENT_BIND_REJECT_REASONS, tt as selfServiceFeishuBotSchema, u as TASK_CREATOR_TYPES, ut as taskListQuerySchema, v as agentBindRequestSchema, vt as updateSystemConfigSchema, w as connectTokenExchangeSchema, x as agentTypeSchema$1, y as agentPinnedMessageSchema$1, yt as updateTaskStatusSchema, z as githubStartQuerySchema } from "./dist-DUCelK3Z.mjs";
+import { a as ForbiddenError, c as buildInviteUrl, d as getActiveInvitation, f as invitationRedemptions, g as recordRedemption, i as ConflictError, l as ensureActiveInvitation, m as organizations, n as BadRequestError, o as NotFoundError, p as invitations, r as ClientOrgMismatchError$1, s as UnauthorizedError, t as AppError, u as findActiveByToken, v as users, y as uuidv7 } from "./invitation-C_zAhB8x-8Khychlu.mjs";
 import { createRequire } from "node:module";
 import { ZodError, z } from "zod";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
@@ -15,20 +16,21 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { parse, stringify } from "yaml";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
+import { Codex } from "@openai/codex-sdk";
+import { fileURLToPath } from "node:url";
 import * as semver from "semver";
 import bcrypt from "bcrypt";
 import { and, asc, count, desc, eq, gt, inArray, isNotNull, isNull, lt, ne, or, sql } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import { confirm, input, password, select } from "@inquirer/prompts";
-import { fileURLToPath } from "node:url";
 import { migrate } from "drizzle-orm/postgres-js/migrator";
+import { bigserial, boolean, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique, uniqueIndex } from "drizzle-orm/pg-core";
 import cors from "@fastify/cors";
 import rateLimit from "@fastify/rate-limit";
 import fastifyStatic from "@fastify/static";
 import websocket from "@fastify/websocket";
 import Fastify from "fastify";
-import { bigserial, boolean, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique, uniqueIndex } from "drizzle-orm/pg-core";
 import { SignJWT, jwtVerify } from "jose";
 import { Client, EventDispatcher, LoggerLevel, WSClient } from "@larksuiteoapi/node-sdk";
 //#region ../client/dist/observability-B4kO005X.mjs
@@ -392,7 +394,8 @@ z.enum([
 	"not_owned",
 	"agent_suspended",
 	"wrong_org",
-	"unknown_agent"
+	"unknown_agent",
+	"runtime_provider_mismatch"
 ]);
 /** Header used on agent-scoped HTTP calls to select which managed agent the JWT acts as. */
 const AGENT_SELECTOR_HEADER = "x-agent-id";
@@ -420,6 +423,7 @@ z.object({
 	}),
 	clients: z.number().int()
 });
+const runtimeProviderSchema = z.enum(["claude-code", "codex"]);
 const agentTypeSchema = z.enum([
 	"human",
 	"personal_assistant",
@@ -461,7 +465,8 @@ z.object({
 	visibility: agentVisibilitySchema.optional(),
 	metadata: z.record(z.string(), z.unknown()).optional(),
 	managerId: z.string().optional(),
-	clientId: z.string().min(1).max(100).optional()
+	clientId: z.string().min(1).max(100).optional(),
+	runtimeProvider: runtimeProviderSchema.optional()
 });
 z.object({
 	type: agentTypeSchema.optional(),
@@ -472,6 +477,11 @@ z.object({
 	managerId: z.string().nullable().optional(),
 	clientId: z.string().min(1).max(100).nullable().optional()
 });
+z.object({
+	clientId: z.string().min(1).max(100),
+	runtimeProvider: runtimeProviderSchema,
+	force: z.boolean().optional()
+});
 z.object({
 	uuid: z.string(),
 	name: z.string().nullable(),
@@ -486,6 +496,7 @@ z.object({
 	metadata: z.record(z.string(), z.unknown()),
 	managerId: z.string().nullable(),
 	clientId: z.string().nullable(),
+	runtimeProvider: runtimeProviderSchema,
 	presenceStatus: presenceStatusSchema.optional(),
 	createdAt: z.string(),
 	updatedAt: z.string()
@@ -505,14 +516,16 @@ const agentPinnedMessageSchema = z.object({
 	agentId: z.string(),
 	name: z.string().nullable(),
 	displayName: z.string(),
-	agentType: agentTypeSchema
+	agentType: agentTypeSchema,
+	runtimeProvider: runtimeProviderSchema
 });
 /**
-* Agent runtime configuration — M1 (Claude Code only).
+* Agent runtime configuration.
 *
 * Defines the 5 user-tunable field groups that the Hub centrally manages
 * and pushes down to the client runtime: prompt append, model, MCP servers,
-* env vars, and Git repos.
+* env vars, and Git repos. Tagged by `kind` (a runtime provider) so future
+* provider-specific fields can land on a dedicated variant.
 *
 * NOTE: do not co-locate with `packages/shared/src/config/` — that namespace
 * is reserved for the local YAML config (`agent.yaml` / server / client) and
@@ -556,9 +569,11 @@ const gitRepoSchema = z.object({
 	localPath: z.string().min(1).optional()
 });
 /**
-* Base shape (no refinements) — used for `.partial()` derivations such as the
-* PATCH payload schema. Zod 4 forbids `.partial()` on a refined object, so we
-* keep refinements on a separate full schema below.
+* Untagged base shape — 5 user-tunable fields, no `kind` discriminator.
+* Used for `.partial()` derivations on the PATCH side, where `kind` is
+* pinned to `agents.runtime_provider` and never changes via config PATCH.
+* Zod 4 forbids `.partial()` on a refined object, so we keep refinements
+* on the tagged schema below.
 */
 const agentRuntimeConfigPayloadShape = z.object({
 	prompt: promptConfigSchema.default({ append: "" }),
@@ -567,6 +582,17 @@ const agentRuntimeConfigPayloadShape = z.object({
 	env: z.array(envEntrySchema).default([]),
 	gitRepos: z.array(gitRepoSchema).default([])
 });
+/**
+* Tagged variants — read-side, full payload including `kind`. Adding a new
+* provider means adding a variant here, plus a handler factory and a
+* capability probe module on the client side.
+*
+* Provider-specific fields (e.g. codex `sandboxMode`) belong on the
+* matching variant, not on the base shape.
+*/
+const claudeRuntimeConfigPayloadShape = agentRuntimeConfigPayloadShape.extend({ kind: z.literal("claude-code") });
+const codexRuntimeConfigPayloadShape = agentRuntimeConfigPayloadShape.extend({ kind: z.literal("codex") });
+const taggedPayloadUnion = z.discriminatedUnion("kind", [claudeRuntimeConfigPayloadShape, codexRuntimeConfigPayloadShape]);
 const payloadDuplicatesRefinement = (payload, ctx) => {
 	const seenMcp = /* @__PURE__ */ new Set();
 	payload.mcpServers.forEach((server, idx) => {
@@ -611,7 +637,21 @@ const payloadDuplicatesRefinement = (payload, ctx) => {
 		seenPaths.add(path);
 	});
 };
-const agentRuntimeConfigPayloadSchema = agentRuntimeConfigPayloadShape.superRefine(payloadDuplicatesRefinement);
+/**
+* Read-side full payload schema. Rows persisted before 0026 do not carry
+* `kind`; `z.preprocess` injects `"claude-code"` so they parse cleanly into
+* the claude variant. The service layer separately enforces
+* `payload.kind === agents.runtime_provider` on writes.
+*/
+const agentRuntimeConfigPayloadSchema = z.preprocess((input) => {
+	if (input && typeof input === "object" && !Array.isArray(input) && !("kind" in input)) return {
+		...input,
+		kind: "claude-code"
+	};
+	return input;
+}, taggedPayloadUnion).superRefine((payload, ctx) => {
+	payloadDuplicatesRefinement(payload, ctx);
+});
 const agentRuntimeConfigSchema = z.object({
 	agentId: z.string(),
 	version: z.number().int().positive(),
@@ -720,6 +760,37 @@ z.object({
 	os: z.string().max(50).optional(),
 	sdkVersion: z.string().max(50).optional()
 });
+const capabilityStateSchema = z.enum([
+	"ok",
+	"missing",
+	"unauthenticated",
+	"error"
+]);
+const capabilityAuthMethodSchema = z.enum([
+	"api_key",
+	"oauth",
+	"auth_json",
+	"none"
+]);
+const capabilityEntrySchema = z.object({
+	state: capabilityStateSchema,
+	available: z.boolean(),
+	authenticated: z.boolean(),
+	sdkVersion: z.string().nullable().optional(),
+	authMethod: capabilityAuthMethodSchema,
+	error: z.string().nullable().optional(),
+	detectedAt: z.string()
+});
+/**
+* Capabilities snapshot keyed by runtime provider name. Recorded as a plain
+* `Record<string, CapabilityEntry>` — every entry is optional (a client may
+* report only the runtimes it actually probed) and the key set evolves
+* naturally as new providers ship without a schema migration. Service-layer
+* lookups (`agents.runtime_provider ∈ keys(capabilities)`) treat the keys
+* as `RuntimeProvider` strings.
+*/
+const clientCapabilitiesSchema = z.record(z.string(), capabilityEntrySchema);
+z.object({ capabilities: clientCapabilitiesSchema });
 z.object({
 	limit: z.coerce.number().int().min(1).max(100).default(20),
 	cursor: z.string().optional()
@@ -897,6 +968,39 @@ z.object({
 	ackedAt: z.string().nullable()
 }).extend({ message: clientMessageSchema });
 z.object({ limit: z.coerce.number().int().min(1).max(50).default(10) });
+z.object({
+	organizationId: z.string(),
+	organizationName: z.string(),
+	organizationDisplayName: z.string(),
+	role: z.string()
+});
+z.object({
+	id: z.string(),
+	organizationId: z.string(),
+	token: z.string(),
+	inviteUrl: z.string(),
+	role: z.string(),
+	createdAt: z.string(),
+	expiresAt: z.string().nullable()
+});
+z.object({ token: z.string().min(1) });
+z.object({}).optional();
+z.enum([
+	"connect",
+	"create_agent",
+	"completed"
+]);
+z.object({
+	id: z.string(),
+	name: z.string(),
+	displayName: z.string(),
+	role: z.enum(["admin", "member"])
+});
+z.object({
+	name: z.string().min(2).max(50).regex(/^[a-z0-9][a-z0-9-]*$/),
+	displayName: z.string().min(1).max(200)
+});
+z.object({ organizationId: z.string().min(1) });
 const memberRoleSchema = z.enum(["admin", "member"]);
 const memberSchema = z.object({
 	id: z.string(),
@@ -953,6 +1057,18 @@ z.object({
 	read: z.enum(["true", "false"]).transform((v) => v === "true").optional(),
 	agentId: z.string().optional()
 });
+z.object({ next: z.string().max(256).optional() });
+z.object({
+	code: z.string().min(1),
+	state: z.string().min(1)
+});
+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()
+});
 const UUID_PATTERN$1 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 z.object({
 	name: z.string().min(2).max(50).regex(/^[a-z0-9][a-z0-9-]*$/, "Must start with a letter or digit and contain only lowercase alphanumeric and hyphens").refine((v) => !UUID_PATTERN$1.test(v), "Name must not be a UUID format"),
@@ -1330,7 +1446,8 @@ defineConfig({
 	},
 	server: {
 		port: field(z.number().default(8e3), { env: "FIRST_TREE_HUB_PORT" }),
-		host: field(z.string().default("127.0.0.1"), { env: "FIRST_TREE_HUB_HOST" })
+		host: field(z.string().default("127.0.0.1"), { env: "FIRST_TREE_HUB_HOST" }),
+		publicUrl: field(z.string().optional(), { env: "FIRST_TREE_HUB_PUBLIC_URL" })
 	},
 	secrets: {
 		jwtSecret: field(z.string(), {
@@ -1358,6 +1475,13 @@ defineConfig({
 		}),
 		allowedOrg: field(z.string().optional(), { env: "FIRST_TREE_HUB_GITHUB_ALLOWED_ORG" })
 	},
+	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",
+			secret: true
+		})
+	}) }),
 	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
 	rateLimit: optional({
 		max: field(z.number().default(100), { env: "FIRST_TREE_HUB_RATE_LIMIT_MAX" }),
@@ -1481,6 +1605,25 @@ var FirstTreeHubSDK = class {
 	async fetchAgentConfig() {
 		return this.requestJson("/api/v1/agent/config");
 	}
+	/**
+	* Member-scoped: report this client's runtime-provider capabilities. The
+	* server stores them under `clients.metadata.capabilities` after checking
+	* that the connected member owns the client.
+	*/
+	async updateCapabilities(clientId, capabilities) {
+		await this.requestVoid(`/api/v1/clients/${encodeURIComponent(clientId)}/capabilities`, {
+			method: "PATCH",
+			body: JSON.stringify({ capabilities })
+		});
+	}
+	/**
+	* Member-scoped: every agent pinned to a client owned by the calling user.
+	* Used by client startup to reconcile the local `agent.yaml::runtime` with
+	* the authoritative `agents.runtime_provider` before spawning handlers.
+	*/
+	async listMyAgents() {
+		return this.requestJson("/api/v1/clients/me/agents");
+	}
 	async isHubReachable(timeoutMs = 3e3) {
 		try {
 			const url = `${this._baseUrl}/api/v1/health`;
@@ -1576,7 +1719,7 @@ var SdkError = class extends Error {
 * different organization. The CLI layer detects this via `instanceof` and
 * prompts the user before rotating the local clientId.
 */
-var ClientOrgMismatchError$1 = class extends Error {
+var ClientOrgMismatchError = class extends Error {
 	code = "CLIENT_ORG_MISMATCH";
 	constructor(message = "Client belongs to a different organization") {
 		super(message);
@@ -1886,7 +2029,7 @@ var ClientConnection = class extends EventEmitter {
 			const code = typeof msg.code === "string" ? msg.code : void 0;
 			const message = typeof msg.message === "string" ? msg.message : "unknown";
 			this.closing = true;
-			const err = code === "CLIENT_ORG_MISMATCH" ? new ClientOrgMismatchError$1(message) : /* @__PURE__ */ new Error(`client:register rejected: ${message}`);
+			const err = code === "CLIENT_ORG_MISMATCH" ? new ClientOrgMismatchError(message) : /* @__PURE__ */ new Error(`client:register rejected: ${message}`);
 			this.lastHandshakeError = err;
 			this.wsLogger.error({
 				code,
@@ -2120,13 +2263,23 @@ function getHandlerFactory(type) {
 }
 join(DEFAULT_DATA_DIR, "context-tree");
 /**
-* Bootstrap a workspace with .agent/ directory files.
+* Marker file written into every workspace so the Codex CLI's project-root
+* detection (configured via `project_root_markers: ["first-tree-workspace"]`)
+* stops at the workspace boundary instead of walking up the filesystem and
+* loading an unintended `AGENTS.md` from the operator's home or repo root.
+*/
+const FIRST_TREE_WORKSPACE_MARKER = ".first-tree-workspace";
+/**
+* Bootstrap a workspace with `.agent/` directory files plus the workspace
+* root marker (and an optional provider-specific briefing).
 *
-* Writes identity.json, context/self.md (if context tree available), and tools.md.
-* Designed to be called on every handler start() and conditionally on resume().
+* Writes identity.json, context/agent-instructions.md (if context tree
+* available), tools.md, the `.first-tree-workspace` marker, and — for
+* Codex — `AGENTS.md`. Idempotent: safe to call on every handler start()
+* and on resume().
 */
 function bootstrapWorkspace(options) {
-	const { workspacePath, identity, contextTreePath, serverUrl, chatId } = options;
+	const { workspacePath, identity, contextTreePath, serverUrl, chatId, briefing } = options;
 	const agentDir = join(workspacePath, ".agent");
 	const contextDir = join(agentDir, "context");
 	if (existsSync(contextDir)) rmSync(contextDir, {
@@ -2152,6 +2305,8 @@ function bootstrapWorkspace(options) {
 		if (existsSync(rootNodePath)) copyFileSync(rootNodePath, join(contextDir, "domain-map.md"));
 	}
 	writeFileSync(join(agentDir, "tools.md"), generateToolsDoc(), "utf-8");
+	writeFileSync(join(workspacePath, FIRST_TREE_WORKSPACE_MARKER), "", "utf-8");
+	if (briefing?.format === "agents-md") writeFileSync(join(workspacePath, "AGENTS.md"), briefing.content, "utf-8");
 }
 function defaultInstallExec(command, args, options) {
 	execFileSync(command, args, {
@@ -2877,7 +3032,7 @@ function splitPathExt(pathext) {
 }
 const MAX_RETRIES = 2;
 const TOOL_RESULT_PREVIEW_LIMIT = 400;
-const ASSISTANT_TEXT_EVENT_LIMIT = 8e3;
+const ASSISTANT_TEXT_EVENT_LIMIT$1 = 8e3;
 const SUPPORTED_IMAGE_MIMES = new Set(SUPPORTED_IMAGE_MIMES$1);
 const MIME_TO_EXT = {
 	"image/png": "png",
@@ -3003,7 +3158,7 @@ function createToolCallProcessor(emit) {
 					if (text.length === 0) continue;
 					emit({
 						kind: "assistant_text",
-						payload: { text: text.slice(0, ASSISTANT_TEXT_EVENT_LIMIT) }
+						payload: { text: text.slice(0, ASSISTANT_TEXT_EVENT_LIMIT$1) }
 					});
 				} else if (isThinkingBlock(block)) emit({
 					kind: "thinking",
@@ -3547,6 +3702,457 @@ function generateClaudeMd(workspacePath, identity, contextTreePath) {
 	}
 	writeFileSync(join(workspacePath, "CLAUDE.md"), sections.join("\n"), "utf-8");
 }
+const ASSISTANT_TEXT_EVENT_LIMIT = 8e3;
+const RESULT_PREVIEW_LIMIT = 400;
+/**
+* Build the per-turn `ThreadOptions` Codex consumes. Exported so unit tests
+* can lock the auth-mode-friendly defaults (notably `model` only set when
+* the operator chose one).
+*/
+function buildCodexThreadOptions(payload, workspaceCwd) {
+	const additionalDirectories = [];
+	for (const repo of payload.gitRepos) {
+		const localPath = repo.localPath ?? deriveRepoLocalPath(repo.url);
+		if (!localPath) continue;
+		additionalDirectories.push(join(workspaceCwd, localPath));
+	}
+	const opts = {
+		workingDirectory: workspaceCwd,
+		skipGitRepoCheck: true,
+		sandboxMode: "workspace-write",
+		approvalPolicy: "never",
+		modelReasoningEffort: "high",
+		webSearchEnabled: false,
+		additionalDirectories
+	};
+	if (payload.model) opts.model = payload.model;
+	return opts;
+}
+/**
+* Codex Handler — session-oriented handler using `@openai/codex-sdk`.
+*
+* Each instance owns one Thread for one chat. Each turn is a fresh
+* `runStreamed()` call (Codex CLI is run-to-completion per turn). Inject
+* during an active turn buffers messages and runs them as a follow-up turn
+* the moment the current one completes.
+*
+* Key footguns observed end-to-end (private plan §10.7):
+*   - F1: providing `env` to Codex SDK does NOT inherit `process.env`; we
+*         explicitly merge.
+*   - F2: `resumeThread(id)` does NOT inherit `ThreadOptions`; we re-pass
+*         them every time.
+*   - F3: `modelReasoningEffort: "minimal"` is incompatible with default
+*         tools; we default to `"high"` with `webSearchEnabled: false`.
+*   - F6: `Thread` has no close/dispose — shutdown is exclusively
+*         `AbortController.abort()`.
+*/
+const createCodexHandler = (config) => {
+	const workspaceRoot = config.workspaceRoot;
+	const agentConfigCache = config.agentConfigCache ?? null;
+	const gitMirrorManager = config.gitMirrorManager ?? null;
+	const contextTreePath = config.contextTreePath ?? null;
+	let cwd = null;
+	let codex = null;
+	let thread = null;
+	let threadId = null;
+	let currentAbort = null;
+	let currentTurnPromise = null;
+	let ctx = null;
+	let drainScheduled = false;
+	const queuedMessages = [];
+	const ownedWorktrees = [];
+	function buildEnv(sessionCtx) {
+		const env = {};
+		for (const [k, v] of Object.entries(process.env)) if (typeof v === "string") env[k] = v;
+		const payload = agentConfigCache?.get(sessionCtx.agent.agentId)?.payload;
+		if (payload) for (const e of payload.env) env[e.key] = e.value;
+		const merged = sessionCtx.buildAgentEnv(env);
+		const out = {};
+		for (const [k, v] of Object.entries(merged)) if (typeof v === "string") out[k] = v;
+		return out;
+	}
+	function buildCodexConfig(payload) {
+		const cfg = { project_root_markers: [FIRST_TREE_WORKSPACE_MARKER] };
+		if (payload.mcpServers.length === 0) return cfg;
+		const mcpServers = {};
+		for (const m of payload.mcpServers) if (m.transport === "stdio") mcpServers[m.name] = {
+			command: m.command,
+			args: m.args ?? []
+		};
+		else {
+			const entry = { url: m.url };
+			if (m.headers) entry.headers = m.headers;
+			mcpServers[m.name] = entry;
+		}
+		cfg.mcp_servers = mcpServers;
+		return cfg;
+	}
+	function buildAgentBriefing(payload) {
+		const lines = [];
+		lines.push("# Agent Briefing");
+		lines.push("");
+		if (payload.prompt.append.trim()) {
+			lines.push(payload.prompt.append.trim());
+			lines.push("");
+		}
+		lines.push("Refer to `.agent/identity.json` for your agent identity, `.agent/tools.md` for the");
+		lines.push("first-tree-hub SDK reference, and `.agent/context/` for organisational context");
+		lines.push("(when configured).");
+		return lines.join("\n").concat("\n");
+	}
+	function toCodexInput(message, sessionCtx) {
+		return sessionCtx.formatInboundContent(message).then((text) => text);
+	}
+	async function prepareGitWorktrees(payload, workspaceCwd, chatId) {
+		if (!gitMirrorManager) return;
+		for (const repo of payload.gitRepos) {
+			const localPath = repo.localPath ?? deriveRepoLocalPath(repo.url);
+			if (!localPath) continue;
+			const targetPath = join(workspaceCwd, localPath);
+			if (existsSync(targetPath)) continue;
+			try {
+				await gitMirrorManager.ensureMirror(repo.url);
+				await gitMirrorManager.fetchMirror(repo.url);
+				const result = await gitMirrorManager.createWorktree({
+					url: repo.url,
+					ref: repo.ref,
+					targetPath,
+					sessionKey: chatId
+				});
+				ownedWorktrees.push({
+					url: repo.url,
+					path: targetPath,
+					branchName: result.branchName
+				});
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				ctx?.log(`codex git materialisation skipped (${repo.url}): ${msg}`);
+			}
+		}
+	}
+	function emitToolCall(sessionCtx, payload) {
+		const event = {
+			kind: "tool_call",
+			payload: {
+				toolUseId: payload.toolUseId,
+				name: payload.name,
+				args: payload.args,
+				status: payload.status,
+				...payload.resultPreview ? { resultPreview: payload.resultPreview.slice(0, RESULT_PREVIEW_LIMIT) } : {}
+			}
+		};
+		sessionCtx.emitEvent(event);
+	}
+	/**
+	* Translate one terminal `item.completed` payload into the runtime's event
+	* stream and, when the item is the assistant's final message, return the
+	* raw text so `runTurn` can stitch the per-turn reply together.
+	*/
+	function processItem(item, sessionCtx) {
+		switch (item.type) {
+			case "agent_message":
+				if (!item.text.trim()) return "";
+				sessionCtx.emitEvent({
+					kind: "assistant_text",
+					payload: { text: item.text.slice(0, ASSISTANT_TEXT_EVENT_LIMIT) }
+				});
+				return item.text;
+			case "command_execution": {
+				const status = item.status === "completed" ? "ok" : item.status === "failed" ? "error" : "pending";
+				emitToolCall(sessionCtx, {
+					toolUseId: item.id,
+					name: "command",
+					args: { command: item.command },
+					status,
+					resultPreview: item.aggregated_output
+				});
+				return "";
+			}
+			case "file_change": {
+				const status = item.status === "completed" ? "ok" : "error";
+				emitToolCall(sessionCtx, {
+					toolUseId: item.id,
+					name: "file_change",
+					args: { changes: item.changes },
+					status
+				});
+				return "";
+			}
+			case "mcp_tool_call": {
+				const status = item.status === "completed" ? "ok" : item.status === "failed" ? "error" : "pending";
+				const resultPreview = item.error ? `error: ${item.error.message}` : item.result ? JSON.stringify(item.result.structured_content ?? item.result.content) : void 0;
+				emitToolCall(sessionCtx, {
+					toolUseId: item.id,
+					name: `mcp:${item.server}/${item.tool}`,
+					args: item.arguments,
+					status,
+					resultPreview
+				});
+				return "";
+			}
+			case "web_search":
+				emitToolCall(sessionCtx, {
+					toolUseId: item.id,
+					name: "web_search",
+					args: { query: item.query },
+					status: "ok"
+				});
+				return "";
+			case "todo_list":
+				emitToolCall(sessionCtx, {
+					toolUseId: item.id,
+					name: "todo_list",
+					args: { items: item.items },
+					status: "ok"
+				});
+				return "";
+			case "reasoning":
+				sessionCtx.emitEvent({
+					kind: "thinking",
+					payload: {}
+				});
+				return "";
+			case "error":
+				sessionCtx.emitEvent({
+					kind: "error",
+					payload: {
+						source: "tool",
+						message: item.message
+					}
+				});
+				return "";
+			default: return "";
+		}
+	}
+	async function runTurn(input, sessionCtx) {
+		const activeThread = thread;
+		if (!activeThread) return;
+		const abort = new AbortController();
+		currentAbort = abort;
+		sessionCtx.setRuntimeState("working");
+		const assistantTexts = [];
+		let turnFailed = false;
+		const promise = (async () => {
+			try {
+				const streamed = await activeThread.runStreamed(input, { signal: abort.signal });
+				for await (const event of streamed.events) {
+					if (abort.signal.aborted) break;
+					sessionCtx.touch();
+					if (event.type === "thread.started") threadId = event.thread_id;
+					else if (event.type === "turn.started") {} else if (event.type === "item.completed") {
+						const text = processItem(event.item, sessionCtx);
+						if (text) assistantTexts.push(text);
+					} else if (event.type === "item.started" || event.type === "item.updated") {} else if (event.type === "turn.completed") {} else if (event.type === "turn.failed") {
+						turnFailed = true;
+						sessionCtx.emitEvent({
+							kind: "error",
+							payload: {
+								source: "sdk",
+								message: event.error.message
+							}
+						});
+					} else if (event.type === "error") sessionCtx.emitEvent({
+						kind: "error",
+						payload: {
+							source: "sdk",
+							message: event.message
+						}
+					});
+				}
+			} catch (err) {
+				if (abort.signal.aborted) return;
+				turnFailed = true;
+				const msg = err instanceof Error ? err.message : String(err);
+				sessionCtx.emitEvent({
+					kind: "error",
+					payload: {
+						source: "sdk",
+						message: msg
+					}
+				});
+			}
+		})();
+		currentTurnPromise = promise;
+		try {
+			await promise;
+		} finally {
+			currentAbort = null;
+			currentTurnPromise = null;
+		}
+		if (abort.signal.aborted) return;
+		const accumulated = assistantTexts.join("\n\n");
+		let forwardFailed = false;
+		if (accumulated.trim()) try {
+			await sessionCtx.forwardResult(accumulated);
+		} catch (err) {
+			forwardFailed = true;
+			const msg = err instanceof Error ? err.message : String(err);
+			sessionCtx.emitEvent({
+				kind: "error",
+				payload: {
+					source: "runtime",
+					message: `forwardResult failed: ${msg}`
+				}
+			});
+		}
+		const succeeded = !turnFailed && !forwardFailed;
+		sessionCtx.emitEvent({
+			kind: "turn_end",
+			payload: { status: succeeded ? "success" : "error" }
+		});
+		if (succeeded && accumulated.trim()) sessionCtx.reportSessionCompletion();
+		sessionCtx.setRuntimeState("idle");
+		if (queuedMessages.length > 0 && !drainScheduled) {
+			drainScheduled = true;
+			setImmediate(() => {
+				drainScheduled = false;
+				const drained = queuedMessages.splice(0);
+				if (drained.length === 0 || !ctx || !thread) return;
+				mergeAndRun(drained, ctx);
+			});
+		}
+	}
+	async function mergeAndRun(drained, sessionCtx) {
+		const inputs = [];
+		for (const m of drained) try {
+			inputs.push(await sessionCtx.formatInboundContent(m));
+		} catch (err) {
+			sessionCtx.log(`codex inject formatInboundContent failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (inputs.length === 0) return;
+		await runTurn(inputs.join("\n\n"), sessionCtx);
+	}
+	return {
+		async start(message, sessionCtx) {
+			ctx = sessionCtx;
+			cwd = await acquireWorkspace(workspaceRoot, sessionCtx.chatId);
+			let payload = null;
+			if (agentConfigCache) payload = (await agentConfigCache.refresh(sessionCtx.agent.agentId)).payload;
+			if (!payload) payload = {
+				kind: "codex",
+				prompt: { append: "" },
+				model: "",
+				mcpServers: [],
+				env: [],
+				gitRepos: []
+			};
+			bootstrapWorkspace({
+				workspacePath: cwd,
+				identity: sessionCtx.agent,
+				contextTreePath,
+				serverUrl: sessionCtx.sdk.serverUrl,
+				chatId: sessionCtx.chatId,
+				briefing: {
+					format: "agents-md",
+					content: buildAgentBriefing(payload)
+				}
+			});
+			await prepareGitWorktrees(payload, cwd, sessionCtx.chatId);
+			codex = new Codex({
+				env: buildEnv(sessionCtx),
+				config: buildCodexConfig(payload)
+			});
+			thread = codex.startThread(buildCodexThreadOptions(payload, cwd));
+			await runTurn(await toCodexInput(message, sessionCtx), sessionCtx);
+			if (!threadId) threadId = thread.id ?? null;
+			if (!threadId) throw new Error("codex did not assign a thread id during the first turn");
+			return threadId;
+		},
+		async resume(message, sessionId, sessionCtx) {
+			ctx = sessionCtx;
+			cwd = await acquireWorkspace(workspaceRoot, sessionCtx.chatId);
+			let payload = null;
+			if (agentConfigCache) payload = (await agentConfigCache.refresh(sessionCtx.agent.agentId)).payload;
+			if (!payload) payload = {
+				kind: "codex",
+				prompt: { append: "" },
+				model: "",
+				mcpServers: [],
+				env: [],
+				gitRepos: []
+			};
+			bootstrapWorkspace({
+				workspacePath: cwd,
+				identity: sessionCtx.agent,
+				contextTreePath,
+				serverUrl: sessionCtx.sdk.serverUrl,
+				chatId: sessionCtx.chatId,
+				briefing: {
+					format: "agents-md",
+					content: buildAgentBriefing(payload)
+				}
+			});
+			await prepareGitWorktrees(payload, cwd, sessionCtx.chatId);
+			codex = new Codex({
+				env: buildEnv(sessionCtx),
+				config: buildCodexConfig(payload)
+			});
+			thread = codex.resumeThread(sessionId, buildCodexThreadOptions(payload, cwd));
+			threadId = sessionId;
+			if (message) await runTurn(await toCodexInput(message, sessionCtx), sessionCtx);
+			return sessionId;
+		},
+		inject(message) {
+			if (currentTurnPromise) {
+				queuedMessages.push(message);
+				return;
+			}
+			const sessionCtx = ctx;
+			if (!sessionCtx || !thread) return;
+			(async () => {
+				try {
+					await runTurn(await toCodexInput(message, sessionCtx), sessionCtx);
+				} catch (err) {
+					sessionCtx.log(`codex inject failed: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			})();
+		},
+		async suspend() {
+			currentAbort?.abort();
+			try {
+				await currentTurnPromise;
+			} catch {}
+			currentAbort = null;
+			currentTurnPromise = null;
+			thread = null;
+			codex = null;
+		},
+		async shutdown() {
+			currentAbort?.abort();
+			try {
+				await currentTurnPromise;
+			} catch {}
+			currentAbort = null;
+			currentTurnPromise = null;
+			thread = null;
+			codex = null;
+			if (gitMirrorManager) {
+				for (const wt of ownedWorktrees) try {
+					await gitMirrorManager.removeWorktree({
+						url: wt.url,
+						path: wt.path,
+						branchName: wt.branchName
+					});
+				} catch (err) {
+					ctx?.log(`codex worktree cleanup failed (${wt.path}): ${err instanceof Error ? err.message : String(err)}`);
+				}
+				ownedWorktrees.length = 0;
+			}
+			if (cwd && existsSync(cwd)) try {
+				rmSync(cwd, {
+					recursive: true,
+					force: true
+				});
+			} catch (err) {
+				ctx?.log(`codex workspace cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			cwd = null;
+			threadId = null;
+			ctx = null;
+			queuedMessages.length = 0;
+		}
+	};
+};
 /** Register all built-in handlers. Call once at startup. */
 function registerBuiltinHandlers() {
 	const resolution = resolveClaudeCodeExecutable();
@@ -3556,6 +4162,7 @@ function registerBuiltinHandlers() {
 		...config,
 		claudeCodeExecutable: resolution.path
 	}));
+	registerHandler("codex", (config) => createCodexHandler(config));
 }
 function createAgentConfigCache(opts) {
 	const { sdk } = opts;
@@ -3590,6 +4197,7 @@ function createAgentConfigCache(opts) {
 					agentId,
 					version: 0,
 					payload: {
+						kind: "claude-code",
 						prompt: { append: "" },
 						model: "",
 						mcpServers: [],
@@ -4607,50 +5215,270 @@ var AgentSlot = class {
 	}
 };
 /**
-* Runtime-wide constants (Step 7 + Step 11).
-*
-* After Step 11 these values are fixed at code level — the previously
-* exposed `session.idle_timeout` / `session.max_sessions` / `concurrency`
-* fields in `agent.yaml` are dropped per PRD §D1 / §D15.
-*
-* Picked deliberately wide for M1 internal use; revisit when scale shows
-* a real bottleneck.
+* Top-level marker file Claude Code writes after a successful OAuth login.
+* Path is platform-agnostic (`~/.claude.json`); the access token itself lives
+* in the platform credential store (macOS Keychain entry "Claude Code-
+* credentials", or libsecret on Linux), so we treat the presence of an
+* `oauthAccount.accountUuid` field as the canonical "logged in" signal.
 */
-/** 8 hours — covers "leave it on overnight" usage without holding worktrees forever. */
-const IDLE_TIMEOUT_MS = 480 * 60 * 1e3;
-z.object({
-	idle_timeout: z.number().int().positive().optional(),
-	max_sessions: z.number().int().positive().optional()
-}).passthrough();
-const sessionConfigSchema = z.object({
-	idle_timeout: z.number().int().positive().default(IDLE_TIMEOUT_MS / 1e3),
-	max_sessions: z.number().int().positive().default(50),
-	reconcile_interval_seconds: z.number().int().min(30).max(3600).default(300)
-}).passthrough();
-const agentSlotConfigSchema = z.object({
-	agentId: z.string().min(1),
-	type: z.string().min(1),
-	session: sessionConfigSchema.prefault({}),
-	concurrency: z.number().int().positive().default(16)
-}).passthrough();
-z.object({
-	server: z.url().default("http://localhost:8000"),
-	agents: z.record(z.string(), agentSlotConfigSchema).refine((agents) => Object.keys(agents).length > 0, "At least one agent must be defined")
-});
+const CLAUDE_PROFILE_PATH = () => join(homedir(), ".claude.json");
+function hasClaudeOAuthAccount() {
+	try {
+		const path = CLAUDE_PROFILE_PATH();
+		if (!existsSync(path)) return false;
+		const raw = readFileSync(path, "utf-8");
+		const obj = JSON.parse(raw);
+		return typeof obj.oauthAccount?.accountUuid === "string" && obj.oauthAccount.accountUuid.length > 0;
+	} catch {
+		return false;
+	}
+}
+async function readSdkVersion$1() {
+	try {
+		let dir = dirname(fileURLToPath(await import.meta.resolve("@anthropic-ai/claude-agent-sdk")));
+		for (let depth = 0; depth < 8; depth += 1) {
+			const candidate = join(dir, "package.json");
+			if (existsSync(candidate)) {
+				const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+				if (pkg.name === "@anthropic-ai/claude-agent-sdk" && typeof pkg.version === "string") return pkg.version;
+			}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	} catch {}
+	return null;
+}
+function detectAuth$1() {
+	if (process.env.ANTHROPIC_API_KEY && process.env.ANTHROPIC_API_KEY.length > 0) return {
+		authenticated: true,
+		method: "api_key"
+	};
+	if (hasClaudeOAuthAccount()) return {
+		authenticated: true,
+		method: "oauth"
+	};
+	return {
+		authenticated: false,
+		method: "none"
+	};
+}
 /**
-* Version-drift decision flow. Install, prompt, and exit are delegated to
-* command-layer callbacks so the Client package stays free of CLI /
-* filesystem knowledge.
+* Probe whether the Claude Code runtime is usable on this machine.
+*
+* `state` is the authoritative field; `available` and `authenticated` are
+* derived booleans kept around for simple consumers (e.g. capability lookup
+* in service-layer guards).
 */
-var UpdateManager = class UpdateManager {
-	options;
-	connection;
-	welcomeListener;
-	updateInFlight = false;
-	quietGateTimer = null;
-	disposed = false;
-	/**
-	* Set when a standalone (unmanaged) executeUpdate reports `installed: true`
+async function probeClaudeCodeCapability() {
+	const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+	try {
+		let sdkPresent = false;
+		try {
+			await import("@anthropic-ai/claude-agent-sdk");
+			sdkPresent = true;
+		} catch {
+			sdkPresent = false;
+		}
+		if (!sdkPresent) return {
+			state: "missing",
+			available: false,
+			authenticated: false,
+			sdkVersion: null,
+			authMethod: "none",
+			detectedAt
+		};
+		const sdkVersion = await readSdkVersion$1();
+		const auth = detectAuth$1();
+		if (!auth.authenticated) return {
+			state: "unauthenticated",
+			available: true,
+			authenticated: false,
+			sdkVersion,
+			authMethod: "none",
+			detectedAt
+		};
+		return {
+			state: "ok",
+			available: true,
+			authenticated: true,
+			sdkVersion,
+			authMethod: auth.method,
+			detectedAt
+		};
+	} catch (err) {
+		return {
+			state: "error",
+			available: false,
+			authenticated: false,
+			sdkVersion: null,
+			authMethod: "none",
+			error: err instanceof Error ? err.message : String(err),
+			detectedAt
+		};
+	}
+}
+function codexAuthPath() {
+	return join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "auth.json");
+}
+async function readSdkVersion() {
+	try {
+		let dir = dirname(fileURLToPath(await import.meta.resolve("@openai/codex-sdk")));
+		for (let depth = 0; depth < 8; depth += 1) {
+			const candidate = join(dir, "package.json");
+			if (existsSync(candidate)) {
+				const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+				if (pkg.name === "@openai/codex-sdk" && typeof pkg.version === "string") return pkg.version;
+			}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	} catch {}
+	return null;
+}
+function detectAuth() {
+	if (process.env.CODEX_API_KEY && process.env.CODEX_API_KEY.length > 0) return {
+		authenticated: true,
+		method: "api_key"
+	};
+	if (existsSync(codexAuthPath())) return {
+		authenticated: true,
+		method: "auth_json"
+	};
+	return {
+		authenticated: false,
+		method: "none"
+	};
+}
+/**
+* Probe whether the OpenAI Codex runtime is usable on this machine.
+* Treats `~/.codex/auth.json` (set by `codex login`) as the canonical local
+* auth source; CODEX_API_KEY env shortcuts that for ephemeral use.
+*/
+async function probeCodexCapability() {
+	const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+	try {
+		let sdkPresent = false;
+		try {
+			await import("@openai/codex-sdk");
+			sdkPresent = true;
+		} catch {
+			sdkPresent = false;
+		}
+		if (!sdkPresent) return {
+			state: "missing",
+			available: false,
+			authenticated: false,
+			sdkVersion: null,
+			authMethod: "none",
+			detectedAt
+		};
+		const sdkVersion = await readSdkVersion();
+		const auth = detectAuth();
+		if (!auth.authenticated) return {
+			state: "unauthenticated",
+			available: true,
+			authenticated: false,
+			sdkVersion,
+			authMethod: "none",
+			detectedAt
+		};
+		return {
+			state: "ok",
+			available: true,
+			authenticated: true,
+			sdkVersion,
+			authMethod: auth.method,
+			detectedAt
+		};
+	} catch (err) {
+		return {
+			state: "error",
+			available: false,
+			authenticated: false,
+			sdkVersion: null,
+			authMethod: "none",
+			error: err instanceof Error ? err.message : String(err),
+			detectedAt
+		};
+	}
+}
+/**
+* Run every built-in capability probe and aggregate the results.
+*
+* Each provider gets its own module under this directory; the orchestrator
+* is intentionally simple — adding a new provider means importing the new
+* probe here and registering its key. The probe modules themselves are
+* deliberately not part of the `HandlerFactory` interface so capability
+* detection stays decoupled from runtime instantiation (so we can probe
+* whether a runtime is usable before spawning anything).
+*/
+async function probeCapabilities() {
+	const probes = [["claude-code", probeClaudeCodeCapability()], ["codex", probeCodexCapability()]];
+	const out = {};
+	await Promise.all(probes.map(async ([provider, p]) => {
+		try {
+			out[provider] = await p;
+		} catch (err) {
+			out[provider] = {
+				state: "error",
+				available: false,
+				authenticated: false,
+				sdkVersion: null,
+				authMethod: "none",
+				error: err instanceof Error ? err.message : String(err),
+				detectedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+		}
+	}));
+	return out;
+}
+/**
+* Runtime-wide constants (Step 7 + Step 11).
+*
+* After Step 11 these values are fixed at code level — the previously
+* exposed `session.idle_timeout` / `session.max_sessions` / `concurrency`
+* fields in `agent.yaml` are dropped per PRD §D1 / §D15.
+*
+* Picked deliberately wide for M1 internal use; revisit when scale shows
+* a real bottleneck.
+*/
+/** 8 hours — covers "leave it on overnight" usage without holding worktrees forever. */
+const IDLE_TIMEOUT_MS = 480 * 60 * 1e3;
+z.object({
+	idle_timeout: z.number().int().positive().optional(),
+	max_sessions: z.number().int().positive().optional()
+}).passthrough();
+const sessionConfigSchema = z.object({
+	idle_timeout: z.number().int().positive().default(IDLE_TIMEOUT_MS / 1e3),
+	max_sessions: z.number().int().positive().default(50),
+	reconcile_interval_seconds: z.number().int().min(30).max(3600).default(300)
+}).passthrough();
+const agentSlotConfigSchema = z.object({
+	agentId: z.string().min(1),
+	type: z.string().min(1),
+	session: sessionConfigSchema.prefault({}),
+	concurrency: z.number().int().positive().default(16)
+}).passthrough();
+z.object({
+	server: z.url().default("http://localhost:8000"),
+	agents: z.record(z.string(), agentSlotConfigSchema).refine((agents) => Object.keys(agents).length > 0, "At least one agent must be defined")
+});
+/**
+* Version-drift decision flow. Install, prompt, and exit are delegated to
+* command-layer callbacks so the Client package stays free of CLI /
+* filesystem knowledge.
+*/
+var UpdateManager = class UpdateManager {
+	options;
+	connection;
+	welcomeListener;
+	updateInFlight = false;
+	quietGateTimer = null;
+	disposed = false;
+	/**
+	* Set when a standalone (unmanaged) executeUpdate reports `installed: true`
 	* without exiting. The new bits are on disk; subsequent welcome frames must
 	* not re-invoke npm since a restart is the only way to pick them up.
 	*/
@@ -4802,7 +5630,7 @@ function result(data) {
 		data
 	})}\n`);
 }
-function fail(code, message, exitCode = 1) {
+function fail$1(code, message, exitCode = 1) {
 	process.stderr.write(`${JSON.stringify({
 		ok: false,
 		error: {
@@ -4837,13 +5665,26 @@ function line(text) {
 }
 const print = {
 	result,
-	fail,
+	fail: fail$1,
 	status,
 	check,
 	blank,
 	line
 };
 //#endregion
+//#region src/cli/output.ts
+/**
+* CLI output re-exports. The underlying implementation lives in
+* `core/output.ts` (the Print layer). Keep these thin wrappers so callers that
+* only depend on `cli/output.ts` keep working during the migration.
+*/
+function success(data) {
+	print.result(data);
+}
+function fail(code, message, exitCode = 1) {
+	return print.fail(code, message, exitCode);
+}
+//#endregion
 //#region src/core/agent-messaging.ts
 /**
 * Resolve `replyTo` envelope fields for `agent send`. When the CLI is invoked
@@ -5217,7 +6058,7 @@ var ClientRuntime = class {
 			});
 			const yaml = stringify({
 				agentId: message.agentId,
-				runtime: "claude-code"
+				runtime: message.runtimeProvider
 			});
 			writeFileSync(join(agentDir, "agent.yaml"), yaml, { mode: 384 });
 			print.check(true, `auto-added agent "${localName}"`, `${message.agentId} (from server push)`);
@@ -6530,7 +7371,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-DEmwoNn_.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-Boy3n8CT.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 {
@@ -6693,6 +7534,66 @@ function setNestedByDot(obj, dotPath, value) {
 	if (lastKey !== void 0) current[lastKey] = value;
 }
 //#endregion
+//#region src/core/runtime-provider-reconcile.ts
+/**
+* Pre-flight reconciliation called before the agents loop spawns. Pulls
+* authoritative `runtime_provider` for every agent the calling user owns and
+* rewrites any local `agent.yaml` whose `runtime` field disagrees. Best-
+* effort: a transient hub failure logs and falls back to the local YAML
+* value (the in-band repair path catches any remaining drift on first bind).
+*/
+async function reconcileLocalRuntimeProviders(opts) {
+	const res = await fetch(`${opts.serverUrl}/api/v1/clients/me/agents`, { headers: { Authorization: `Bearer ${opts.accessToken}` } });
+	if (!res.ok) throw new Error(`hub returned ${res.status} on /clients/me/agents`);
+	const items = await res.json();
+	const byAgentId = new Map(items.map((it) => [it.agentId, it]));
+	if (!existsSync(opts.agentsDir)) return;
+	const subdirs = readdirSync(opts.agentsDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+	for (const subdir of subdirs) {
+		const yamlPath = join(opts.agentsDir, subdir.name, "agent.yaml");
+		if (!existsSync(yamlPath)) continue;
+		let parsed;
+		try {
+			parsed = parse(readFileSync(yamlPath, "utf-8")) ?? {};
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			opts.log?.("warn", `agent ${subdir.name}: cannot parse yaml — ${msg}`);
+			continue;
+		}
+		if (!parsed.agentId) continue;
+		const auth = byAgentId.get(parsed.agentId);
+		if (!auth) continue;
+		if (parsed.runtime === auth.runtimeProvider) continue;
+		const next = {
+			...parsed,
+			runtime: auth.runtimeProvider
+		};
+		try {
+			writeFileSync(yamlPath, stringify(next), { mode: 384 });
+			opts.log?.("info", `agent ${parsed.agentId}: yaml runtime "${parsed.runtime ?? "(unset)"}" → "${auth.runtimeProvider}" (hub authoritative)`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			opts.log?.("warn", `agent ${parsed.agentId}: failed to rewrite yaml — ${msg}`);
+		}
+	}
+}
+/**
+* Member-scoped capabilities upload. Server stores the snapshot under
+* `clients.metadata.capabilities`. Best-effort: failure does not block
+* client startup since capabilities only matter for UI / admin checks.
+*/
+async function uploadClientCapabilities(opts) {
+	const res = await fetch(`${opts.serverUrl}/api/v1/clients/${encodeURIComponent(opts.clientId)}/capabilities`, {
+		method: "PATCH",
+		headers: {
+			Authorization: `Bearer ${opts.accessToken}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ capabilities: opts.capabilities })
+	});
+	if (!res.ok) throw new Error(`hub returned ${res.status} on PATCH /clients/${opts.clientId}/capabilities`);
+}
+//#endregion
 //#region ../../node_modules/.pnpm/hearback-core@0.1.1/node_modules/hearback-core/dist/schema.js
 const FeedbackType = z.enum(["bug", "feature"]);
 const BrowserContext = z.object({
@@ -7450,7 +8351,7 @@ function createFeedbackHandler(config) {
 	return { handle };
 }
 //#endregion
-//#region ../server/dist/app-DugUZNsw.mjs
+//#region ../server/dist/app-D-aIvdiQ.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -7461,28 +8362,6 @@ var __exportAll = (all, no_symbols) => {
 	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
-/** Organization entity. Agents and chats belong to exactly one organization. */
-const organizations = pgTable("organizations", {
-	id: text("id").primaryKey(),
-	name: text("name").unique().notNull(),
-	displayName: text("display_name").notNull(),
-	maxAgents: integer("max_agents").notNull().default(0),
-	maxMessagesPerMinute: integer("max_messages_per_minute").notNull().default(0),
-	features: jsonb("features").$type().notNull().default({}),
-	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
-	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
-});
-/** User accounts. Passwords are stored as bcrypt hashes. */
-const users = pgTable("users", {
-	id: text("id").primaryKey(),
-	username: text("username").unique().notNull(),
-	passwordHash: text("password_hash").notNull(),
-	displayName: text("display_name").notNull(),
-	avatarUrl: text("avatar_url"),
-	status: text("status").notNull().default("active"),
-	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
-	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
-});
 /**
 * Client connections. A client is a single SDK process (AgentRuntime) that may
 * host multiple agents. From the unified-user-token milestone on, a client is
@@ -7526,6 +8405,7 @@ const agents = pgTable("agents", {
 	metadata: jsonb("metadata").$type().notNull().default({}),
 	managerId: text("manager_id").notNull(),
 	clientId: text("client_id").references(() => clients.id, { onDelete: "restrict" }),
+	runtimeProvider: text("runtime_provider").notNull().default("claude-code"),
 	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
 }, (table) => [
@@ -7546,57 +8426,6 @@ const adapterAgentMappings = pgTable("adapter_agent_mappings", {
 	metadata: jsonb("metadata").$type().notNull().default({}),
 	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
 }, (table) => [unique("uq_adapter_agent_mapping").on(table.platform, table.externalUserId)]);
-var AppError = class extends Error {
-	constructor(statusCode, message) {
-		super(message);
-		this.statusCode = statusCode;
-		this.name = "AppError";
-	}
-};
-var NotFoundError = class extends AppError {
-	constructor(message = "Not found") {
-		super(404, message);
-		this.name = "NotFoundError";
-	}
-};
-var UnauthorizedError = class extends AppError {
-	constructor(message = "Unauthorized") {
-		super(401, message);
-		this.name = "UnauthorizedError";
-	}
-};
-var ForbiddenError = class extends AppError {
-	constructor(message = "Forbidden") {
-		super(403, message);
-		this.name = "ForbiddenError";
-	}
-};
-var ConflictError = class extends AppError {
-	constructor(message = "Conflict") {
-		super(409, message);
-		this.name = "ConflictError";
-	}
-};
-var BadRequestError = class extends AppError {
-	constructor(message = "Bad request") {
-		super(400, message);
-		this.name = "BadRequestError";
-	}
-};
-/**
-* Thrown when an operation targets a client whose organization does not match
-* the caller's authenticated organization. A client is bound to exactly one
-* org for its lifetime; re-registering or operating under a different org's
-* credentials is refused. CLI consumers recognize the `code` field and
-* respond by abandoning the local clientId to register a fresh one.
-*/
-var ClientOrgMismatchError = class extends AppError {
-	code = "CLIENT_ORG_MISMATCH";
-	constructor(message = "Client belongs to a different organization") {
-		super(403, message);
-		this.name = "ClientOrgMismatchError";
-	}
-};
 /** Communication container. All messages between agents flow within a Chat. */
 const chats = pgTable("chats", {
 	id: text("id").primaryKey(),
@@ -7747,26 +8576,6 @@ const adapterMessageReferences = pgTable("adapter_message_references", {
 	externalChannelId: text("external_channel_id").notNull(),
 	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
 }, (table) => [unique("uq_adapter_message_ref").on(table.messageId, table.platform)]);
-/** Generate a UUID v7 (time-ordered). No external dependency. */
-function uuidv7() {
-	const now = BigInt(Date.now());
-	const bytes = new Uint8Array(16);
-	bytes[0] = Number(now >> 40n & 255n);
-	bytes[1] = Number(now >> 32n & 255n);
-	bytes[2] = Number(now >> 24n & 255n);
-	bytes[3] = Number(now >> 16n & 255n);
-	bytes[4] = Number(now >> 8n & 255n);
-	bytes[5] = Number(now & 255n);
-	const rand = randomBytes(10);
-	for (let i = 0; i < 10; i++) {
-		const b = rand[i];
-		if (b !== void 0) bytes[6 + i] = b;
-	}
-	bytes[6] = (bytes[6] ?? 0) & 15 | 112;
-	bytes[8] = (bytes[8] ?? 0) & 63 | 128;
-	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
 /** UUID v7 regex pattern for distinguishing UUIDs from name slugs. */
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 /**
@@ -8266,7 +9075,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$4 = createLogger$1("AdminAdapters");
+const log$5 = createLogger$1("AdminAdapters");
 function parseId(raw) {
 	const id = Number(raw);
 	if (!Number.isInteger(id) || id <= 0) throw new BadRequestError(`Invalid adapter ID: "${raw}"`);
@@ -8286,7 +9095,7 @@ async function adminAdapterRoutes(app) {
 		const scope = memberScope(request);
 		await assertCanManage(app.db, scope, body.agentId);
 		const config = await createAdapterConfig(app.db, body, app.config.secrets.encryptionKey);
-		app.adapterManager.reload().catch((err) => log$4.error({ err }, "adapter reload failed after create"));
+		app.adapterManager.reload().catch((err) => log$5.error({ err }, "adapter reload failed after create"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return reply.status(201).send({
 			...config,
@@ -8310,7 +9119,7 @@ async function adminAdapterRoutes(app) {
 		const existing = await getAdapterConfig(app.db, id);
 		await assertCanManage(app.db, scope, existing.agentId);
 		const config = await updateAdapterConfig(app.db, id, body, app.config.secrets.encryptionKey);
-		app.adapterManager.reload().catch((err) => log$4.error({ err }, "adapter reload failed after update"));
+		app.adapterManager.reload().catch((err) => log$5.error({ err }, "adapter reload failed after update"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return {
 			...config,
@@ -8324,7 +9133,7 @@ async function adminAdapterRoutes(app) {
 		const existing = await getAdapterConfig(app.db, id);
 		await assertCanManage(app.db, scope, existing.agentId);
 		await deleteAdapterConfig(app.db, id);
-		app.adapterManager.reload().catch((err) => log$4.error({ err }, "adapter reload failed after delete"));
+		app.adapterManager.reload().catch((err) => log$5.error({ err }, "adapter reload failed after delete"));
 		app.notifier.notifyConfigChange("adapter_configs").catch(() => {});
 		return reply.status(204).send();
 	});
@@ -8411,6 +9220,7 @@ const members = pgTable("members", {
 	organizationId: text("organization_id").notNull().references(() => organizations.id),
 	agentId: text("agent_id").unique().notNull().references(() => agents.uuid),
 	role: text("role").notNull(),
+	status: text("status").notNull().default("active"),
 	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
 }, (table) => [
 	unique("uq_members_user_org").on(table.userId, table.organizationId),
@@ -8424,6 +9234,38 @@ const members = pgTable("members", {
 * real account.
 */
 const RESERVED_AGENT_NAME_PREFIX = "__";
+/**
+* True iff `clients.metadata.capabilities` is a non-empty object — i.e. the
+* client has reported at least one runtime probe result. Used to distinguish
+* "we don't know what's installed yet" (empty / never reported) from
+* "client explicitly reports this provider is missing".
+*/
+function clientCapabilitiesReported(metadata) {
+	if (!metadata || typeof metadata !== "object") return false;
+	const caps = metadata.capabilities;
+	if (!caps || typeof caps !== "object") return false;
+	return Object.keys(caps).length > 0;
+}
+/**
+* Inspect a `clients.metadata.capabilities` blob (jsonb) for a specific
+* runtime provider entry. Capabilities live under the `metadata.capabilities`
+* subkey (Option C); the column is unstructured at the DB layer, so we
+* defensively narrow before key access.
+*
+* "Supports" requires the entry's SDK to be **available** — `state: "ok"` or
+* `state: "unauthenticated"`. A `missing` or `error` entry is *reported* but
+* not usable, so we explicitly reject those rather than treating mere key
+* presence as support. Auth state is left to the user to fix at runtime
+* (the re-bind dialog surfaces an `unauthenticated` hint).
+*/
+function clientSupportsRuntimeProvider(metadata, provider) {
+	if (!metadata || typeof metadata !== "object") return false;
+	const caps = metadata.capabilities;
+	if (!caps || typeof caps !== "object") return false;
+	const entry = caps[provider];
+	if (!entry || typeof entry !== "object") return false;
+	return entry.available === true;
+}
 /** Default visibility per agent type. */
 function defaultVisibility(type) {
 	switch (type) {
@@ -8444,6 +9286,32 @@ function defaultVisibility(type) {
 *   - When a non-human agent IS created with a `clientId`, the pinned client
 *     must already be owned by the manager's user (Rule R-RUN).
 */
+/**
+* Check that a client's reported capabilities show the given runtime provider
+* as **available** (SDK installed, regardless of auth state).
+*
+* Tri-state semantics by `clients.metadata.capabilities` shape:
+*   - empty / absent — client hasn't probed yet (newly registered or pre-P2
+*     install). Treat as "unknown" and allow; the in-band repair path
+*     (RUNTIME_PROVIDER_MISMATCH on bind) catches actual incompatibility.
+*   - reported, entry shows `state: ok | unauthenticated` (i.e. `available:
+*     true`) — allow.
+*   - reported, entry missing OR `state: missing | error` — block unless
+*     `force` is set. We deliberately do NOT treat mere key presence as
+*     support: probeCapabilities() always emits an entry per built-in
+*     provider, including `{ state: "missing" }` for absent SDKs.
+*
+* Skipped entirely for human agents (no clientId) and when `force` is set
+* (e.g. operator overrides for an offline client).
+*/
+async function ensureClientSupportsRuntimeProvider(db, clientId, runtimeProvider, options = {}) {
+	if (clientId === null) return;
+	if (options.force) return;
+	const [client] = await db.select({ metadata: clients.metadata }).from(clients).where(eq(clients.id, clientId)).limit(1);
+	if (!client) return;
+	if (!clientCapabilitiesReported(client.metadata)) return;
+	if (!clientSupportsRuntimeProvider(client.metadata, runtimeProvider)) throw new BadRequestError(`Client "${clientId}" does not have runtime provider "${runtimeProvider}" available. Install the matching SDK on that machine and re-run capability detection, or retry with \`force: true\` if the client is offline / capabilities are stale.`);
+}
 async function resolveAgentClient(db, data) {
 	if (data.type === "human") {
 		if (data.clientId) throw new BadRequestError("Human agents cannot be pinned to a client");
@@ -8476,9 +9344,10 @@ async function resolveFallbackManagerId(db, orgId) {
 	if (!row) throw new BadRequestError(`Cannot create agent in organization "${orgId}" — no admin member exists. Create an admin member first (see \`first-tree-hub onboard\`).`);
 	return row.id;
 }
-async function createAgent(db, data) {
+async function createAgent(db, data, options = {}) {
 	const uuid = uuidv7();
 	const name = data.name ?? null;
+	const runtimeProvider = data.runtimeProvider ?? "claude-code";
 	if (name?.startsWith(RESERVED_AGENT_NAME_PREFIX)) throw new BadRequestError(`Agent name "${name}" is reserved — names starting with "${RESERVED_AGENT_NAME_PREFIX}" are Hub-internal`);
 	if (name && isReservedAgentName$1(name)) throw new BadRequestError(`Agent name "${name}" is reserved — pick a different one.`);
 	const inboxId = `inbox_${uuid}`;
@@ -8504,6 +9373,7 @@ async function createAgent(db, data) {
 		managerId,
 		type: data.type
 	});
+	await ensureClientSupportsRuntimeProvider(db, clientId, runtimeProvider, { force: options.force });
 	const [org] = await db.select({ maxAgents: organizations.maxAgents }).from(organizations).where(eq(organizations.id, orgId)).limit(1);
 	if (org && org.maxAgents > 0) {
 		if (((await db.select({ value: count() }).from(agents).where(and(eq(agents.organizationId, orgId), ne(agents.status, AGENT_STATUSES.DELETED))))[0]?.value ?? 0) >= org.maxAgents) throw new ForbiddenError(`Organization "${orgId}" has reached its agent limit (${org.maxAgents}). Upgrade your plan or delete unused agents.`);
@@ -8522,13 +9392,14 @@ async function createAgent(db, data) {
 			visibility: data.visibility ?? defaultVisibility(data.type),
 			metadata: data.metadata ?? {},
 			managerId,
-			clientId
+			clientId,
+			runtimeProvider
 		}).returning();
 		if (!agent) throw new Error("Unexpected: INSERT RETURNING produced no row");
 		await db.insert(agentConfigs).values({
 			agentId: agent.uuid,
 			version: 1,
-			payload: DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD,
+			payload: defaultRuntimeConfigPayload(runtimeProvider),
 			updatedBy: "system"
 		}).onConflictDoNothing();
 		return agent;
@@ -8582,6 +9453,7 @@ async function listAgentsForAdmin(db, scope, limit, cursor) {
 		metadata: agents.metadata,
 		managerId: agents.managerId,
 		clientId: agents.clientId,
+		runtimeProvider: agents.runtimeProvider,
 		createdAt: agents.createdAt,
 		updatedAt: agents.updatedAt,
 		presenceStatus: agentPresence.status,
@@ -8619,6 +9491,7 @@ async function listAgentsForMember(db, scope, limit, cursor, type) {
 		metadata: agents.metadata,
 		managerId: agents.managerId,
 		clientId: agents.clientId,
+		runtimeProvider: agents.runtimeProvider,
 		createdAt: agents.createdAt,
 		updatedAt: agents.updatedAt,
 		presenceStatus: agentPresence.status,
@@ -8638,7 +9511,7 @@ async function updateAgent(db, uuid, data) {
 	const agent = await getAgent(db, uuid);
 	if (data.clientId !== void 0) {
 		if (data.clientId === null) throw new BadRequestError("clientId cannot be cleared — once bound, an agent stays bound to its client");
-		if (agent.clientId !== null && agent.clientId !== data.clientId) throw new BadRequestError("clientId is immutable once set — delete and re-create the agent on the target client to move it");
+		if (agent.clientId !== null && agent.clientId !== data.clientId) throw new BadRequestError("clientId is immutable through this entry — cross-client moves go through rebindAgent (PATCH /admin/agents/:agentId/rebind), which runs owner / org / capability checks atomically.");
 	}
 	const updates = { updatedAt: /* @__PURE__ */ new Date() };
 	if (data.type !== void 0) updates.type = data.type;
@@ -8669,6 +9542,39 @@ async function updateAgent(db, uuid, data) {
 	return updated;
 }
 /**
+* Atomically re-bind an agent to a new client and/or runtime provider.
+*
+* Validations: agent must exist and not be human; new client must belong to
+* the same owner (manager.userId) and same organization; client must report
+* the requested runtime provider in its capabilities (skipped under `force`).
+*
+* Intended caller: PATCH /admin/agents/:agentId/rebind. The Web "Re-bind"
+* dialog routes both same-client runtime-only switches and cross-client
+* moves through this single entry.
+*
+* NOTE: active sessions on the previous client are not auto-suspended in P1.
+* P3 will wire in cross-service coordination (inbox + presence + session)
+* so the destination client can resume cleanly.
+*/
+async function rebindAgent(db, uuid, data) {
+	const agent = await getAgent(db, uuid);
+	if (agent.type === "human") throw new BadRequestError("Human agents have no runtime — they cannot be re-bound to a client.");
+	const newClientId = await resolveAgentClient(db, {
+		clientId: data.clientId,
+		managerId: agent.managerId,
+		type: agent.type
+	});
+	if (newClientId === null) throw new BadRequestError("Rebind requires a non-null clientId.");
+	await ensureClientSupportsRuntimeProvider(db, newClientId, data.runtimeProvider, { force: data.force });
+	const [updated] = await db.update(agents).set({
+		clientId: newClientId,
+		runtimeProvider: data.runtimeProvider,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(eq(agents.uuid, uuid)).returning();
+	if (!updated) throw new Error("Unexpected: UPDATE RETURNING produced no row");
+	return updated;
+}
+/**
 * Reactivate a suspended agent.
 */
 async function reactivateAgent(db, uuid) {
@@ -9188,7 +10094,7 @@ async function registerClient(db, data) {
 		userId: clients.userId,
 		organizationId: clients.organizationId
 	}).from(clients).where(eq(clients.id, data.clientId)).limit(1);
-	if (existing && existing.organizationId !== data.organizationId) throw new ClientOrgMismatchError(`Client "${data.clientId}" is bound to a different organization. Re-register as a new client under the current org.`);
+	if (existing && existing.organizationId !== data.organizationId) throw new ClientOrgMismatchError$1(`Client "${data.clientId}" is bound to a different organization. Re-register as a new client under the current org.`);
 	if (existing?.userId && existing.userId !== data.userId) throw new ForbiddenError(`Client "${data.clientId}" is already claimed by a different user. Pick a unique client_id.`);
 	await db.insert(clients).values({
 		id: data.clientId,
@@ -9248,10 +10154,45 @@ async function listActiveAgentsPinnedToClient(db, clientId) {
 		uuid: agents.uuid,
 		name: agents.name,
 		displayName: agents.displayName,
-		type: agents.type
+		type: agents.type,
+		runtimeProvider: agents.runtimeProvider
 	}).from(agents).where(and(eq(agents.clientId, clientId), ne(agents.status, "deleted")));
 }
 /**
+* Member-scoped: every active agent pinned to a client owned by this user
+* within the given organization. Used by client startup to reconcile its
+* local YAML against the authoritative `agents.runtime_provider`.
+*/
+async function listMyPinnedAgents(db, scope) {
+	return (await db.select({
+		agentId: agents.uuid,
+		clientId: agents.clientId,
+		runtimeProvider: agents.runtimeProvider
+	}).from(agents).innerJoin(clients, eq(agents.clientId, clients.id)).where(and(eq(clients.userId, scope.userId), eq(clients.organizationId, scope.organizationId), ne(agents.status, "deleted")))).filter((r) => r.clientId !== null).map((r) => ({
+		agentId: r.agentId,
+		clientId: r.clientId,
+		runtimeProvider: r.runtimeProvider
+	}));
+}
+/**
+* Replace this client's capabilities snapshot. Capabilities live under
+* `clients.metadata.capabilities` (Option C — no dedicated column); other
+* `metadata` subkeys are preserved on merge.
+*
+* Caller is expected to have already passed `assertClientOwner`.
+*/
+async function updateClientCapabilities(db, clientId, capabilities) {
+	const parsed = clientCapabilitiesSchema$1.safeParse(capabilities);
+	if (!parsed.success) throw new BadRequestError(`Invalid capabilities payload: ${parsed.error.message}`);
+	const [client] = await db.select({ metadata: clients.metadata }).from(clients).where(eq(clients.id, clientId)).limit(1);
+	if (!client) throw new NotFoundError(`Client "${clientId}" not found`);
+	const merged = {
+		...client.metadata ?? {},
+		capabilities: parsed.data
+	};
+	await db.update(clients).set({ metadata: merged }).where(eq(clients.id, clientId));
+}
+/**
 * Scope-aware client listing.
 *
 *   - member: rows where `user_id = scope.userId` AND `organization_id = scope.organizationId`
@@ -9464,51 +10405,178 @@ const inboxEntries = pgTable("inbox_entries", {
 	index("idx_inbox_pending_notify").on(table.inboxId, table.createdAt).where(sql`status = 'pending' AND notify = true`),
 	index("idx_inbox_chat_silent").on(table.inboxId, table.chatId, table.notify, table.status)
 ]);
-async function sendMessage(db, chatId, senderId, data, options = {}) {
-	return withSpan("inbox.enqueue", messageAttrs({
-		chatId,
-		senderAgentId: senderId,
-		source: data.source ?? void 0
-	}), () => sendMessageInner(db, chatId, senderId, data, options));
-}
-async function sendMessageInner(db, chatId, senderId, data, options) {
-	return db.transaction(async (tx) => {
-		const [participants, [chatRow]] = await Promise.all([tx.select({
-			agentId: chatParticipants.agentId,
-			inboxId: agents.inboxId,
-			mode: chatParticipants.mode,
-			name: agents.name
-		}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId)), tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1)]);
-		const chatType = chatRow?.type ?? null;
-		if (data.replyToInbox !== void 0 && data.replyToInbox !== null) {
-			const [senderRow] = await tx.select({ inboxId: agents.inboxId }).from(agents).where(eq(agents.uuid, senderId)).limit(1);
-			if (!senderRow || senderRow.inboxId !== data.replyToInbox) throw new BadRequestError("replyToInbox must reference the sender's own inbox");
-		}
-		const incomingMeta = data.metadata ?? {};
-		const explicitMentionsRaw = incomingMeta.mentions;
-		const explicitMentions = Array.isArray(explicitMentionsRaw) ? explicitMentionsRaw.filter((m) => typeof m === "string") : [];
-		const contentText = typeof data.content === "string" ? data.content : "";
-		const resolved = contentText ? extractMentions(contentText, participants) : [];
-		const mergedMentions = [...new Set([...explicitMentions, ...resolved])];
-		const metadataToStore = mergedMentions.length > 0 ? {
-			...incomingMeta,
-			mentions: mergedMentions
-		} : incomingMeta;
-		if (options.enforceGroupMention && chatType === "group") {
-			if (mergedMentions.filter((id) => id !== senderId).length === 0) throw new BadRequestError("Sending to a group chat requires an explicit @mention. Use `agent send <name>` to message a single agent, or @<name> in the content to address one or more group members.");
-		}
-		let outboundContent = data.content;
-		if (options.normalizeMentionsInContent && typeof outboundContent === "string") {
-			const present = new Set(scanMentionTokens(outboundContent));
-			const missingNames = [];
-			for (const id of mergedMentions) {
-				if (id === senderId) continue;
-				const p = participants.find((q) => q.agentId === id);
-				if (!p?.name) continue;
-				if (present.has(p.name.toLowerCase())) continue;
-				missingNames.push(p.name);
-			}
-			if (missingNames.length > 0) {
+/** Per-session state snapshot. One row per (agent, chat) pair, upserted on each session:state message. */
+const agentChatSessions = pgTable("agent_chat_sessions", {
+	agentId: text("agent_id").notNull().references(() => agents.uuid, { onDelete: "cascade" }),
+	chatId: text("chat_id").notNull().references(() => chats.id, { onDelete: "cascade" }),
+	state: text("state").notNull(),
+	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+}, (table) => [primaryKey({ columns: [table.agentId, table.chatId] })]);
+/**
+* Upsert session state + refresh presence aggregates + NOTIFY.
+*
+* `agent_chat_sessions.(agent_id, chat_id)` is a single-row "current session
+* state" cache, not a session history log. A new runtime session starting on
+* the same (agent, chat) pair MUST overwrite whatever ended before — including
+* an `evicted` row left by a previous terminate. The previous "revival
+* defense" conflated two concerns: "this runtime session ended" (which is
+* what `evicted` actually means) and "this chat is permanently archived for
+* this agent" (a chat-level decision that should live on `chats`, not here).
+* See proposals/hub-agent-messaging-reply-and-mentions §M2-session-lifecycle.
+*
+* Presence row contract: this function tolerates a missing `agent_presence`
+* row by using `INSERT ... ON CONFLICT DO UPDATE`. The predictive-write path
+* (sendMessage on first message) may target an agent whose client has never
+* bound, so a prior `update agent_presence ... where agentId` would silently
+* drop the activeSessions/totalSessions refresh. See PR #198 review §2.
+*/
+async function upsertSessionState(db, agentId, chatId, state, organizationId, notifier, options) {
+	const now = /* @__PURE__ */ new Date();
+	let wrote = false;
+	await db.transaction(async (tx) => {
+		await tx.insert(agentChatSessions).values({
+			agentId,
+			chatId,
+			state,
+			updatedAt: now
+		}).onConflictDoUpdate({
+			target: [agentChatSessions.agentId, agentChatSessions.chatId],
+			set: {
+				state,
+				updatedAt: now
+			},
+			setWhere: ne(agentChatSessions.state, state)
+		});
+		const [counts] = await tx.select({
+			active: sql`count(*) FILTER (WHERE ${agentChatSessions.state} = 'active')::int`,
+			total: sql`count(*) FILTER (WHERE ${agentChatSessions.state} != 'evicted')::int`
+		}).from(agentChatSessions).where(eq(agentChatSessions.agentId, agentId));
+		const activeSessions = counts?.active ?? 0;
+		const totalSessions = counts?.total ?? 0;
+		const presenceSet = options?.touchPresenceLastSeen ?? true ? {
+			activeSessions,
+			totalSessions,
+			lastSeenAt: now
+		} : {
+			activeSessions,
+			totalSessions
+		};
+		await tx.insert(agentPresence).values({
+			agentId,
+			activeSessions,
+			totalSessions
+		}).onConflictDoUpdate({
+			target: [agentPresence.agentId],
+			set: presenceSet
+		});
+		wrote = true;
+	});
+	if (wrote && notifier) notifier.notifySessionStateChange(agentId, chatId, state, organizationId).catch(() => {});
+}
+async function resetActivity(db, agentId) {
+	const now = /* @__PURE__ */ new Date();
+	await db.update(agentPresence).set({
+		runtimeState: "idle",
+		runtimeUpdatedAt: now
+	}).where(eq(agentPresence.agentId, agentId));
+}
+async function getActivityOverview(db) {
+	const [agentCounts] = await db.select({
+		total: sql`count(*)::int`,
+		running: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} IS NOT NULL)::int`,
+		idle: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'idle')::int`,
+		working: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'working')::int`,
+		blocked: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'blocked')::int`,
+		error: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'error')::int`
+	}).from(agentPresence);
+	const [clientCounts] = await db.select({ count: sql`count(*)::int` }).from(clients).where(eq(clients.status, "connected"));
+	return {
+		total: agentCounts?.total ?? 0,
+		running: agentCounts?.running ?? 0,
+		byState: {
+			idle: agentCounts?.idle ?? 0,
+			working: agentCounts?.working ?? 0,
+			blocked: agentCounts?.blocked ?? 0,
+			error: agentCounts?.error ?? 0
+		},
+		clients: clientCounts?.count ?? 0
+	};
+}
+/**
+* List agents with active runtime state.
+* When scope is provided, filters to agents visible to the member.
+*/
+async function listAgentsWithRuntime(db, scope) {
+	if (!scope) return db.select().from(agentPresence).where(isNotNull(agentPresence.runtimeState));
+	return db.select({
+		agentId: agentPresence.agentId,
+		status: agentPresence.status,
+		instanceId: agentPresence.instanceId,
+		connectedAt: agentPresence.connectedAt,
+		lastSeenAt: agentPresence.lastSeenAt,
+		clientId: agentPresence.clientId,
+		runtimeType: agentPresence.runtimeType,
+		runtimeVersion: agentPresence.runtimeVersion,
+		runtimeState: agentPresence.runtimeState,
+		activeSessions: agentPresence.activeSessions,
+		totalSessions: agentPresence.totalSessions,
+		runtimeUpdatedAt: agentPresence.runtimeUpdatedAt,
+		type: agents.type
+	}).from(agentPresence).innerJoin(agents, eq(agentPresence.agentId, agents.uuid)).where(and(isNotNull(agentPresence.runtimeState), agentVisibilityCondition(scope)));
+}
+const log$4 = createLogger$1("message");
+async function sendMessage(db, chatId, senderId, data, options = {}) {
+	return withSpan("inbox.enqueue", messageAttrs({
+		chatId,
+		senderAgentId: senderId,
+		source: data.source ?? void 0
+	}), () => sendMessageInner(db, chatId, senderId, data, options));
+}
+async function sendMessageInner(db, chatId, senderId, data, options) {
+	const txResult = await db.transaction(async (tx) => {
+		const [participants, [chatRow], [senderRow]] = await Promise.all([
+			tx.select({
+				agentId: chatParticipants.agentId,
+				inboxId: agents.inboxId,
+				mode: chatParticipants.mode,
+				name: agents.name
+			}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId)),
+			tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1),
+			tx.select({
+				inboxId: agents.inboxId,
+				organizationId: agents.organizationId
+			}).from(agents).where(eq(agents.uuid, senderId)).limit(1)
+		]);
+		const chatType = chatRow?.type ?? null;
+		if (!senderRow) throw new NotFoundError(`Sender agent "${senderId}" not found`);
+		if (data.replyToInbox !== void 0 && data.replyToInbox !== null) {
+			if (senderRow.inboxId !== data.replyToInbox) throw new BadRequestError("replyToInbox must reference the sender's own inbox");
+		}
+		const incomingMeta = data.metadata ?? {};
+		const explicitMentionsRaw = incomingMeta.mentions;
+		const explicitMentions = Array.isArray(explicitMentionsRaw) ? explicitMentionsRaw.filter((m) => typeof m === "string") : [];
+		const contentText = typeof data.content === "string" ? data.content : "";
+		const resolved = contentText ? extractMentions(contentText, participants) : [];
+		const mergedMentions = [...new Set([...explicitMentions, ...resolved])];
+		const metadataToStore = mergedMentions.length > 0 ? {
+			...incomingMeta,
+			mentions: mergedMentions
+		} : incomingMeta;
+		if (options.enforceGroupMention && chatType === "group") {
+			if (mergedMentions.filter((id) => id !== senderId).length === 0) throw new BadRequestError("Sending to a group chat requires an explicit @mention. Use `agent send <name>` to message a single agent, or @<name> in the content to address one or more group members.");
+		}
+		let outboundContent = data.content;
+		if (options.normalizeMentionsInContent && typeof outboundContent === "string") {
+			const present = new Set(scanMentionTokens(outboundContent));
+			const missingNames = [];
+			for (const id of mergedMentions) {
+				if (id === senderId) continue;
+				const p = participants.find((q) => q.agentId === id);
+				if (!p?.name) continue;
+				if (present.has(p.name.toLowerCase())) continue;
+				missingNames.push(p.name);
+			}
+			if (missingNames.length > 0) {
 				const prefix = missingNames.map((n) => `@${n}`).join(" ");
 				outboundContent = outboundContent.length > 0 ? `${prefix} ${outboundContent}` : prefix;
 			}
@@ -9527,14 +10595,20 @@ async function sendMessageInner(db, chatId, senderId, data, options) {
 			source: data.source ?? null
 		}).returning();
 		const mentionSet = new Set(mergedMentions);
-		const entries = participants.filter((p) => p.agentId !== senderId).map((p) => ({
+		const fanout = participants.filter((p) => p.agentId !== senderId).map((p) => ({
+			agentId: p.agentId,
 			inboxId: p.inboxId,
-			messageId,
-			chatId,
 			notify: p.mode !== "mention_only" || mentionSet.has(p.agentId)
 		}));
-		if (entries.length > 0) await tx.insert(inboxEntries).values(entries);
-		const recipients = entries.filter((e) => e.notify).map((e) => e.inboxId);
+		if (fanout.length > 0) await tx.insert(inboxEntries).values(fanout.map((f) => ({
+			inboxId: f.inboxId,
+			messageId,
+			chatId,
+			notify: f.notify
+		})));
+		const notified = fanout.filter((f) => f.notify);
+		const recipients = notified.map((f) => f.inboxId);
+		const recipientAgentIds = notified.map((f) => f.agentId);
 		if (data.inReplyTo) {
 			const [original] = await tx.select({
 				replyToInbox: messages.replyToInbox,
@@ -9553,9 +10627,24 @@ async function sendMessageInner(db, chatId, senderId, data, options) {
 		if (!msg) throw new Error("Unexpected: INSERT RETURNING produced no row");
 		return {
 			message: msg,
-			recipients
+			recipients,
+			recipientAgentIds,
+			organizationId: senderRow.organizationId
 		};
 	});
+	const settled = await Promise.allSettled(txResult.recipientAgentIds.map((agentId) => upsertSessionState(db, agentId, chatId, "active", txResult.organizationId, void 0, { touchPresenceLastSeen: false })));
+	for (let i = 0; i < settled.length; i++) {
+		const r = settled[i];
+		if (r?.status === "rejected") log$4.error({
+			err: r.reason,
+			chatId,
+			agentId: txResult.recipientAgentIds[i]
+		}, "predictive session activation failed");
+	}
+	return {
+		message: txResult.message,
+		recipients: txResult.recipients
+	};
 }
 async function sendToAgent(db, senderUuid, targetName, data) {
 	const [sender] = await db.select({
@@ -9782,7 +10871,8 @@ async function adminAgentRoutes(app) {
 			agentId: agent.uuid,
 			name: agent.name,
 			displayName: agent.displayName,
-			agentType: agent.type
+			agentType: agent.type,
+			runtimeProvider: agent.runtimeProvider
 		});
 		if (!parsed.success) {
 			app.log.warn({
@@ -9885,6 +10975,23 @@ async function adminAgentRoutes(app) {
 			updatedAt: agent.updatedAt.toISOString()
 		};
 	});
+	/**
+	* Rebind an agent to a new client and/or runtime provider. Re-runs owner /
+	* org / capability checks atomically. Capability mismatch can be overridden
+	* with `force: true` (e.g. client offline, capabilities stale).
+	*/
+	app.patch("/:uuid/rebind", async (request) => {
+		const scope = memberScope(request);
+		await assertCanManage(app.db, scope, request.params.uuid);
+		const body = rebindAgentSchema.parse(request.body);
+		const agent = await rebindAgent(app.db, request.params.uuid, body);
+		notifyClientAgentPinned(agent);
+		return {
+			...agent,
+			createdAt: agent.createdAt.toISOString(),
+			updatedAt: agent.updatedAt.toISOString()
+		};
+	});
 	app.get("/:uuid", async (request) => {
 		const scope = memberScope(request);
 		await assertAgentVisible(app.db, scope, request.params.uuid);
@@ -10059,9 +11166,10 @@ function memberAuthHook(db, jwtSecret) {
 			id: members.id,
 			organizationId: members.organizationId,
 			role: members.role,
-			agentId: members.agentId
+			agentId: members.agentId,
+			status: members.status
 		}).from(members).where(eq(members.id, payload.memberId)).limit(1);
-		if (!member) throw new UnauthorizedError("Membership not found");
+		if (!member || member.status !== "active") throw new UnauthorizedError("Membership not found");
 		request.member = {
 			userId: user.id,
 			memberId: member.id,
@@ -10338,107 +11446,6 @@ async function adminChatRoutes(app) {
 		});
 	});
 }
-/** Per-session state snapshot. One row per (agent, chat) pair, upserted on each session:state message. */
-const agentChatSessions = pgTable("agent_chat_sessions", {
-	agentId: text("agent_id").notNull().references(() => agents.uuid, { onDelete: "cascade" }),
-	chatId: text("chat_id").notNull().references(() => chats.id, { onDelete: "cascade" }),
-	state: text("state").notNull(),
-	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
-}, (table) => [primaryKey({ columns: [table.agentId, table.chatId] })]);
-/**
-* Upsert session state + refresh presence aggregates + NOTIFY.
-*
-* `agent_chat_sessions.(agent_id, chat_id)` is a single-row "current session
-* state" cache, not a session history log. A new runtime session starting on
-* the same (agent, chat) pair MUST overwrite whatever ended before — including
-* an `evicted` row left by a previous terminate. The previous "revival
-* defense" conflated two concerns: "this runtime session ended" (which is
-* what `evicted` actually means) and "this chat is permanently archived for
-* this agent" (a chat-level decision that should live on `chats`, not here).
-* See proposals/hub-agent-messaging-reply-and-mentions §M2-session-lifecycle.
-*/
-async function upsertSessionState(db, agentId, chatId, state, organizationId, notifier) {
-	const now = /* @__PURE__ */ new Date();
-	let wrote = false;
-	await db.transaction(async (tx) => {
-		await tx.insert(agentChatSessions).values({
-			agentId,
-			chatId,
-			state,
-			updatedAt: now
-		}).onConflictDoUpdate({
-			target: [agentChatSessions.agentId, agentChatSessions.chatId],
-			set: {
-				state,
-				updatedAt: now
-			}
-		});
-		const [counts] = await tx.select({
-			active: sql`count(*) FILTER (WHERE ${agentChatSessions.state} = 'active')::int`,
-			total: sql`count(*) FILTER (WHERE ${agentChatSessions.state} != 'evicted')::int`
-		}).from(agentChatSessions).where(eq(agentChatSessions.agentId, agentId));
-		const activeSessions = counts?.active ?? 0;
-		const totalSessions = counts?.total ?? 0;
-		await tx.update(agentPresence).set({
-			activeSessions,
-			totalSessions,
-			lastSeenAt: now
-		}).where(eq(agentPresence.agentId, agentId));
-		wrote = true;
-	});
-	if (wrote && notifier) notifier.notifySessionStateChange(agentId, chatId, state, organizationId).catch(() => {});
-}
-async function resetActivity(db, agentId) {
-	const now = /* @__PURE__ */ new Date();
-	await db.update(agentPresence).set({
-		runtimeState: "idle",
-		runtimeUpdatedAt: now
-	}).where(eq(agentPresence.agentId, agentId));
-}
-async function getActivityOverview(db) {
-	const [agentCounts] = await db.select({
-		total: sql`count(*)::int`,
-		running: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} IS NOT NULL)::int`,
-		idle: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'idle')::int`,
-		working: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'working')::int`,
-		blocked: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'blocked')::int`,
-		error: sql`count(*) FILTER (WHERE ${agentPresence.runtimeState} = 'error')::int`
-	}).from(agentPresence);
-	const [clientCounts] = await db.select({ count: sql`count(*)::int` }).from(clients).where(eq(clients.status, "connected"));
-	return {
-		total: agentCounts?.total ?? 0,
-		running: agentCounts?.running ?? 0,
-		byState: {
-			idle: agentCounts?.idle ?? 0,
-			working: agentCounts?.working ?? 0,
-			blocked: agentCounts?.blocked ?? 0,
-			error: agentCounts?.error ?? 0
-		},
-		clients: clientCounts?.count ?? 0
-	};
-}
-/**
-* List agents with active runtime state.
-* When scope is provided, filters to agents visible to the member.
-*/
-async function listAgentsWithRuntime(db, scope) {
-	if (!scope) return db.select().from(agentPresence).where(isNotNull(agentPresence.runtimeState));
-	return db.select({
-		agentId: agentPresence.agentId,
-		status: agentPresence.status,
-		instanceId: agentPresence.instanceId,
-		connectedAt: agentPresence.connectedAt,
-		lastSeenAt: agentPresence.lastSeenAt,
-		clientId: agentPresence.clientId,
-		runtimeType: agentPresence.runtimeType,
-		runtimeVersion: agentPresence.runtimeVersion,
-		runtimeState: agentPresence.runtimeState,
-		activeSessions: agentPresence.activeSessions,
-		totalSessions: agentPresence.totalSessions,
-		runtimeUpdatedAt: agentPresence.runtimeUpdatedAt,
-		type: agents.type
-	}).from(agentPresence).innerJoin(agents, eq(agentPresence.agentId, agents.uuid)).where(and(isNotNull(agentPresence.runtimeState), agentVisibilityCondition(scope)));
-}
 /** Serialize a Date to ISO string, or null. */
 function serializeDate(d) {
 	return d ? d.toISOString() : null;
@@ -10462,11 +11469,27 @@ async function adminClientRoutes(app) {
 			lastSeenAt: c.lastSeenAt.toISOString()
 		}));
 	});
+	app.get("/me/agents", async (request) => {
+		const scope = memberScope(request);
+		return await listMyPinnedAgents(app.db, {
+			userId: scope.userId,
+			organizationId: scope.organizationId
+		});
+	});
+	app.patch("/:clientId/capabilities", async (request, reply) => {
+		const scope = memberScope(request);
+		await assertClientOwner(app.db, request.params.clientId, scope);
+		const body = updateClientCapabilitiesSchema.parse(request.body);
+		await updateClientCapabilities(app.db, request.params.clientId, body.capabilities);
+		return reply.status(204).send();
+	});
 	app.get("/:clientId", async (request) => {
 		const scope = memberScope(request);
 		await assertClientOwner(app.db, request.params.clientId, scope);
 		const client = await getClient(app.db, request.params.clientId);
 		if (!client) throw new Error("unreachable: client missing after owner check");
+		const metadata = client.metadata ?? {};
+		const capabilities = metadata.capabilities && typeof metadata.capabilities === "object" ? metadata.capabilities : {};
 		return {
 			id: client.id,
 			userId: client.userId,
@@ -10475,7 +11498,8 @@ async function adminClientRoutes(app) {
 			hostname: client.hostname,
 			os: client.os,
 			connectedAt: serializeDate(client.connectedAt),
-			lastSeenAt: client.lastSeenAt.toISOString()
+			lastSeenAt: client.lastSeenAt.toISOString(),
+			capabilities
 		};
 	});
 	app.post("/:clientId/disconnect", async (request) => {
@@ -12750,7 +13774,7 @@ function clientWsRoutes(notifier, instanceId) {
 								});
 							} catch (err) {
 								const message = err instanceof Error ? err.message : "client register failed";
-								const code = err instanceof ClientOrgMismatchError ? err.code : void 0;
+								const code = err instanceof ClientOrgMismatchError$1 ? err.code : void 0;
 								socket.send(JSON.stringify({
 									type: "client:register:rejected",
 									message,
@@ -12774,7 +13798,8 @@ function clientWsRoutes(notifier, instanceId) {
 										agentId: agent.uuid,
 										name: agent.name,
 										displayName: agent.displayName,
-										agentType: agent.type
+										agentType: agent.type,
+										runtimeProvider: agent.runtimeProvider
 									});
 									if (!parsed.success) {
 										app.log.warn({
@@ -12810,6 +13835,7 @@ function clientWsRoutes(notifier, instanceId) {
 								inboxId: agents.inboxId,
 								status: agents.status,
 								clientId: agents.clientId,
+								runtimeProvider: agents.runtimeProvider,
 								clientUserId: clients.userId,
 								managerUserId: members.userId
 							}).from(agents).leftJoin(clients, eq(agents.clientId, clients.id)).leftJoin(members, eq(agents.managerId, members.id)).where(and(eq(agents.uuid, bindRequest.agentId))).limit(1);
@@ -12844,6 +13870,10 @@ function clientWsRoutes(notifier, instanceId) {
 								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.NOT_OWNED);
 								return;
 							}
+							if (bindRequest.runtimeType !== agent.runtimeProvider) {
+								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.RUNTIME_PROVIDER_MISMATCH);
+								return;
+							}
 							await bindAgent(app.db, agent.id, {
 								clientId,
 								instanceId,
@@ -13025,122 +14055,722 @@ const CONNECT_JTI_TTL_MS = 6e5;
 async function signToken(secret, payload, expiry) {
 	return new SignJWT({ ...payload }).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(expiry).sign(secret);
 }
+/**
+* Sign an `(access, refresh)` pair for the given member. Used by both the
+* legacy username/password login path and the SaaS GitHub OAuth callback,
+* so the issuance shape stays in one place.
+*/
+async function signTokensForMember(jwtSecretKey, member) {
+	const secret = new TextEncoder().encode(jwtSecretKey);
+	const tokenBase = {
+		sub: member.userId,
+		memberId: member.memberId,
+		organizationId: member.organizationId,
+		role: member.role
+	};
+	return {
+		accessToken: await signToken(secret, {
+			...tokenBase,
+			type: "access"
+		}, ACCESS_TOKEN_EXPIRY),
+		refreshToken: await signToken(secret, {
+			...tokenBase,
+			type: "refresh"
+		}, REFRESH_TOKEN_EXPIRY)
+	};
+}
 async function login(db, username, password, jwtSecretKey) {
 	const [user] = await db.select().from(users).where(eq(users.username, username)).limit(1);
 	if (!user || user.status !== "active") throw new UnauthorizedError("Invalid username or password");
 	if (!await bcrypt.compare(password, user.passwordHash)) throw new UnauthorizedError("Invalid username or password");
-	const [member] = await db.select().from(members).where(eq(members.userId, user.id)).limit(1);
+	const [member] = await db.select().from(members).where(and(eq(members.userId, user.id), eq(members.status, "active"))).limit(1);
 	if (!member) throw new UnauthorizedError("No organization membership found");
+	const tokens = await signTokensForMember(jwtSecretKey, {
+		userId: user.id,
+		memberId: member.id,
+		organizationId: member.organizationId,
+		role: member.role
+	});
+	await db.update(users).set({ updatedAt: /* @__PURE__ */ new Date() }).where(eq(users.id, user.id));
+	return tokens;
+}
+async function refreshAccessToken(db, refreshToken, jwtSecretKey) {
 	const secret = new TextEncoder().encode(jwtSecretKey);
-	const tokenBase = {
+	let payload;
+	try {
+		const { payload: p } = await jwtVerify(refreshToken, secret);
+		payload = p;
+	} catch {
+		throw new UnauthorizedError("Invalid or expired refresh token");
+	}
+	if (payload.type !== "refresh" || !payload.sub) throw new UnauthorizedError("Invalid token type");
+	const [user] = await db.select({
+		id: users.id,
+		status: users.status
+	}).from(users).where(eq(users.id, payload.sub)).limit(1);
+	if (!user || user.status !== "active") throw new UnauthorizedError("User not found or suspended");
+	const [member] = await db.select().from(members).where(and(eq(members.id, payload.memberId), eq(members.status, "active"))).limit(1);
+	if (!member) throw new UnauthorizedError("Membership not found");
+	return { accessToken: await signToken(secret, {
 		sub: user.id,
 		memberId: member.id,
 		organizationId: member.organizationId,
+		role: member.role,
+		type: "access"
+	}, ACCESS_TOKEN_EXPIRY) };
+}
+/**
+* Generate a short-lived connect token for CLI authentication.
+* The connect token carries the member's identity and can be exchanged
+* for full access+refresh tokens via exchangeConnectToken().
+*
+* `iss` (when supplied) is stamped into the JWT so the CLI can derive
+* the hub URL with no additional argument. Production servers must
+* always pass it; dev callers may omit and the CLI will require an
+* explicit `--server-url` (legacy form).
+*/
+async function generateConnectToken(member, jwtSecretKey, iss) {
+	const secret = new TextEncoder().encode(jwtSecretKey);
+	const jti = randomUUID();
+	const builder = new SignJWT({
+		sub: member.userId,
+		memberId: member.memberId,
+		organizationId: member.organizationId,
+		role: member.role,
+		type: "connect"
+	}).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setJti(jti).setExpirationTime(CONNECT_TOKEN_EXPIRY);
+	if (iss) builder.setIssuer(iss);
+	return {
+		token: await builder.sign(secret),
+		expiresIn: 600
+	};
+}
+/**
+* Exchange a connect token for full access+refresh tokens.
+* Validates the connect token, verifies the user is still active,
+* and issues a fresh token pair.
+*/
+async function exchangeConnectToken(db, connectToken, jwtSecretKey) {
+	const secret = new TextEncoder().encode(jwtSecretKey);
+	let payload;
+	try {
+		const { payload: p } = await jwtVerify(connectToken, secret);
+		payload = p;
+	} catch {
+		throw new UnauthorizedError("Invalid or expired connect token");
+	}
+	if (payload.type !== "connect" || !payload.sub || !payload.memberId) throw new UnauthorizedError("Invalid token type — expected connect token");
+	const jti = payload.jti;
+	if (jti) {
+		if (consumedConnectJtis.has(jti)) throw new UnauthorizedError("Connect token has already been used");
+		consumedConnectJtis.set(jti, Date.now());
+		const cutoff = Date.now() - CONNECT_JTI_TTL_MS;
+		for (const [k, ts] of consumedConnectJtis) if (ts < cutoff) consumedConnectJtis.delete(k);
+	}
+	const [user] = await db.select({
+		id: users.id,
+		status: users.status
+	}).from(users).where(eq(users.id, payload.sub)).limit(1);
+	if (!user || user.status !== "active") throw new UnauthorizedError("User not found or suspended");
+	const [member] = await db.select().from(members).where(and(eq(members.id, payload.memberId), eq(members.status, "active"))).limit(1);
+	if (!member) throw new UnauthorizedError("Membership not found");
+	return signTokensForMember(jwtSecretKey, {
+		userId: user.id,
+		memberId: member.id,
+		organizationId: member.organizationId,
 		role: member.role
+	});
+}
+/**
+* Third-party / local auth identities for a user. Models "how does this user
+* prove they are who they say they are". A single user MAY have multiple
+* identities (e.g. GitHub login + future email/password) but each
+* (provider, identifier) tuple maps to exactly one user.
+*
+* v1 supported shapes:
+*   - GitHub OAuth: provider='github', identifier=<github numeric id>,
+*     email=<primary>, credential_type=null
+*   - Future Email + password: provider='email', identifier=<email>,
+*     credential_type='password', credential_payload={ hash }
+*   - Future Email + magic link: provider='email', identifier=<email>,
+*     credential_type=null
+*   - Future Webauthn / passkey: credential_type='webauthn',
+*     credential_payload={ pubkey, counter }
+*
+* v1 explicitly does NOT support multi-factor on the same identity — the
+* (provider, identifier) UNIQUE constraint precludes two credential rows for
+* the same identifier. v2 splits credential_type / credential_payload into
+* a separate auth_credentials table; the migration is recorded in the
+* proposal so the upgrade path is unambiguous.
+*
+* The legacy `users.password_hash` column is preserved for backwards-compat
+* with self-host installs created before this milestone; new SaaS users get
+* a non-functional placeholder there and a real `auth_identities` row.
+*/
+const authIdentities = pgTable("auth_identities", {
+	id: text("id").primaryKey(),
+	userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+	provider: text("provider").notNull(),
+	identifier: text("identifier").notNull(),
+	email: text("email"),
+	verifiedAt: timestamp("verified_at", { withTimezone: true }),
+	credentialType: text("credential_type"),
+	credentialPayload: jsonb("credential_payload").$type(),
+	metadata: jsonb("metadata").$type().notNull().default({}),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	unique("uq_auth_identities_provider_identifier").on(table.provider, table.identifier),
+	index("idx_auth_identities_user").on(table.userId),
+	index("idx_auth_identities_email").on(table.email),
+	uniqueIndex("uq_auth_identities_user_github").on(table.userId).where(sql`provider = 'github'`)
+]);
+/**
+* Find or create the user backing a GitHub OAuth identity. Idempotent —
+* subsequent logins by the same `githubId` reuse the prior `user_id` row.
+*
+* SaaS users have no password. The legacy `users.password_hash` column is
+* NOT NULL (preserved for self-host), so we fill it with a non-functional
+* 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.
+*/
+async function findOrCreateUserFromGithub(db, profile) {
+	const [existing] = await db.select({ userId: authIdentities.userId }).from(authIdentities).where(and(eq(authIdentities.provider, "github"), eq(authIdentities.identifier, profile.githubId))).limit(1);
+	if (existing) {
+		if (profile.email) await db.update(authIdentities).set({
+			email: profile.email,
+			updatedAt: /* @__PURE__ */ new Date()
+		}).where(and(eq(authIdentities.provider, "github"), eq(authIdentities.identifier, profile.githubId)));
+		return { userId: existing.userId };
+	}
+	const userId = uuidv7();
+	const baseUsername = profile.login.toLowerCase();
+	const placeholderHash = `oauth:${randomBytes(32).toString("base64url")}`;
+	await insertWithUsernameRetry(db, baseUsername, async (tx, username) => {
+		await tx.insert(users).values({
+			id: userId,
+			username,
+			passwordHash: placeholderHash,
+			displayName: profile.displayName?.trim() || profile.login,
+			avatarUrl: profile.avatarUrl ?? null
+		});
+		await tx.insert(authIdentities).values({
+			id: uuidv7(),
+			userId,
+			provider: "github",
+			identifier: profile.githubId,
+			email: profile.email,
+			verifiedAt: /* @__PURE__ */ new Date(),
+			metadata: { login: profile.login }
+		});
+	});
+	return { userId };
+}
+/** Postgres `unique_violation` SQLSTATE — emitted when a UNIQUE constraint trips. */
+const PG_UNIQUE_VIOLATION$1 = "23505";
+/**
+* Pick a candidate username, attempt the caller's INSERT in a transaction,
+* and retry under a fresh disambiguator if the UNIQUE(users.username)
+* constraint trips. Two concurrent OAuth sign-ins for the same GitHub
+* `login` would otherwise let one INSERT win and the other 500 — the
+* race window between the pre-check `SELECT` and the `INSERT` is small but
+* non-zero in production. Retry budget is small; pathological storms fall
+* back to a fully-random suffix.
+*/
+async function insertWithUsernameRetry(db, base, insert) {
+	const [hit] = await db.select({ id: users.id }).from(users).where(eq(users.username, base)).limit(1);
+	let candidate = hit ? `${base}-${randomBytes(2).toString("hex")}` : base;
+	for (let attempt = 0; attempt < 4; attempt += 1) try {
+		await db.transaction(async (tx) => {
+			await insert(tx, candidate);
+		});
+		return;
+	} catch (err) {
+		if ((err?.code ?? err?.cause?.code) !== PG_UNIQUE_VIOLATION$1) throw err;
+		candidate = `${base}-${randomBytes(2).toString("hex")}`;
+	}
+	candidate = `${base}-${uuidv7().slice(0, 12)}`;
+	await db.transaction(async (tx) => {
+		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.
+*
+* 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 = {}) {
+	const fetcher = opts.fetcher ?? fetch;
+	const tokenRes = await fetcher(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
+		})
+	});
+	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}`,
+		Accept: "application/vnd.github+json"
+	} });
+	if (!userRes.ok) throw new Error(`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}`,
+			Accept: "application/vnd.github+json"
+		} });
+		if (emailsRes.ok) {
+			const emails = await emailsRes.json();
+			email = (emails.find((e) => e.primary && e.verified) ?? emails.find((e) => e.verified))?.email ?? null;
+		}
+	}
+	return {
+		githubId: String(user.id),
+		login: user.login,
+		email,
+		displayName: user.name ?? null,
+		avatarUrl: user.avatar_url ?? null
 	};
-	const accessToken = await signToken(secret, {
-		...tokenBase,
-		type: "access"
-	}, ACCESS_TOKEN_EXPIRY);
-	const refreshToken = await signToken(secret, {
-		...tokenBase,
-		type: "refresh"
-	}, REFRESH_TOKEN_EXPIRY);
-	await db.update(users).set({ updatedAt: /* @__PURE__ */ new Date() }).where(eq(users.id, user.id));
+}
+/** Insert (or reactivate) a `members` row for `userId` in `organizationId`. */
+async function ensureMembership(db, data) {
+	const [existing] = await db.select().from(members).where(and(eq(members.userId, data.userId), eq(members.organizationId, data.organizationId))).limit(1);
+	if (existing) {
+		if (existing.status === "left") {
+			await db.update(members).set({ status: "active" }).where(eq(members.id, existing.id));
+			return {
+				...existing,
+				status: "active"
+			};
+		}
+		return existing;
+	}
+	return db.transaction(async (tx) => {
+		const memberId = uuidv7();
+		const agentName = sanitizeAgentName(data.username);
+		const inboxId = `inbox_${uuidv7()}`;
+		const agentUuid = uuidv7();
+		await tx.insert(agents).values({
+			uuid: agentUuid,
+			name: agentName,
+			organizationId: data.organizationId,
+			type: "human",
+			displayName: data.displayName,
+			inboxId,
+			source: "oauth",
+			visibility: "organization",
+			managerId: memberId
+		});
+		const [row] = await tx.insert(members).values({
+			id: memberId,
+			userId: data.userId,
+			organizationId: data.organizationId,
+			agentId: agentUuid,
+			role: data.role,
+			status: "active"
+		}).returning();
+		if (!row) throw new Error("Unexpected: INSERT RETURNING produced no row");
+		return row;
+	});
+}
+function sanitizeAgentName(login) {
+	return login.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "user";
+}
+/**
+* Create a fresh "personal team" org for a brand-new user, plus the
+* matching admin membership + 1:1 human agent. Slug strategy:
+*
+*   - First try: `${login}-personal`
+*   - On collision: append a 4-char hex disambiguator
+*
+* The display name is `{user}'s Personal Team` so it reads sensibly in the
+* UI; the user can rename via Settings later (proposal §"Personal team
+* visual降级").
+*/
+async function createPersonalTeam(db, input) {
+	const baseSlug = sanitizeOrgSlug(`${input.loginSeed}-personal`);
+	const displayName = `${input.userDisplayName}'s Personal Team`;
+	const orgId = uuidv7();
+	return {
+		organizationId: orgId,
+		slug: await insertOrgWithSlugRetry(db, orgId, baseSlug, displayName),
+		displayName,
+		memberId: (await ensureMembership(db, {
+			userId: input.userId,
+			organizationId: orgId,
+			role: "admin",
+			displayName: input.userDisplayName,
+			username: input.loginSeed
+		})).id
+	};
+}
+function sanitizeOrgSlug(raw) {
+	return raw.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "team";
+}
+/** Postgres `unique_violation` SQLSTATE — `organizations.name` UNIQUE tripping. */
+const PG_UNIQUE_VIOLATION = "23505";
+/**
+* Attempt INSERT into `organizations` with `base` slug, retrying with a
+* disambiguator on UNIQUE constraint violations. Two concurrent OAuth
+* sign-ins for the same GitHub `login` would race here without retry —
+* pre-check `SELECT` followed by `INSERT` has a TOCTOU window the unique
+* constraint catches but the catch path needs to exist. Returns the slug
+* actually used.
+*/
+async function insertOrgWithSlugRetry(db, orgId, base, displayName) {
+	const [existing] = await db.select({ id: organizations.id }).from(organizations).where(eq(organizations.name, base)).limit(1);
+	let candidate = existing ? `${base}-${randomBytes(2).toString("hex")}` : base;
+	for (let attempt = 0; attempt < 4; attempt += 1) try {
+		await db.insert(organizations).values({
+			id: orgId,
+			name: candidate,
+			displayName
+		});
+		return candidate;
+	} catch (err) {
+		if ((err?.code ?? err?.cause?.code) !== PG_UNIQUE_VIOLATION) throw err;
+		candidate = `${base}-${randomBytes(2).toString("hex")}`;
+	}
+	candidate = `${base}-${uuidv7().slice(0, 12)}`;
+	await db.insert(organizations).values({
+		id: orgId,
+		name: candidate,
+		displayName
+	});
+	return candidate;
+}
+/** List ACTIVE memberships (omit soft-deleted "left") for a user. */
+async function listActiveMemberships(db, userId) {
+	return await db.select({
+		memberId: members.id,
+		organizationId: members.organizationId,
+		role: members.role,
+		orgName: organizations.name,
+		orgDisplayName: organizations.displayName,
+		createdAt: members.createdAt
+	}).from(members).innerJoin(organizations, eq(members.organizationId, organizations.id)).where(and(eq(members.userId, userId), eq(members.status, "active"))).orderBy(desc(members.createdAt));
+}
+/**
+* Pick the most recently joined active membership — used after OAuth login
+* when the user already has at least one team but no `next` was specified.
+*/
+async function pickPrimaryMembership(db, userId) {
+	return (await listActiveMemberships(db, userId))[0] ?? 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
+* a v2 sweep job.
+*/
+async function leaveOrganization(db, memberId) {
+	const [existing] = await db.select().from(members).where(eq(members.id, memberId)).limit(1);
+	if (!existing) throw new NotFoundError(`Membership "${memberId}" not found`);
+	if (existing.status === "left") return existing;
+	await db.update(members).set({ status: "left" }).where(eq(members.id, memberId));
+	return {
+		...existing,
+		status: "left"
+	};
+}
+/**
+* Self-service "create another team" (operator clicks "Create team" in the
+* org switcher). Caller is the new team's admin. Slug uniqueness is
+* enforced by the underlying organizations.name UNIQUE constraint.
+*/
+async function selfCreateOrganization(db, data) {
+	const [collision] = await db.select({ id: organizations.id }).from(organizations).where(eq(organizations.name, data.name)).limit(1);
+	if (collision) throw new ConflictError(`Organization "${data.name}" already exists`);
+	if (data.name === "default") throw new BadRequestError("\"default\" is a reserved organization name");
+	const orgId = uuidv7();
+	await db.insert(organizations).values({
+		id: orgId,
+		name: data.name,
+		displayName: data.displayName
+	});
 	return {
-		accessToken,
-		refreshToken
+		organizationId: orgId,
+		memberId: (await ensureMembership(db, {
+			userId: data.userId,
+			organizationId: orgId,
+			role: "admin",
+			displayName: data.userDisplayName,
+			username: data.username
+		})).id,
+		name: data.name,
+		displayName: data.displayName
 	};
 }
-async function refreshAccessToken(db, refreshToken, jwtSecretKey) {
-	const secret = new TextEncoder().encode(jwtSecretKey);
-	let payload;
-	try {
-		const { payload: p } = await jwtVerify(refreshToken, secret);
-		payload = p;
-	} catch {
-		throw new UnauthorizedError("Invalid or expired refresh token");
-	}
-	if (payload.type !== "refresh" || !payload.sub) throw new UnauthorizedError("Invalid token type");
-	const [user] = await db.select({
-		id: users.id,
-		status: users.status
-	}).from(users).where(eq(users.id, payload.sub)).limit(1);
-	if (!user || user.status !== "active") throw new UnauthorizedError("User not found or suspended");
-	const [member] = await db.select().from(members).where(eq(members.id, payload.memberId)).limit(1);
-	if (!member) throw new UnauthorizedError("Membership not found");
-	return { accessToken: await signToken(secret, {
-		sub: user.id,
-		memberId: member.id,
-		organizationId: member.organizationId,
-		role: member.role,
-		type: "access"
-	}, ACCESS_TOKEN_EXPIRY) };
-}
 /**
-* Generate a short-lived connect token for CLI authentication.
-* The connect token carries the member's identity and can be exchanged
-* for full access+refresh tokens via exchangeConnectToken().
+* State-token signing for the GitHub OAuth dance.
+*
+* Flow:
+*   1. `/auth/github/start` mints a `state` JWT *and* an HttpOnly cookie
+*      holding the same nonce. Both ride for ~10 minutes.
+*   2. GitHub redirects back to `/auth/github/callback?code=…&state=<jwt>`.
+*   3. Callback verifies the JWT (signature + expiry) AND that the cookie
+*      nonce matches `payload.nonce`. The double check defeats the
+*      classic login-CSRF where an attacker pre-signs a `start` with their
+*      own GitHub account and tricks a victim's browser into completing
+*      the callback under that identity.
+*
+* `next` rides inside the JWT so the caller's intended landing path can't
+* be tampered with mid-flight.
 */
-async function generateConnectToken(member, jwtSecretKey) {
-	const secret = new TextEncoder().encode(jwtSecretKey);
-	const jti = randomUUID();
+const STATE_EXPIRY = "10m";
+const NONCE_BYTES = 24;
+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) {
+	const nonce = randomBytes(NONCE_BYTES).toString("base64url");
+	const secret = new TextEncoder().encode(jwtSecret);
 	return {
 		token: await new SignJWT({
-			sub: member.userId,
-			memberId: member.memberId,
-			organizationId: member.organizationId,
-			role: member.role,
-			type: "connect"
-		}).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setJti(jti).setExpirationTime(CONNECT_TOKEN_EXPIRY).sign(secret),
-		expiresIn: 600
+			nonce,
+			next
+		}).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(STATE_EXPIRY).sign(secret),
+		nonce
 	};
 }
 /**
-* Exchange a connect token for full access+refresh tokens.
-* Validates the connect token, verifies the user is still active,
-* and issues a fresh token pair.
+* Verify a state token. Returns the carried `next` on success. Throws
+* `Error` with the verification failure mode on rejection so the route
+* layer can map to 401.
+*
+* Cookie/nonce double-submit is mandatory — this is the CSRF defense.
+* `/dev-callback` does NOT call this function; it bypasses state entirely
+* (see `api/auth/github.ts`) because the dev shortcut also bypasses the
+* github.com round-trip that would have set a state cookie.
 */
-async function exchangeConnectToken(db, connectToken, jwtSecretKey) {
-	const secret = new TextEncoder().encode(jwtSecretKey);
+async function verifyOAuthState(jwtSecret, token, cookieNonce) {
+	const secret = new TextEncoder().encode(jwtSecret);
 	let payload;
 	try {
-		const { payload: p } = await jwtVerify(connectToken, secret);
+		const { payload: p } = await jwtVerify(token, secret);
 		payload = p;
 	} catch {
-		throw new UnauthorizedError("Invalid or expired connect token");
+		throw new Error("Invalid or expired OAuth state");
 	}
-	if (payload.type !== "connect" || !payload.sub || !payload.memberId) throw new UnauthorizedError("Invalid token type — expected connect token");
-	const jti = payload.jti;
-	if (jti) {
-		if (consumedConnectJtis.has(jti)) throw new UnauthorizedError("Connect token has already been used");
-		consumedConnectJtis.set(jti, Date.now());
-		const cutoff = Date.now() - CONNECT_JTI_TTL_MS;
-		for (const [k, ts] of consumedConnectJtis) if (ts < cutoff) consumedConnectJtis.delete(k);
+	if (typeof payload.nonce !== "string" || typeof payload.next !== "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 };
+}
+/**
+* Resolve the hub's public-facing base URL.
+*
+* Precedence:
+*   1. `app.config.server.publicUrl` — explicit configuration. Required in
+*      production (the boot check enforces it).
+*   2. The request's `Host` header (with `X-Forwarded-Proto` honored) —
+*      dev fallback so local quickstart works without extra config.
+*
+* Result is normalized to drop trailing slashes so callers can append
+* paths with a single leading `/`.
+*/
+function resolvePublicUrl(app, request) {
+	const configured = app.config.server.publicUrl;
+	if (configured && configured.length > 0) return configured.replace(/\/+$/, "");
+	return `${pickHeader(request.headers["x-forwarded-proto"]) ?? request.protocol}://${pickHeader(request.headers["x-forwarded-host"]) ?? pickHeader(request.headers.host) ?? request.hostname}`.replace(/\/+$/, "");
+}
+function pickHeader(value) {
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+/**
+* Manual cookie helpers — we don't pull in `@fastify/cookie` because the
+* SaaS onboarding flow needs exactly one cookie (the OAuth state nonce).
+* Parser tolerates the standard `name=value; name2=value2` format.
+*/
+function parseCookieHeader(header, name) {
+	if (!header) return null;
+	const raw = Array.isArray(header) ? header.join("; ") : header;
+	for (const entry of raw.split(/;\s*/)) {
+		const eq = entry.indexOf("=");
+		if (eq < 0) continue;
+		if (entry.slice(0, eq).trim() === name) return decodeURIComponent(entry.slice(eq + 1));
 	}
-	const [user] = await db.select({
-		id: users.id,
-		status: users.status
-	}).from(users).where(eq(users.id, payload.sub)).limit(1);
-	if (!user || user.status !== "active") throw new UnauthorizedError("User not found or suspended");
-	const [member] = await db.select().from(members).where(eq(members.id, payload.memberId)).limit(1);
-	if (!member) throw new UnauthorizedError("Membership not found");
-	const tokenBase = {
-		sub: user.id,
-		memberId: member.id,
-		organizationId: member.organizationId,
-		role: member.role
-	};
-	return {
-		accessToken: await signToken(secret, {
-			...tokenBase,
-			type: "access"
-		}, ACCESS_TOKEN_EXPIRY),
-		refreshToken: await signToken(secret, {
-			...tokenBase,
-			type: "refresh"
-		}, REFRESH_TOKEN_EXPIRY)
-	};
+	return null;
+}
+function buildCookie(opts) {
+	const sameSite = opts.sameSite ?? "Lax";
+	const parts = [
+		`${opts.name}=${encodeURIComponent(opts.value)}`,
+		"Path=/",
+		"HttpOnly",
+		`SameSite=${sameSite}`,
+		`Max-Age=${opts.maxAge}`
+	];
+	if (opts.secure) parts.push("Secure");
+	if (opts.maxAge <= 0) parts.push("Expires=Thu, 01 Jan 1970 00:00:00 GMT");
+	return parts.join("; ");
+}
+/**
+* GitHub OAuth surface. All routes are public (no member JWT required).
+*
+* Routes:
+*   - GET /auth/github/start         — sign state JWT + cookie + 302 to GitHub
+*   - GET /auth/github/callback      — verify state + exchange code → fragment
+*   - 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.");
+	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" });
+		const { token, nonce } = await signOAuthState(app.config.secrets.jwtSecret, safeNext);
+		const isProd = process.env.NODE_ENV === "production";
+		reply.header("Set-Cookie", buildCookie({
+			name: OAUTH_STATE_COOKIE,
+			value: nonce,
+			maxAge: 600,
+			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",
+			allow_signup: "true"
+		});
+		return reply.redirect(`https://github.com/login/oauth/authorize?${params}`, 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);
+		const cookieNonce = parseCookieHeader(request.headers.cookie, OAUTH_STATE_COOKIE);
+		let next;
+		try {
+			next = (await verifyOAuthState(app.config.secrets.jwtSecret, state, cookieNonce)).next;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : "OAuth state rejected";
+			return reply.status(401).send({ error: msg });
+		}
+		reply.header("Set-Cookie", buildCookie({
+			name: OAUTH_STATE_COOKIE,
+			value: "",
+			maxAge: 0,
+			secure: process.env.NODE_ENV === "production"
+		}));
+		const redirectUri = `${resolvePublicUrl(app, request)}/api/v1/auth/github/callback`;
+		let profile;
+		try {
+			profile = await exchangeCodeForProfile({
+				clientId: oauthCfg.clientId,
+				clientSecret: oauthCfg.clientSecret
+			}, code, redirectUri);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : "GitHub exchange failed";
+			app.log.warn({ err }, "github oauth code exchange failed");
+			return reply.status(401).send({ error: msg });
+		}
+		return completeOauthFlow(app, request, reply, profile, next);
+	});
+	app.get("/dev-callback", async (request, reply) => {
+		if (process.env.NODE_ENV === "production") 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, {
+			githubId: params.githubId,
+			login: params.login,
+			email: params.email ?? null,
+			displayName: params.displayName ?? params.login,
+			avatarUrl: null
+		}, next);
+	});
+}
+async function completeOauthFlow(app, request, reply, profile, next) {
+	const { userId } = await findOrCreateUserFromGithub(app.db, profile);
+	let joinPath = "returning";
+	const inviteMatch = /^\/invite\/([^/?#]+)/.exec(next);
+	let memberInfo = null;
+	if (inviteMatch?.[1]) {
+		const token = inviteMatch[1];
+		const inv = await findActiveByToken(app.db, token);
+		if (!inv) return reply.status(404).send({ error: "Invitation not found or no longer valid" });
+		const member = await ensureMembership(app.db, {
+			userId,
+			organizationId: inv.organizationId,
+			role: inv.role === "admin" ? "admin" : "member",
+			displayName: profile.displayName?.trim() || profile.login,
+			username: profile.login
+		});
+		await recordRedemption(app.db, {
+			invitationId: inv.id,
+			userId,
+			ip: request.ip,
+			userAgent: request.headers["user-agent"] ?? null
+		});
+		memberInfo = {
+			memberId: member.id,
+			organizationId: member.organizationId,
+			role: member.role === "admin" ? "admin" : "member"
+		};
+		joinPath = "invite";
+		next = "/";
+	} else {
+		const primary = await pickPrimaryMembership(app.db, userId);
+		if (primary) memberInfo = {
+			memberId: primary.memberId,
+			organizationId: primary.organizationId,
+			role: primary.role === "admin" ? "admin" : "member"
+		};
+		else {
+			const personal = await createPersonalTeam(app.db, {
+				userId,
+				loginSeed: profile.login,
+				userDisplayName: profile.displayName?.trim() || profile.login
+			});
+			memberInfo = {
+				memberId: personal.memberId,
+				organizationId: personal.organizationId,
+				role: "admin"
+			};
+			joinPath = "solo";
+			next = "/";
+		}
+	}
+	if (!memberInfo) return reply.status(500).send({ error: "Failed to resolve membership" });
+	const tokens = await signTokensForMember(app.config.secrets.jwtSecret, {
+		userId,
+		memberId: memberInfo.memberId,
+		organizationId: memberInfo.organizationId,
+		role: memberInfo.role
+	});
+	const fragment = new URLSearchParams({
+		access: tokens.accessToken,
+		refresh: tokens.refreshToken,
+		next,
+		joinPath
+	}).toString();
+	return reply.redirect(`/auth/github/complete#${fragment}`, 302);
 }
 async function authRoutes(app) {
 	const loginMax = app.config.rateLimit?.loginMax ?? 5;
@@ -13277,7 +14907,12 @@ async function healthzRoutes(app) {
 		}
 	});
 }
-/** GET /me — returns current user + member + agent info. */
+/**
+* `/me` and self-service organization routes (mounted under the member
+* auth hook). The legacy `GET /me` shape is preserved + extended with
+* `wizard` and `inviteUrl` (admin only) so the web SPA can derive its
+* landing UI without an extra round-trip.
+*/
 async function meRoutes(app) {
 	app.get("/me", async (request) => {
 		const m = requireMember(request);
@@ -13293,6 +14928,12 @@ async function meRoutes(app) {
 			displayName: agents.displayName,
 			inboxId: agents.inboxId
 		}).from(agents).where(eq(agents.uuid, m.agentId)).limit(1);
+		const wizardStep = await inferWizardStep(app, m);
+		let inviteUrl = null;
+		if (m.role === "admin") {
+			const inv = await getActiveInvitation(app.db, m.organizationId);
+			if (inv) inviteUrl = buildInviteUrl(resolvePublicUrl(app, request), inv.token);
+		}
 		return {
 			user: user ?? null,
 			member: {
@@ -13301,25 +14942,202 @@ async function meRoutes(app) {
 				role: m.role,
 				agentId: m.agentId
 			},
-			agent: agent ?? null
+			agent: agent ?? null,
+			wizard: { step: wizardStep },
+			inviteUrl
 		};
 	});
 	/**
 	* POST /connect-tokens — generate a short-lived connect token for CLI authentication.
-	* The token can be exchanged via POST /auth/connect-token for full credentials.
+	* Stamped with `iss = server.publicUrl` (or the request host as a dev fallback)
+	* so the CLI's `connect <token>` form can derive the hub URL with no extra arg.
+	*
+	* Rate-limited per-route at the same level as `/auth/login`: a "Copy
+	* commands" double-click in the wizard mustn't burn through token slots,
+	* but neither should a stolen access token mint unlimited connect tokens.
 	*/
-	app.post("/connect-tokens", async (request) => {
+	const loginMax = app.config.rateLimit?.loginMax ?? 5;
+	app.post("/connect-tokens", { config: { rateLimit: {
+		max: loginMax,
+		timeWindow: "1 minute"
+	} } }, async (request) => {
 		const m = requireMember(request);
+		const issuer = resolvePublicUrl(app, request);
 		const { token, expiresIn } = await generateConnectToken({
 			userId: m.userId,
 			memberId: m.memberId,
 			organizationId: m.organizationId,
 			role: m.role
-		}, app.config.secrets.jwtSecret);
+		}, app.config.secrets.jwtSecret, issuer);
 		return {
 			token,
 			expiresIn,
-			command: `first-tree-hub client connect ${`${request.headers["x-forwarded-proto"] ?? request.protocol}://${request.headers["x-forwarded-host"] ?? request.headers.host ?? request.hostname}`} --token ${token}`
+			command: `first-tree-hub connect ${token}`
+		};
+	});
+	app.get("/me/organizations", async (request) => {
+		const m = requireMember(request);
+		return (await listActiveMemberships(app.db, m.userId)).map((r) => ({
+			id: r.organizationId,
+			name: r.orgName,
+			displayName: r.orgDisplayName,
+			role: r.role
+		}));
+	});
+	app.post("/me/organizations", async (request, reply) => {
+		const m = requireMember(request);
+		const body = createOrgFromMeSchema.parse(request.body);
+		const [u] = await app.db.select({
+			username: users.username,
+			displayName: users.displayName
+		}).from(users).where(eq(users.id, m.userId)).limit(1);
+		if (!u) throw new NotFoundError("User not found");
+		const created = await selfCreateOrganization(app.db, {
+			userId: m.userId,
+			userDisplayName: u.displayName,
+			username: u.username,
+			name: body.name,
+			displayName: body.displayName
+		});
+		const tokens = await signTokensForMember(app.config.secrets.jwtSecret, {
+			userId: m.userId,
+			memberId: created.memberId,
+			organizationId: created.organizationId,
+			role: "admin"
+		});
+		return reply.status(201).send({
+			organization: {
+				id: created.organizationId,
+				name: created.name,
+				displayName: created.displayName,
+				role: "admin"
+			},
+			tokens
+		});
+	});
+	app.post("/me/organizations/join", { config: { rateLimit: {
+		max: loginMax,
+		timeWindow: "1 minute"
+	} } }, async (request, reply) => {
+		const m = requireMember(request);
+		const body = joinByInvitationSchema.parse(request.body);
+		const inv = await findActiveByToken(app.db, body.token);
+		if (!inv) return reply.status(404).send({ error: "Invitation not found or no longer valid" });
+		const [u] = await app.db.select({
+			username: users.username,
+			displayName: users.displayName
+		}).from(users).where(eq(users.id, m.userId)).limit(1);
+		if (!u) throw new NotFoundError("User not found");
+		const member = await ensureMembership(app.db, {
+			userId: m.userId,
+			organizationId: inv.organizationId,
+			role: inv.role === "admin" ? "admin" : "member",
+			displayName: u.displayName,
+			username: u.username
+		});
+		await recordRedemption(app.db, {
+			invitationId: inv.id,
+			userId: m.userId,
+			ip: request.ip,
+			userAgent: request.headers["user-agent"] ?? null
+		});
+		const tokens = await signTokensForMember(app.config.secrets.jwtSecret, {
+			userId: m.userId,
+			memberId: member.id,
+			organizationId: member.organizationId,
+			role: member.role
+		});
+		return reply.status(200).send({
+			organizationId: member.organizationId,
+			memberId: member.id,
+			role: member.role,
+			tokens
+		});
+	});
+	app.post("/me/organizations/leave", async (request, reply) => {
+		const m = requireMember(request);
+		await leaveOrganization(app.db, m.memberId);
+		return reply.status(204).send();
+	});
+	app.post("/auth/switch-org", async (request, reply) => {
+		const m = requireMember(request);
+		const body = switchOrgSchema.parse(request.body);
+		const [target] = await app.db.select().from(members).where(and(eq(members.userId, m.userId), eq(members.organizationId, body.organizationId), eq(members.status, "active"))).limit(1);
+		if (!target) throw new ForbiddenError("You do not belong to that organization");
+		const tokens = await signTokensForMember(app.config.secrets.jwtSecret, {
+			userId: m.userId,
+			memberId: target.id,
+			organizationId: target.organizationId,
+			role: target.role
+		});
+		return reply.send(tokens);
+	});
+}
+/**
+* Infer the wizard step from observable runtime state. Refer to
+* proposal §"Onboarding 状态推断" for the rationale.
+*
+* Note: we deliberately do NOT filter by `clients.status='connected'`
+* here. The original "fact-is-state" reading would have flapped between
+* `completed` and `connect` every time the user's client briefly went
+* offline — UX disaster (the onboarding modal would re-pop). "Ever
+* connected" (= a clients row exists at all for this user/org) is still
+* fact-derived: deleting the row really does rewind the wizard, and
+* that's the explicit reset path.
+*/
+async function inferWizardStep(app, m) {
+	const [hasClient] = await app.db.select({ id: clients.id }).from(clients).where(and(eq(clients.userId, m.userId), eq(clients.organizationId, m.organizationId))).limit(1);
+	if (!hasClient) return "connect";
+	const [hasAgent] = await app.db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.managerId, m.memberId), ne(agents.type, "human"), eq(agents.status, "active"))).limit(1);
+	if (!hasAgent) return "create_agent";
+	return "completed";
+}
+/**
+* Public route exported separately so it mounts BEFORE the member auth hook.
+* Just exposes the org's display name & slug for the unauthenticated `/invite/:token`
+* landing page.
+*/
+async function publicInvitePreviewRoute(app) {
+	const { previewInvitation } = await import("./invitation-BTlGMy0o-Coj07kYi.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);
+		return reply.send(preview);
+	});
+}
+/**
+* Admin-only invitation routes — mounted under `/admin/organizations/:id/invitations`.
+*/
+async function adminInvitationRoutes(app) {
+	app.get("/", async (request) => {
+		const m = requireMember(request);
+		if (m.role !== "admin") throw new ForbiddenError("Admin role required");
+		if (request.params.id !== m.organizationId) throw new ForbiddenError("Cannot inspect invitations for another organization");
+		const inv = await ensureActiveInvitation(app.db, m.organizationId, m.userId);
+		return {
+			id: inv.id,
+			organizationId: inv.organizationId,
+			token: inv.token,
+			inviteUrl: buildInviteUrl(resolvePublicUrl(app, request), inv.token),
+			role: inv.role,
+			createdAt: inv.createdAt.toISOString(),
+			expiresAt: inv.expiresAt ? inv.expiresAt.toISOString() : null
+		};
+	});
+	app.post("/rotate", async (request) => {
+		const m = requireMember(request);
+		if (m.role !== "admin") throw new ForbiddenError("Admin role required");
+		if (request.params.id !== m.organizationId) throw new ForbiddenError("Cannot rotate invitations for another organization");
+		const { rotateInvitation } = await import("./invitation-BTlGMy0o-Coj07kYi.mjs");
+		const inv = await rotateInvitation(app.db, m.organizationId, m.userId);
+		return {
+			id: inv.id,
+			organizationId: inv.organizationId,
+			token: inv.token,
+			inviteUrl: buildInviteUrl(resolvePublicUrl(app, request), inv.token),
+			role: inv.role,
+			createdAt: inv.createdAt.toISOString(),
+			expiresAt: inv.expiresAt ? inv.expiresAt.toISOString() : null
 		};
 	});
 }
@@ -13959,10 +15777,13 @@ var schema_exports = /* @__PURE__ */ __exportAll({
 	agentConfigs: () => agentConfigs,
 	agentPresence: () => agentPresence,
 	agents: () => agents,
+	authIdentities: () => authIdentities,
 	chatParticipants: () => chatParticipants,
 	chats: () => chats,
 	clients: () => clients,
 	inboxEntries: () => inboxEntries,
+	invitationRedemptions: () => invitationRedemptions,
+	invitations: () => invitations,
 	members: () => members,
 	messages: () => messages,
 	notifications: () => notifications,
@@ -14674,6 +16495,7 @@ function createConfigService(opts) {
 	*/
 	function applyPatch(current, patch) {
 		return {
+			kind: current.kind,
 			prompt: patch.prompt ?? current.prompt,
 			model: patch.model ?? current.model,
 			mcpServers: patch.mcpServers ?? current.mcpServers,
@@ -14699,13 +16521,26 @@ function createConfigService(opts) {
 	async function readRow(agentId) {
 		const [row] = await db.select().from(agentConfigs).where(eq(agentConfigs.agentId, agentId)).limit(1);
 		if (!row) throw new NotFoundError(`Agent config "${agentId}" not found`);
-		return row;
+		const payload = agentRuntimeConfigPayloadSchema$1.parse(row.payload);
+		return {
+			...row,
+			payload
+		};
+	}
+	async function readRuntimeProviderFor(agentId) {
+		const [row] = await db.select({ runtimeProvider: agents.runtimeProvider }).from(agents).where(eq(agents.uuid, agentId)).limit(1);
+		if (!row) throw new NotFoundError(`Agent "${agentId}" not found`);
+		return row.runtimeProvider;
 	}
 	async function commitWrite(agentId, patch, expectedVersion, updatedBy) {
 		const current = await readRow(agentId);
 		if (current.version !== expectedVersion) throw new ConflictError(`Agent config "${agentId}" version mismatch: expected ${expectedVersion}, got ${current.version}`);
-		const merged = applyPatch(current.payload, patch);
-		const validated = agentRuntimeConfigPayloadSchema$1.parse(merged);
+		const provider = await readRuntimeProviderFor(agentId);
+		const synced = {
+			...applyPatch(current.payload, patch),
+			kind: provider
+		};
+		const validated = agentRuntimeConfigPayloadSchema$1.parse(synced);
 		const [updated] = await db.update(agentConfigs).set({
 			version: sql`${agentConfigs.version} + 1`,
 			payload: validated,
@@ -14812,7 +16647,12 @@ function createConfigService(opts) {
 		},
 		async dryRun(agentId, patch) {
 			const row = await readRow(agentId);
-			const next = agentRuntimeConfigPayloadSchema$1.parse(applyPatch(row.payload, patch));
+			const provider = await readRuntimeProviderFor(agentId);
+			const synced = {
+				...applyPatch(row.payload, patch),
+				kind: provider
+			};
+			const next = agentRuntimeConfigPayloadSchema$1.parse(synced);
 			const diff = computeDiff(row.payload, next);
 			return {
 				current: {
@@ -15217,6 +17057,8 @@ async function buildApp(config) {
 		await api.register(healthRoutes);
 		await api.register(githubWebhookRoutes, { prefix: "/webhooks" });
 		await api.register(authRoutes, { prefix: "/auth" });
+		await api.register(githubOauthRoutes, { prefix: "/auth/github" });
+		await api.register(publicInvitePreviewRoute, { prefix: "/invite" });
 		await api.register(contextTreeInfoRoutes, { prefix: "/context-tree" });
 		await api.register(bootstrapConfigRoutes, { prefix: "/bootstrap" });
 		await api.register(async (adminApp) => {
@@ -15277,6 +17119,10 @@ async function buildApp(config) {
 			adminApp.addHook("onRequest", adminOnly);
 			await adminApp.register(adminOrganizationRoutes);
 		}, { prefix: "/admin/organizations" });
+		await api.register(async (adminApp) => {
+			adminApp.addHook("onRequest", memberAuth);
+			await adminApp.register(adminInvitationRoutes);
+		}, { prefix: "/admin/organizations/:id/invitations" });
 		await api.register(async (adminApp) => {
 			adminApp.addHook("onRequest", memberAuth);
 			adminApp.addHook("onRequest", adminOnly);
@@ -15488,7 +17334,7 @@ async function startServer(options) {
 		instanceId: `srv_${randomUUID().slice(0, 8)}`,
 		commandVersion: COMMAND_VERSION
 	};
-	const { initTelemetry, shutdownTelemetry } = await import("./observability-DDkJwSKv.mjs");
+	const { initTelemetry, shutdownTelemetry } = await import("./observability-C08jUFsJ.mjs");
 	await initTelemetry(serverConfig.observability.tracing, config.instanceId);
 	const app = await buildApp(config);
 	const shutdown = async () => {
@@ -15714,4 +17560,187 @@ function createExecuteUpdate({ managed }) {
 	};
 }
 //#endregion
-export { configureClientLoggerForService as $, installClientService as A, createOwner as B, checkNodeVersion as C, checkWebSocket as D, checkServerReachable as E, isDockerAvailable as F, setJsonMode as G, resolveReplyToFromEnv as H, stopPostgres as I, FirstTreeHubSDK as J, status as K, ClientRuntime as L, resolveCliInvocation as M, uninstallClientService as N, printResults as O, ensurePostgres as P, applyClientLoggerConfig as Q, handleClientOrgMismatch as R, checkDocker as S, checkServerHealth as T, blank as U, hasUser as V, print as W, SessionRegistry as X, SdkError as Y, cleanWorkspaces as Z, runMigrations as _, COMMAND_VERSION as a, checkClientConfig as b, promptMissingFields as c, onboardCheck as d, onboardCreate as f, migrateLocalAgentDirs as g, createApiNameResolver as h, startServer as i, isServiceSupported as j, getClientServiceStatus as k, formatCheckReport as l, runHomeMigration as m, declineUpdate as n, isInteractive as o, saveOnboardState as p, ClientOrgMismatchError$1 as q, promptUpdate as r, promptAddAgent as s, createExecuteUpdate as t, loadOnboardState as u, checkAgentConfigs as v, checkServerConfig as w, checkDatabase as x, checkBackgroundService as y, rotateClientIdWithBackup as z };
+//#region src/commands/saas-connect.ts
+/**
+* @internal
+* Decode a JWT payload without verifying its signature. Used only by the
+* CLI's account-switch prompt and the URL-derivation helper below. Not
+* re-exported from `packages/command/src/index.ts` — external consumers
+* should call `deriveHubUrlFromToken` instead.
+*/
+function decodeJwtPayload(token) {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3 || !parts[1]) return null;
+		const raw = Buffer.from(parts[1], "base64url").toString();
+		const obj = JSON.parse(raw);
+		if (typeof obj !== "object" || obj === null) return null;
+		return obj;
+	} catch {
+		return null;
+	}
+}
+var HubUrlDerivationError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "HubUrlDerivationError";
+	}
+};
+/**
+* Derive the hub URL from a connect token's `iss` claim. Throws
+* `HubUrlDerivationError` when the claim is missing or malformed — we
+* *never* fall back to a default URL because that would let a stale
+* connect token from one environment silently re-target another (prod →
+* staging foot-gun).
+*
+* The action handler maps the thrown error to a `fail()` exit so this
+* function stays unit-testable without spawning a subprocess.
+*/
+function deriveHubUrlFromToken(token) {
+	const payload = decodeJwtPayload(token);
+	if (!payload) throw new HubUrlDerivationError("INVALID_TOKEN", "Connect token is not a valid JWT. Generate a new one from your Hub web console.");
+	const iss = payload.iss;
+	if (typeof iss !== "string" || iss.length === 0) throw new HubUrlDerivationError("TOKEN_MISSING_ISS", "Connect token does not carry an issuer (`iss` claim). Generate a new token from a Hub running v0.10+.");
+	if (!/^https?:\/\//i.test(iss)) throw new HubUrlDerivationError("TOKEN_BAD_ISS", `Connect token issuer "${iss}" is not an http(s) URL. Generate a new token.`);
+	return iss.replace(/\/+$/, "");
+}
+async function promptReplaceOrCancel(newMemberId) {
+	const existing = loadCredentials();
+	if (!existing) return "proceed";
+	const existingPayload = decodeJwtPayload(existing.accessToken);
+	const existingMemberId = typeof existingPayload?.memberId === "string" ? existingPayload.memberId : null;
+	if (existingMemberId && existingMemberId === newMemberId) return "proceed";
+	const existingMember = existingMemberId ? `member ${existingMemberId.slice(0, 8)}` : "unknown account";
+	const serviceStatus = getClientServiceStatus();
+	const serviceLine = serviceStatus.state === "active" ? `running (${serviceStatus.detail ?? "live"})` : serviceStatus.state === "inactive" ? `installed but not running${serviceStatus.detail ? ` — ${serviceStatus.detail}` : ""}` : "not installed";
+	print.line("\n  ⚠️  This computer is already connected under another account.\n\n");
+	print.line(`       Existing account:  ${existingMember}\n`);
+	print.line(`       Server:            ${existing.serverUrl}\n`);
+	print.line(`       Background service: ${serviceLine}\n\n`);
+	print.line("     Replacing only affects THIS computer. Server-side data is untouched.\n\n");
+	return await select({
+		message: "How would you like to continue?",
+		choices: [{
+			name: "Replace — log out the other account and set up this one",
+			value: "replace"
+		}, {
+			name: "Cancel  — keep the existing setup",
+			value: "cancel"
+		}]
+	}) === "replace" ? "proceed" : "cancel";
+}
+async function exchangeToken(url, token) {
+	const res = await fetch(`${url}/api/v1/auth/connect-token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ token }),
+		signal: AbortSignal.timeout(1e4)
+	});
+	if (!res.ok) fail("AUTH_ERROR", (await res.json().catch(() => ({}))).error ?? `Token exchange failed (HTTP ${res.status})`, 1);
+	return await res.json();
+}
+/**
+* Top-level `first-tree-hub connect <token>`. Single positional, no flags,
+* no env-var override — the connect token's `iss` claim carries the hub
+* URL so prod / staging / local environments are tagged at issuance and
+* the operator can never accidentally cross-target.
+*/
+function registerSaaSConnectCommand(program) {
+	program.command("connect <token>").description("Connect this computer to the Hub using a token from the web console").option("--no-service", "Skip background service install (runs inline until Ctrl+C)").action(async (token, options) => {
+		try {
+			let url;
+			try {
+				url = deriveHubUrlFromToken(token);
+			} catch (err) {
+				if (err instanceof HubUrlDerivationError) fail(err.code, err.message, 1);
+				throw err;
+			}
+			const payload = decodeJwtPayload(token);
+			const newMemberId = typeof payload?.memberId === "string" ? payload.memberId : null;
+			if (newMemberId) {
+				if (await promptReplaceOrCancel(newMemberId) === "cancel") {
+					print.line("\n  Cancelled. Existing setup untouched.\n");
+					return;
+				}
+			}
+			const tokens = await exchangeToken(url, token);
+			setConfigValue(join(DEFAULT_CONFIG_DIR, "client.yaml"), "server.url", url);
+			print.line(`\n  ✓ Hub: ${url}\n`);
+			saveCredentials({
+				...tokens,
+				serverUrl: url
+			});
+			print.line("  ✓ Authenticated\n");
+			resetConfig();
+			resetConfigMeta();
+			const config = await initConfig({
+				schema: clientConfigSchema,
+				role: "client"
+			});
+			print.line(`  ✓ Computer registered (id: ${config.client.id})\n`);
+			if (options.service !== false && isServiceSupported()) {
+				const info = installClientService();
+				print.line(`  ✓ Background service installed (${info.platform}) — you may close this terminal.\n`);
+				print.line(`    Logs: ${info.logDir}\n\n`);
+				return;
+			}
+			if (options.service === false) print.line("  (--no-service) running inline — Ctrl+C to stop\n");
+			else print.line(`  Background service not supported on ${process.platform}; running inline.\n`);
+			const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
+			try {
+				await migrateLocalAgentDirs({
+					agentsDir,
+					workspacesDir: join(DEFAULT_DATA_DIR$1, "workspaces"),
+					sessionsDir: join(DEFAULT_DATA_DIR$1, "sessions"),
+					resolver: createApiNameResolver(config.server.url, () => ensureFreshAccessToken())
+				});
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				print.status("⚠️", `agent-dir migration skipped: ${msg}`);
+			}
+			const agents = loadAgents({
+				schema: agentConfigSchema,
+				agentsDir
+			});
+			const runtime = new ClientRuntime(config.server.url, config.client.id, {
+				currentVersion: COMMAND_VERSION,
+				update: {
+					updateConfig: config.update,
+					prompt: promptUpdate,
+					executeUpdate: createExecuteUpdate({ managed: false })
+				}
+			});
+			for (const [name, agentConfig] of agents) runtime.addAgent(name, agentConfig);
+			await runtime.start();
+			runtime.watchAgentsDir(agentsDir);
+			const shutdown = async () => {
+				print.line("\n  Shutting down...\n");
+				runtime.unwatchAgentsDir();
+				await runtime.stop();
+				process.exit(0);
+			};
+			process.on("SIGINT", () => void shutdown());
+			process.on("SIGTERM", () => void shutdown());
+			await new Promise(() => {});
+		} catch (error) {
+			if (error.name === "ExitPromptError") {
+				print.line("\n  Cancelled.\n");
+				return;
+			}
+			if (error instanceof ClientOrgMismatchError) await handleClientOrgMismatch(error, {
+				managed: false,
+				configDir: DEFAULT_CONFIG_DIR,
+				rerunCommand: "first-tree-hub connect <token>"
+			});
+			const msg = error instanceof Error ? error.message : String(error);
+			print.line(`  Error: ${msg}\n`);
+			process.exit(1);
+		} finally {
+			resetConfig();
+			resetConfigMeta();
+		}
+	});
+}
+//#endregion
+export { status as $, checkServerHealth as A, isDockerAvailable as B, checkAgentConfigs as C, checkDocker as D, checkDatabase as E, installClientService as F, createOwner as G, ClientRuntime as H, isServiceSupported as I, fail as J, hasUser as K, resolveCliInvocation as L, checkWebSocket as M, printResults as N, checkNodeVersion as O, getClientServiceStatus as P, setJsonMode as Q, uninstallClientService as R, runMigrations as S, checkClientConfig as T, handleClientOrgMismatch as U, stopPostgres as V, rotateClientIdWithBackup as W, blank as X, success as Y, print as Z, onboardCreate as _, declineUpdate as a, probeCapabilities as at, createApiNameResolver as b, COMMAND_VERSION as c, isInteractive as d, ClientOrgMismatchError as et, promptAddAgent as f, onboardCheck as g, loadOnboardState as h, createExecuteUpdate as i, cleanWorkspaces as it, checkServerReachable as j, checkServerConfig as k, reconcileLocalRuntimeProviders as l, formatCheckReport as m, deriveHubUrlFromToken as n, SdkError as nt, promptUpdate as o, applyClientLoggerConfig as ot, promptMissingFields as p, resolveReplyToFromEnv as q, registerSaaSConnectCommand as r, SessionRegistry as rt, startServer as s, configureClientLoggerForService as st, HubUrlDerivationError as t, FirstTreeHubSDK as tt, uploadClientCapabilities as u, saveOnboardState as v, checkBackgroundService as w, migrateLocalAgentDirs as x, runHomeMigration as y, ensurePostgres as z };