@agent-team-foundation/first-tree-hub 0.10.2 → 0.10.4

package/dist/{saas-connect-idjpoPTk.mjs → saas-connect-2puW1r3r.mjs}

@@ -1,8 +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-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-Ca5Fiqz6.mjs";
-import { $ as sendMessageSchema, A as createOrganizationSchema, B as isRedactedEnvValue, C as connectTokenExchangeSchema, D as createChatSchema, E as createAgentSchema, F as githubCallbackQuerySchema, G as messageSourceSchema$1, H as joinByInvitationSchema, I as githubDevCallbackQuerySchema, J as refreshTokenSchema, K as notificationQuerySchema, L as githubStartQuerySchema, M as delegateFeishuUserSchema, N as dryRunAgentRuntimeConfigSchema, O as createMemberSchema, P as extractMentions, Q as selfServiceFeishuBotSchema, R as imageInlineContentSchema, S as clientRegisterSchema, T as createAdapterMappingSchema, U as linkTaskChatSchema, V as isReservedAgentName$1, W as loginSchema, X as safeRedirectPath, Y as runtimeStateMessageSchema, Z as scanMentionTokens, _ as adminUpdateTaskSchema, a as AGENT_STATUSES, at as sessionStateMessageSchema, b as agentRuntimeConfigPayloadSchema$1, c as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, ct as updateAdapterConfigSchema, d as TASK_HEALTH_SIGNALS, dt as updateChatSchema, et as sendToAgentSchema, f as TASK_STATUSES, ft as updateMemberSchema, g as adminCreateTaskSchema, gt as wsAuthFrameSchema, h as addParticipantSchema, ht as updateTaskStatusSchema, i as AGENT_SOURCES, it as sessionReconcileRequestSchema, j as createTaskSchema, k as createOrgFromMeSchema, l as SYSTEM_CONFIG_DEFAULTS, lt as updateAgentRuntimeConfigSchema, m as WS_AUTH_FRAME_TIMEOUT_MS, mt as updateSystemConfigSchema, n as AGENT_NAME_REGEX$1, nt as sessionEventMessageSchema, o as AGENT_TYPES, ot as switchOrgSchema, p as TASK_TERMINAL_STATUSES, pt as updateOrganizationSchema, q as paginationQuerySchema, r as AGENT_SELECTOR_HEADER$1, rt as sessionEventSchema$1, s as AGENT_VISIBILITY, st as taskListQuerySchema, t as AGENT_BIND_REJECT_REASONS, tt as sessionCompletionMessageSchema, u as TASK_CREATOR_TYPES, ut as updateAgentSchema, v as agentBindRequestSchema, w as createAdapterConfigSchema, x as agentTypeSchema$1, y as agentPinnedMessageSchema$1, z as inboxPollQuerySchema } from "./dist-CLiN7cVS.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 { 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-jx5nN1qZ.mjs";
+import { $ as refreshTokenSchema, A as createOrgFromMeSchema, B as imageInlineContentSchema, C as clientRegisterSchema, D as createAgentSchema, E as createAdapterMappingSchema, F as dryRunAgentRuntimeConfigSchema, G as isReservedAgentName$1, H as inboxDeliverFrameSchema$1, I as extractMentions, J as loginSchema, K as joinByInvitationSchema, L as githubCallbackQuerySchema, M as createTaskSchema, N as defaultRuntimeConfigPayload, O as createChatSchema, P as delegateFeishuUserSchema, Q as rebindAgentSchema, R as githubDevCallbackQuerySchema, S as clientCapabilitiesSchema$1, St as wsAuthFrameSchema, T as createAdapterConfigSchema, U as inboxPollQuerySchema, V as inboxAckFrameSchema, W as isRedactedEnvValue, X as notificationQuerySchema, Y as messageSourceSchema$1, Z as paginationQuerySchema, _ as adminUpdateTaskSchema, _t as updateClientCapabilitiesSchema, a as AGENT_STATUSES, at as sendToAgentSchema, b as agentRuntimeConfigPayloadSchema$1, bt as updateSystemConfigSchema, ct as sessionEventSchema$1, d as TASK_HEALTH_SIGNALS, dt as switchOrgSchema, et as runtimeStateMessageSchema, f as TASK_STATUSES, ft as taskListQuerySchema, g as adminCreateTaskSchema, gt as updateChatSchema, h as addParticipantSchema, ht as updateAgentSchema, i as AGENT_SOURCES, it as sendMessageSchema, j as createOrganizationSchema, k as createMemberSchema, l as SYSTEM_CONFIG_DEFAULTS, lt as sessionReconcileRequestSchema, m as WS_AUTH_FRAME_TIMEOUT_MS, mt as updateAgentRuntimeConfigSchema, n as AGENT_NAME_REGEX$1, nt as scanMentionTokens, o as AGENT_TYPES, ot as sessionCompletionMessageSchema, p as TASK_TERMINAL_STATUSES, pt as updateAdapterConfigSchema, q as linkTaskChatSchema, r as AGENT_SELECTOR_HEADER$1, rt as selfServiceFeishuBotSchema, s as AGENT_VISIBILITY, st as sessionEventMessageSchema, t as AGENT_BIND_REJECT_REASONS, tt as safeRedirectPath, u as TASK_CREATOR_TYPES, ut as sessionStateMessageSchema, v as agentBindRequestSchema, vt as updateMemberSchema, w as connectTokenExchangeSchema, x as agentTypeSchema$1, xt as updateTaskStatusSchema, y as agentPinnedMessageSchema$1, yt as updateOrganizationSchema, z as githubStartQuerySchema } from "./dist-CbX9mUVH.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-BljIolbO-DLeHfURd.mjs";
 import { createRequire } from "node:module";
 import { ZodError, z } from "zod";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
@@ -16,13 +16,14 @@ 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";
@@ -393,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";
@@ -421,6 +423,7 @@ z.object({
 	}),
 	clients: z.number().int()
 });
+const runtimeProviderSchema = z.enum(["claude-code", "codex"]);
 const agentTypeSchema = z.enum([
 	"human",
 	"personal_assistant",
@@ -462,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(),
@@ -473,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(),
@@ -487,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()
@@ -506,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
@@ -557,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: "" }),
@@ -568,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) => {
@@ -612,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(),
@@ -715,12 +754,53 @@ z.object({
 	lastSeenAt: z.string(),
 	metadata: z.record(z.string(), z.unknown()).nullable()
 });
+/**
+* Optional opt-in flags the client carries on `client:register` to advertise
+* which negotiable wire-protocol features it implements. Distinct from
+* `clientCapabilitiesSchema` (per-runtime-provider availability — different
+* concept). Older clients omit the field; the server treats every unset flag
+* as `false` and falls back to the legacy path. See proposal
+* hub-inbox-ws-data-plane §3.6.
+*/
+const clientWireCapabilitiesSchema = z.object({ wsInboxDeliver: z.boolean().default(false) }).partial();
 z.object({
 	clientId: z.string().min(1).max(100),
 	hostname: z.string().max(100).optional(),
 	os: z.string().max(50).optional(),
-	sdkVersion: z.string().max(50).optional()
+	sdkVersion: z.string().max(50).optional(),
+	wireCapabilities: clientWireCapabilitiesSchema.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()
@@ -898,11 +978,37 @@ z.object({
 	ackedAt: z.string().nullable()
 }).extend({ message: clientMessageSchema });
 z.object({ limit: z.coerce.number().int().min(1).max(50).default(10) });
+/**
+* server → client: a single inbox entry pushed over the active WS connection,
+* replacing the legacy `new_message` doorbell + HTTP `/inbox` poll round-trip.
+*
+* `entryId` is the server-side `inbox_entries.id` the client must echo back
+* in `inbox:ack`. `message` is exactly what the legacy poll path returned —
+* `clientMessageSchema` already carries `precedingMessages`, so the client-
+* side dispatch logic is reused verbatim (see proposal
+* hub-inbox-ws-data-plane §3.1).
+*
+* `.passthrough()` so a forward-rolling server may extend the frame without
+* breaking older clients that validate strictly. Older clients drop unknown
+* fields silently.
+*/
+const inboxDeliverFrameSchema = z.object({
+	type: z.literal("inbox:deliver"),
+	entryId: z.number().int().nonnegative(),
+	inboxId: z.string().min(1),
+	chatId: z.string().nullable(),
+	message: clientMessageSchema
+}).passthrough();
+z.object({
+	type: z.literal("inbox:ack"),
+	entryId: z.number().int().nonnegative()
+});
 z.object({
 	organizationId: z.string(),
 	organizationName: z.string(),
 	organizationDisplayName: z.string(),
-	role: z.string()
+	role: z.string(),
+	expiresAt: z.string().nullable()
 });
 z.object({
 	id: z.string(),
@@ -1273,6 +1379,13 @@ z.object({
 	token: z.string().min(1)
 });
 /**
+* Negotiable wire-protocol features the server advertises in its `welcome`
+* frame. Older clients drop the `capabilities` field silently because the
+* frame is `.passthrough()`. New clients gate optional code paths on it —
+* absent ⇒ feature off, never assumed.
+*/
+const serverCapabilitiesSchema = z.object({ wsInboxDeliver: z.boolean().default(false) }).partial();
+/**
 * Advisory frame sent server → client immediately after `auth:ok`. It carries
 * the Command-package version the server was bundled with, so the client can
 * detect version drift on startup and on each reconnect. `.passthrough()` so
@@ -1282,7 +1395,8 @@ z.object({
 const serverWelcomeFrameSchema = z.object({
 	type: z.literal("server:welcome"),
 	serverCommandVersion: z.string().min(1),
-	serverTimeMs: z.number().int().nonnegative()
+	serverTimeMs: z.number().int().nonnegative(),
+	capabilities: serverCapabilitiesSchema.optional()
 }).passthrough();
 /** Declare a config field with a Zod schema and optional metadata. */
 function field(schema, options) {
@@ -1410,8 +1524,7 @@ defineConfig({
 		clientSecret: field(z.string(), {
 			env: "FIRST_TREE_HUB_GITHUB_OAUTH_CLIENT_SECRET",
 			secret: true
-		}),
-		devCallbackEnabled: field(z.boolean().default(false), { env: "FIRST_TREE_HUB_GITHUB_OAUTH_DEV_CALLBACK" })
+		})
 	}) }),
 	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
 	rateLimit: optional({
@@ -1419,6 +1532,7 @@ defineConfig({
 		loginMax: field(z.number().default(5), { env: "FIRST_TREE_HUB_RATE_LIMIT_LOGIN_MAX" }),
 		webhookMax: field(z.number().default(60), { env: "FIRST_TREE_HUB_RATE_LIMIT_WEBHOOK_MAX" })
 	}),
+	inbox: optional({ maxInFlightPerAgent: field(z.number().int().min(1).max(1024).default(32), { env: "FIRST_TREE_HUB_INBOX_MAX_IN_FLIGHT_PER_AGENT" }) }),
 	kael: optional({
 		endpoint: field(z.string(), { env: "KAEL_ENDPOINT" }),
 		apiKey: field(z.string(), {
@@ -1536,6 +1650,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`;
@@ -1643,6 +1776,17 @@ const RECONNECT_MAX_MS = 3e4;
 const WS_CONNECT_TIMEOUT_MS = 1e4;
 const HEARTBEAT_INTERVAL_MS = 3e4;
 /**
+* Client-side opt-in for the WS inbox data plane. Gates BOTH the
+* `wireCapabilities.wsInboxDeliver` flag we declare on `client:register`
+* AND how we interpret the server's welcome capability — without this AND,
+* a future client kill-switch could land in a half-state where we tell the
+* server "no thanks" but still treat welcome's `wsInboxDeliver:true` as
+* authoritative and stop the 5s HTTP poll, leaving messages stuck if a
+* NOTIFY ever drops. Hard-coded `true` for now; flip to a config knob if
+* you need a runtime kill-switch.
+*/
+const WS_INBOX_DELIVER_OPT_IN = true;
+/**
 * Unified-user-token C5: reconnect PROACTIVELY this many ms before the JWT's
 * `exp` claim so the client rotates to a fresh JWT without ever hitting the
 * server-side `auth:expired` push. The provider's next `getAccessToken()` call
@@ -1694,6 +1838,15 @@ var ClientConnection = class extends EventEmitter {
 	/** Count of `server:welcome` frames received; drives `isReconnect` flag. */
 	welcomeFramesReceived = 0;
 	/**
+	* Whether the most recent `server:welcome` frame advertised
+	* `capabilities.wsInboxDeliver`. The runtime (AgentSlot) reads this
+	* (via {@link supportsWsInboxDeliver}) to decide whether to keep the
+	* legacy 5s HTTP poll or rely entirely on `inbox:deliver` push frames.
+	* Re-evaluated on every reconnect — the welcome frame is the source of
+	* truth, never assumed sticky across connections.
+	*/
+	wsInboxDeliverActive = false;
+	/**
 	* Last handshake error, stashed for the `close` handler to surface a typed
 	* reason (e.g. {@link ClientOrgMismatchError}) instead of a generic
 	* "closed before ready" when `connect()` is pending.
@@ -1729,6 +1882,30 @@ var ClientConnection = class extends EventEmitter {
 	get agents() {
 		return this.boundAgents;
 	}
+	/**
+	* True when the current connection's `server:welcome` advertised
+	* `capabilities.wsInboxDeliver` — meaning the server will push
+	* `inbox:deliver` frames and accept `inbox:ack` frames over this WS.
+	* Resets to false on every reconnect until the new welcome arrives.
+	*/
+	get supportsWsInboxDeliver() {
+		return this.wsInboxDeliverActive;
+	}
+	/**
+	* Ack a delivered inbox entry over the WS data plane. Replaces the legacy
+	* `sdk.ack()` HTTP call when the connection has negotiated
+	* `wsInboxDeliver`. Safe to call when the WS is closed — the frame is
+	* dropped silently and the entry will time out and re-deliver on
+	* reconnect, mirroring how the legacy timeout reaper handles HTTP
+	* ack-loss.
+	*/
+	sendInboxAck(entryId) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+		this.ws.send(JSON.stringify({
+			type: "inbox:ack",
+			entryId
+		}));
+	}
 	async connect() {
 		this.closing = false;
 		await this.openWebSocket();
@@ -1880,6 +2057,7 @@ var ClientConnection = class extends EventEmitter {
 				this.clearAuthRefreshTimer();
 				const wasRegistered = this.registered;
 				this.registered = false;
+				this.wsInboxDeliverActive = false;
 				this.rejectAllPendingBinds("WebSocket closed");
 				if (!settled) {
 					this.wsLogger.warn({ code }, "closed before ready");
@@ -1911,7 +2089,8 @@ var ClientConnection = class extends EventEmitter {
 				clientId: this.clientId,
 				hostname: hostname(),
 				os: platform(),
-				sdkVersion: this.sdkVersion
+				sdkVersion: this.sdkVersion,
+				wireCapabilities: { wsInboxDeliver: WS_INBOX_DELIVER_OPT_IN }
 			}));
 			return;
 		}
@@ -1921,6 +2100,7 @@ var ClientConnection = class extends EventEmitter {
 				this.wsLogger.warn({ issues: parsed.error.issues.map((i) => i.message) }, "ignoring malformed server:welcome frame");
 				return;
 			}
+			this.wsInboxDeliverActive = parsed.data.capabilities?.wsInboxDeliver === true && WS_INBOX_DELIVER_OPT_IN;
 			const isReconnect = this.welcomeFramesReceived > 0;
 			this.welcomeFramesReceived++;
 			this.emit("server:welcome", {
@@ -2065,6 +2245,25 @@ var ClientConnection = class extends EventEmitter {
 			else this.emit("agent:message", inboxId, msg);
 			return;
 		}
+		if (type === "inbox:deliver") {
+			const parsed = inboxDeliverFrameSchema.safeParse(msg);
+			if (!parsed.success) {
+				this.wsLogger.warn({
+					issues: parsed.error.issues.map((i) => ({
+						path: i.path.join("."),
+						code: i.code,
+						message: i.message
+					})),
+					frameKeys: Object.keys(msg),
+					messageKeys: msg.message && typeof msg.message === "object" ? Object.keys(msg.message) : null
+				}, "malformed inbox:deliver frame — dropping");
+				return;
+			}
+			const emit = () => this.emit("inbox:deliver", parsed.data.inboxId, parsed.data);
+			if (this.pendingImageWrites.size > 0) Promise.all([...this.pendingImageWrites]).finally(emit);
+			else emit();
+			return;
+		}
 		if (type === "error") {
 			const errorMsg = msg.message;
 			const ref = msg.ref;
@@ -2175,13 +2374,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, {
@@ -2207,6 +2416,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, {
@@ -2932,7 +3143,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",
@@ -3058,7 +3269,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",
@@ -3602,6 +3813,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();
@@ -3611,6 +4273,7 @@ function registerBuiltinHandlers() {
 		...config,
 		claudeCodeExecutable: resolution.path
 	}));
+	registerHandler("codex", (config) => createCodexHandler(config));
 }
 function createAgentConfigCache(opts) {
 	const { sdk } = opts;
@@ -3645,6 +4308,7 @@ function createAgentConfigCache(opts) {
 					agentId,
 					version: 0,
 					payload: {
+						kind: "claude-code",
 						prompt: { append: "" },
 						model: "",
 						mcpServers: [],
@@ -4325,11 +4989,19 @@ var SessionManager = class {
 		this.lastReportedStates.set(chatId, state);
 		this.config.onStateChange(chatId, state);
 	}
-	/** ACK an inbox entry — delayed until handler starts processing. */
+	/**
+	* ACK an inbox entry — delayed until handler starts processing.
+	*
+	* Routes through `config.ackEntry` when set (WS push path) or falls back to
+	* `sdk.ack` (HTTP poll path). One ack per entry, one channel per slot —
+	* mixing channels in one slot would leak the server's per-agent in-flight
+	* counter (proposal hub-inbox-ws-data-plane §3.5).
+	*/
 	async ackEntry(entryId, chatId) {
 		if (entryId === void 0) return;
 		try {
-			await this.config.sdk.ack(entryId);
+			if (this.config.ackEntry) await this.config.ackEntry(entryId);
+			else await this.config.sdk.ack(entryId);
 		} catch {
 			this.config.log.warn({
 				chatId,
@@ -4480,6 +5152,12 @@ var AgentSlot = class {
 	pollingTimer = null;
 	reconcileTimer = null;
 	listeners = [];
+	/**
+	* The inbox this slot's agent owns — used to filter `inbox:deliver`
+	* frames addressed to other agents on the same client. Captured at
+	* `start()` from `sdk.register()`.
+	*/
+	inboxId = null;
 	constructor(config) {
 		this.config = config;
 		this.logger = createLogger("slot").child({
@@ -4522,9 +5200,19 @@ var AgentSlot = class {
 			this.logger.error({ err }, "failed to fetch agent config — bind aborted");
 			throw new Error(`Hub unreachable while loading agent config: ${msg}`);
 		}
+		this.inboxId = agent.inboxId;
 		const onMessage = (agentId) => {
 			if (agentId === this.config.agentId) this.pullAndDispatch();
 		};
+		const onInboxDeliver = (inboxId, frame) => {
+			if (inboxId !== this.inboxId) return;
+			this.dispatchPushedFrame(frame).catch((err) => {
+				this.logger.warn({
+					err,
+					entryId: frame.entryId
+				}, "inbox:deliver dispatch error");
+			});
+		};
 		const onBound = (boundAgent) => {
 			if (boundAgent.agentId === this.config.agentId) {
 				this.fullStateSync();
@@ -4535,11 +5223,15 @@ var AgentSlot = class {
 			if (result.agentId === this.config.agentId && this.sessionManager) this.sessionManager.applyStaleChatIds(result.staleChatIds);
 		};
 		this.clientConnection.on("agent:message", onMessage);
+		this.clientConnection.on("inbox:deliver", onInboxDeliver);
 		this.clientConnection.on("agent:bound", onBound);
 		this.clientConnection.on("session:reconcile:result", onReconcileResult);
 		this.listeners.push({
 			event: "agent:message",
 			fn: onMessage
+		}, {
+			event: "inbox:deliver",
+			fn: onInboxDeliver
 		}, {
 			event: "agent:bound",
 			fn: onBound
@@ -4555,6 +5247,10 @@ var AgentSlot = class {
 				agentId: this.config.agentId
 			})
 		});
+		const ackEntry = this.clientConnection.supportsWsInboxDeliver ? (entryId) => {
+			this.clientConnection.sendInboxAck(entryId);
+			return Promise.resolve();
+		} : void 0;
 		this.sessionManager = new SessionManager({
 			session: this.config.session,
 			concurrency: this.config.concurrency,
@@ -4576,6 +5272,7 @@ var AgentSlot = class {
 			log: this.logger,
 			registryPath,
 			agentConfigCache: this.agentConfigCache,
+			ackEntry,
 			onStateChange: (chatId, state) => this.reportSessionState(chatId, state),
 			onRuntimeStateChange: (state) => this.reportRuntimeState(state),
 			onSessionEvent: (chatId, event) => this.reportSessionEvent(chatId, event),
@@ -4609,6 +5306,7 @@ var AgentSlot = class {
 			this.reconcileTimer = null;
 		}
 		for (const entry of this.listeners) if (entry.event === "agent:message") this.clientConnection.off(entry.event, entry.fn);
+		else if (entry.event === "inbox:deliver") this.clientConnection.off(entry.event, entry.fn);
 		else if (entry.event === "agent:bound") this.clientConnection.off(entry.event, entry.fn);
 		else if (entry.event === "session:reconcile:result") this.clientConnection.off(entry.event, entry.fn);
 		else this.clientConnection.off(entry.event, entry.fn);
@@ -4636,11 +5334,47 @@ var AgentSlot = class {
 		if (runtimeState) this.clientConnection.reportRuntimeState(this.config.agentId, runtimeState);
 	}
 	startPolling() {
+		if (this.clientConnection.supportsWsInboxDeliver) {
+			this.logger.info("WS inbox data plane active — skipping 5s HTTP poll");
+			return;
+		}
 		this.pollingTimer = setInterval(() => {
 			this.pullAndDispatch();
 		}, 5e3);
 		this.pullAndDispatch();
 	}
+	/**
+	* Translate an `inbox:deliver` push frame into the {@link InboxEntryWithMessage}
+	* shape `SessionManager.dispatch` expects, then dispatch.
+	*
+	* Ack happens INSIDE `dispatch` via the `ackEntry` callback we pinned at
+	* construction time — for push slots that's `clientConnection.sendInboxAck`,
+	* for poll slots it stays the legacy `sdk.ack`. Sending an additional ack
+	* here would double-ack: HTTP first (`delivered → acked`) followed by a
+	* WS frame the server can no longer match against any `delivered` row,
+	* which leaks the server's per-agent in-flight counter and stalls push
+	* after `inboxMaxInFlightPerAgent` messages.
+	*
+	* Dispatch errors propagate up; the entry stays `delivered` server-side
+	* and the 300s timeout reaper rolls it back to `pending` for replay
+	* (proposal §3.7).
+	*/
+	async dispatchPushedFrame(frame) {
+		if (!this.sessionManager) return;
+		const entry = {
+			id: frame.entryId,
+			inboxId: frame.inboxId,
+			messageId: frame.message.id,
+			chatId: frame.chatId,
+			status: "delivered",
+			retryCount: 0,
+			createdAt: frame.message.createdAt,
+			deliveredAt: (/* @__PURE__ */ new Date()).toISOString(),
+			ackedAt: null,
+			message: frame.message
+		};
+		await this.sessionManager.dispatch(entry);
+	}
 	startReconcileLoop() {
 		const intervalSec = this.config.session.reconcile_interval_seconds ?? 300;
 		this.reconcileTimer = setInterval(() => this.reconcileNow(), intervalSec * 1e3);
@@ -4662,6 +5396,226 @@ var AgentSlot = class {
 	}
 };
 /**
+* 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.
+*/
+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"
+	};
+}
+/**
+* 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).
+*/
+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
@@ -5285,7 +6239,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)`);
@@ -6598,7 +7552,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-FTWnoOsc.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-DvjRZMdZ.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 {
@@ -6761,6 +7715,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({
@@ -7518,7 +8532,7 @@ function createFeedbackHandler(config) {
 	return { handle };
 }
 //#endregion
-//#region ../server/dist/app-BvSSa9Ak.mjs
+//#region ../server/dist/app-fbgPnPWI.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -7572,6 +8586,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) => [
@@ -8241,7 +9256,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}"`);
@@ -8261,7 +9276,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,
@@ -8285,7 +9300,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,
@@ -8299,7 +9314,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();
 	});
@@ -8400,6 +9415,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) {
@@ -8420,6 +9467,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");
@@ -8452,9 +9525,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}`;
@@ -8480,6 +9554,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.`);
@@ -8498,13 +9573,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;
@@ -8558,6 +9634,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,
@@ -8595,6 +9672,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,
@@ -8614,7 +9692,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;
@@ -8645,6 +9723,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) {
@@ -9224,10 +10335,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`
@@ -9422,24 +10568,144 @@ function forceDisconnectClient(clientId) {
 	clientConnections.delete(clientId);
 	return agentIds;
 }
-/** Delivery queue (envelope). One entry per recipient created during message fan-out. Uses SKIP LOCKED for concurrent-safe consumption. */
-const inboxEntries = pgTable("inbox_entries", {
-	id: bigserial("id", { mode: "number" }).primaryKey(),
-	inboxId: text("inbox_id").notNull(),
-	messageId: text("message_id").notNull().references(() => messages.id),
-	chatId: text("chat_id"),
-	status: text("status").notNull().default("pending"),
-	notify: boolean("notify").notNull().default(true),
-	retryCount: integer("retry_count").notNull().default(0),
-	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
-	deliveredAt: timestamp("delivered_at", { withTimezone: true }),
-	ackedAt: timestamp("acked_at", { withTimezone: true })
-}, (table) => [
-	unique("uq_inbox_delivery").on(table.inboxId, table.messageId, table.chatId),
-	index("idx_inbox_pending").on(table.inboxId, table.createdAt),
-	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)
-]);
+/** Delivery queue (envelope). One entry per recipient created during message fan-out. Uses SKIP LOCKED for concurrent-safe consumption. */
+const inboxEntries = pgTable("inbox_entries", {
+	id: bigserial("id", { mode: "number" }).primaryKey(),
+	inboxId: text("inbox_id").notNull(),
+	messageId: text("message_id").notNull().references(() => messages.id),
+	chatId: text("chat_id"),
+	status: text("status").notNull().default("pending"),
+	notify: boolean("notify").notNull().default(true),
+	retryCount: integer("retry_count").notNull().default(0),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+	deliveredAt: timestamp("delivered_at", { withTimezone: true }),
+	ackedAt: timestamp("acked_at", { withTimezone: true })
+}, (table) => [
+	unique("uq_inbox_delivery").on(table.inboxId, table.messageId, table.chatId),
+	index("idx_inbox_pending").on(table.inboxId, table.createdAt),
+	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)
+]);
+/** 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,
@@ -9448,17 +10714,24 @@ async function sendMessage(db, chatId, senderId, data, options = {}) {
 	}), () => 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 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) {
-			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");
+			if (senderRow.inboxId !== data.replyToInbox) throw new BadRequestError("replyToInbox must reference the sender's own inbox");
 		}
 		const incomingMeta = data.metadata ?? {};
 		const explicitMentionsRaw = incomingMeta.mentions;
@@ -9503,14 +10776,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,
@@ -9529,9 +10808,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({
@@ -9605,27 +10899,31 @@ function createNotifier(listenClient) {
 		const messageId = payload.slice(sepIdx + 1);
 		const sockets = subscriptions.get(inboxId);
 		if (!sockets) return;
-		const data = JSON.stringify({
+		const doorbellFrame = JSON.stringify({
 			type: "new_message",
 			inboxId,
 			messageId
 		});
-		for (const ws of sockets) if (ws.readyState === ws.OPEN) ws.send(data);
+		for (const [ws, pushHandler] of sockets) {
+			if (ws.readyState !== ws.OPEN) continue;
+			if (pushHandler) Promise.resolve(pushHandler(messageId)).catch(() => {});
+			else ws.send(doorbellFrame);
+		}
 	}
 	return {
-		subscribe(inboxId, ws) {
-			let set = subscriptions.get(inboxId);
-			if (!set) {
-				set = /* @__PURE__ */ new Set();
-				subscriptions.set(inboxId, set);
+		subscribe(inboxId, ws, pushHandler) {
+			let map = subscriptions.get(inboxId);
+			if (!map) {
+				map = /* @__PURE__ */ new Map();
+				subscriptions.set(inboxId, map);
 			}
-			set.add(ws);
+			map.set(ws, pushHandler ?? null);
 		},
 		unsubscribe(inboxId, ws) {
-			const set = subscriptions.get(inboxId);
-			if (set) {
-				set.delete(ws);
-				if (set.size === 0) subscriptions.delete(inboxId);
+			const map = subscriptions.get(inboxId);
+			if (map) {
+				map.delete(ws);
+				if (map.size === 0) subscriptions.delete(inboxId);
 			}
 		},
 		async notify(inboxId, messageId) {
@@ -9649,11 +10947,11 @@ function createNotifier(listenClient) {
 			} catch {}
 		},
 		async pushFrameToInbox(inboxId, frame) {
-			const sockets = subscriptions.get(inboxId);
-			if (!sockets) return 0;
+			const map = subscriptions.get(inboxId);
+			if (!map) return 0;
 			let queued = 0;
 			const pending = [];
-			for (const ws of sockets) {
+			for (const ws of map.keys()) {
 				if (ws.readyState !== ws.OPEN) continue;
 				pending.push(new Promise((resolve) => {
 					ws.send(frame, (err) => {
@@ -9758,7 +11056,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({
@@ -9861,6 +11160,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);
@@ -10315,107 +11631,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;
@@ -10439,11 +11654,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,
@@ -10452,7 +11683,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) => {
@@ -12159,8 +13391,8 @@ async function pollInbox(db, inboxId, limit) {
 	}, () => pollInboxInner(db, inboxId, limit));
 }
 async function pollInboxInner(db, inboxId, limit) {
-	return await db.transaction(async (tx) => {
-		const claimed = await tx.execute(sql`
+	return db.transaction(async (tx) => {
+		return bundleDeliveryWithSilentContext(tx, inboxId, await tx.execute(sql`
       UPDATE inbox_entries
       SET status = 'delivered', delivered_at = NOW()
       WHERE id IN (
@@ -12171,53 +13403,132 @@ async function pollInboxInner(db, inboxId, limit) {
         FOR UPDATE SKIP LOCKED
       )
       RETURNING *
-    `);
-		if (claimed.length === 0) return [];
-		claimed.sort((a, b) => a.created_at.localeCompare(b.created_at));
-		const precedingByEntryId = await collectPrecedingContext(tx, inboxId, claimed);
-		const messageIds = claimed.map((e) => e.message_id);
-		const msgs = await tx.select().from(messages).where(inArray(messages.id, messageIds));
-		const msgMap = new Map(msgs.map((m) => [m.id, m]));
-		const payloads = await buildClientMessagePayloadsForInbox(tx, inboxId, claimed.map((entry) => {
-			const msg = msgMap.get(entry.message_id);
-			if (!msg) throw new Error(`Unexpected: message ${entry.message_id} not found`);
-			return {
-				entryChatId: entry.chat_id,
-				precedingMessages: precedingByEntryId.get(entry.id) ?? [],
-				message: {
-					id: msg.id,
-					chatId: msg.chatId,
-					senderId: msg.senderId,
-					format: msg.format,
-					content: msg.content,
-					metadata: msg.metadata,
-					replyToInbox: msg.replyToInbox,
-					replyToChat: msg.replyToChat,
-					inReplyTo: msg.inReplyTo,
-					source: msg.source,
-					createdAt: msg.createdAt.toISOString()
-				}
-			};
-		}));
-		return claimed.map((entry, idx) => {
-			const payload = payloads[idx];
-			if (!payload) throw new Error(`Unexpected: payload for entry ${entry.id} not built`);
-			return {
-				id: entry.id,
-				inboxId: entry.inbox_id,
-				messageId: entry.message_id,
-				chatId: entry.chat_id,
-				status: entry.status,
-				retryCount: entry.retry_count,
-				createdAt: entry.created_at,
-				deliveredAt: entry.delivered_at ?? null,
-				ackedAt: entry.acked_at ?? null,
-				message: payload
-			};
-		});
+    `));
+	});
+}
+/**
+* Shared payload assembler for already-claimed `inbox_entries` rows.
+*
+* Both the HTTP poll path (`pollInbox`) and the WS push path
+* (`claimAndBuildForPush`) call this with rows they have just `UPDATE`d to
+* `status='delivered'`. Keeping the silent-context bundling in one place is
+* the only way to keep the two paths from drifting (proposal
+* hub-inbox-ws-data-plane §3.2 risk #1).
+*
+* Steps:
+*   1. Sort by `created_at` ASC (PG `RETURNING` does not guarantee order).
+*   2. For each trigger, collect silent context & bulk-ack stale silent rows.
+*   3. Fetch the trigger messages.
+*   4. Build wire payloads via the single dispatcher.
+*
+* Returns `[]` if `claimed` is empty.
+*/
+async function bundleDeliveryWithSilentContext(tx, inboxId, claimed) {
+	if (claimed.length === 0) return [];
+	claimed.sort((a, b) => a.created_at.localeCompare(b.created_at));
+	const precedingByEntryId = await collectPrecedingContext(tx, inboxId, claimed);
+	const messageIds = claimed.map((e) => e.message_id);
+	const msgs = await tx.select().from(messages).where(inArray(messages.id, messageIds));
+	const msgMap = new Map(msgs.map((m) => [m.id, m]));
+	const payloads = await buildClientMessagePayloadsForInbox(tx, inboxId, claimed.map((entry) => {
+		const msg = msgMap.get(entry.message_id);
+		if (!msg) throw new Error(`Unexpected: message ${entry.message_id} not found`);
+		return {
+			entryChatId: entry.chat_id,
+			precedingMessages: precedingByEntryId.get(entry.id) ?? [],
+			message: {
+				id: msg.id,
+				chatId: msg.chatId,
+				senderId: msg.senderId,
+				format: msg.format,
+				content: msg.content,
+				metadata: msg.metadata,
+				replyToInbox: msg.replyToInbox,
+				replyToChat: msg.replyToChat,
+				inReplyTo: msg.inReplyTo,
+				source: msg.source,
+				createdAt: msg.createdAt.toISOString()
+			}
+		};
+	}));
+	return claimed.map((entry, idx) => {
+		const payload = payloads[idx];
+		if (!payload) throw new Error(`Unexpected: payload for entry ${entry.id} not built`);
+		return {
+			id: Number(entry.id),
+			inboxId: entry.inbox_id,
+			messageId: entry.message_id,
+			chatId: entry.chat_id,
+			status: entry.status,
+			retryCount: entry.retry_count,
+			createdAt: entry.created_at,
+			deliveredAt: entry.delivered_at ?? null,
+			ackedAt: entry.acked_at ?? null,
+			message: payload
+		};
 	});
 }
 /**
+* Realistic upper bound on rows a single NOTIFY references. The unique
+* constraint `(inbox_id, message_id, chat_id)` caps a `(inbox, message)`
+* pair at one row per chatId; the only way to exceed 1 today is the replyTo
+* cross-chat path (`message.ts` writes a second row keyed by the original's
+* `replyToChat`). 8 leaves headroom for any future fan-out variant without
+* requiring a schema change here.
+*/
+const PUSH_CLAIM_BATCH_LIMIT = 8;
+/**
+* WS-push path: atomically claim every pending entry the just-fired
+* `NOTIFY (inboxId:messageId)` references and assemble their wire payloads.
+*
+* Returns `[]` if no row matches — benign race with HTTP poll or another
+* server instance that already claimed the entry. NOTIFY is fire-and-forget
+* (proposal §3.2).
+*
+* Why an array, not a single row: `sendMessage` can write **two** rows for
+* the same `(inbox, messageId)` pair when the recipient is both a chat
+* participant and the `replyToInbox` of an earlier message — the unique key
+* is `(inbox_id, message_id, chat_id)`, so the rows differ by chatId. The
+* old `LIMIT 1` shape would only push the first; the second sat `pending`
+* until reconnect. Aligning with `pollInboxInner`'s `LIMIT N` shape closes
+* that gap and keeps push/poll behaviour interchangeable.
+*/
+async function claimAndBuildForPush(db, inboxId, messageId) {
+	return withSpan("inbox.deliver.push", {
+		"inbox.id": inboxId,
+		"message.id": messageId
+	}, () => db.transaction(async (tx) => {
+		return bundleDeliveryWithSilentContext(tx, inboxId, await tx.execute(sql`
+          UPDATE inbox_entries
+          SET status = 'delivered', delivered_at = NOW()
+          WHERE id IN (
+            SELECT id FROM inbox_entries
+            WHERE inbox_id = ${inboxId}
+              AND message_id = ${messageId}
+              AND status = 'pending'
+              AND notify = true
+            ORDER BY created_at
+            LIMIT ${PUSH_CLAIM_BATCH_LIMIT}
+            FOR UPDATE SKIP LOCKED
+          )
+          RETURNING *
+        `));
+	}));
+}
+/**
+* WS-push backlog path: on agent rebind (or once an in-flight slot frees up
+* after an ack), drain up to `limit` pending `notify=true` entries oldest-
+* first and assemble wire payloads. Identical claim shape to the HTTP poll
+* path — they are intentionally interchangeable so a hot-path bug fixed in
+* one shows up in the other (proposal §3.3 / §3.5).
+*/
+async function claimBacklogForPush(db, inboxId, limit) {
+	return withSpan("inbox.deliver.backlog", {
+		"inbox.id": inboxId,
+		"inbox.backlog.limit": limit
+	}, () => pollInboxInner(db, inboxId, limit));
+}
+/**
 * Per claimed trigger: SELECT silent (notify=false) pending rows in the same
 * chat that occurred between the previous trigger in this batch (or beginning
 * of time) and this trigger, capped by `PRECEDING_CONTEXT_MAX_ENTRIES` and
@@ -12293,6 +13604,26 @@ async function ackEntry$2(db, entryId, inboxId) {
 		return entry;
 	});
 }
+/**
+* Ack a delivered entry from the WS data plane, scoped to the inboxes the
+* connected socket has bound. Returns the acked row on success, `null` if no
+* row matches — a benign outcome the caller should ignore (the entry may
+* have already been acked, timed out, or never belonged to this socket).
+*
+* Distinct from {@link ackEntry} so the WS path can ack without trusting an
+* `inboxId` from the wire — only entries whose `inboxId` is in `inboxIds`
+* are eligible. Empty `inboxIds` short-circuits to `null`.
+*/
+async function ackEntryByIdForBoundAgents(db, entryId, inboxIds) {
+	if (inboxIds.length === 0) return null;
+	return withSpan("inbox.ack.ws", { [FIRST_TREE_HUB_ATTR.INBOX_ENTRY_ID]: String(entryId) }, async () => {
+		const [entry] = await db.update(inboxEntries).set({
+			status: "acked",
+			ackedAt: /* @__PURE__ */ new Date()
+		}).where(and(eq(inboxEntries.id, entryId), inArray(inboxEntries.inboxId, inboxIds), eq(inboxEntries.status, "delivered"))).returning();
+		return entry ?? null;
+	});
+}
 async function renewEntry(db, entryId, inboxId) {
 	const [entry] = await db.update(inboxEntries).set({ deliveredAt: /* @__PURE__ */ new Date() }).where(and(eq(inboxEntries.id, entryId), eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.status, "delivered"))).returning();
 	if (!entry) throw new NotFoundError("Inbox entry not found or not in delivered status");
@@ -12541,6 +13872,27 @@ async function agentTaskRoutes(app) {
 		return getTaskHealth(app.db, request.params.taskId, identity.organizationId);
 	});
 }
+/**
+* Default per-agent in-flight cap when `server.inbox.maxInFlightPerAgent` is
+* unset. Mirrors the schema default so a hub running without an explicit
+* `inbox` block still gets reasonable backpressure once `wsDataPlane` is
+* flipped on. See proposal hub-inbox-ws-data-plane §3.5.
+*/
+const DEFAULT_INBOX_MAX_IN_FLIGHT_PER_AGENT = 32;
+/**
+* Hard cap on entries scanned in a single backlog drain so a recovering
+* client doesn't trigger an arbitrarily large transaction or burst of
+* frames. Anything beyond this stays `pending` and gets picked up by
+* subsequent post-ack drains. Same constant covers both the agent:bound
+* recovery path and the post-ack top-up.
+*
+* Lower than proposal §3.3's 500 on purpose: the actual limit per drain is
+* `min(remainingInFlightBudget, INBOX_BACKLOG_BATCH_LIMIT)`, so with a
+* default cap of 32 the drain SQL never asks for more than ~32 anyway.
+* Subsequent NOTIFYs and post-ack top-ups continue draining without a
+* single-transaction megabatch.
+*/
+const INBOX_BACKLOG_BATCH_LIMIT = 50;
 const wsMessageSchema = z.object({
 	type: z.string(),
 	agentId: z.string().optional(),
@@ -12585,6 +13937,7 @@ function sendRejected(socket, ref, reason) {
 function clientWsRoutes(notifier, instanceId) {
 	return async (app) => {
 		const jwtSecretBytes = new TextEncoder().encode(app.config.secrets.jwtSecret);
+		const inboxMaxInFlightPerAgent = app.config.inbox?.maxInFlightPerAgent ?? DEFAULT_INBOX_MAX_IN_FLIGHT_PER_AGENT;
 		app.get("/client", {
 			websocket: true,
 			config: { otel: false }
@@ -12594,6 +13947,157 @@ function clientWsRoutes(notifier, instanceId) {
 			let clientId = null;
 			let authExpiryTimer = null;
 			const boundAgents = /* @__PURE__ */ new Map();
+			/**
+			* Whether the connected client opted into the WS inbox data plane via
+			* `client:register.wireCapabilities.wsInboxDeliver`. Set per-socket
+			* because client SDKs are upgraded independently — an old client
+			* connecting to a new server must keep receiving the legacy
+			* `new_message` doorbell + HTTP poll path (proposal §3.6).
+			*/
+			let clientWantsWsInboxDeliver = false;
+			/**
+			* Per-agent in-flight `inbox:deliver` counter for backpressure. Lives on
+			* the socket — when the WS closes it goes with it; that's intentional,
+			* because re-counting on a fresh connection would bias the cap against
+			* a healthy reconnect (proposal §3.5).
+			*/
+			const inboxInFlight = /* @__PURE__ */ new Map();
+			function pushUseWsDataPlane() {
+				return clientWantsWsInboxDeliver;
+			}
+			/**
+			* Returns `false` when the socket has already moved out of `OPEN` —
+			* the only failure mode the caller can observe synchronously.
+			*
+			* Note: `ws.send` is fire-and-forget; a buffered frame that fails
+			* to actually flush (TCP slow-close, internal queue full) does NOT
+			* surface here. That class of loss is recovered by the 300s timeout
+			* reaper rolling the entry back to `pending` (§3.7). If you ever
+			* need flush-level confirmation, switch to the `ws.send(frame, cb)`
+			* callback form (see `notifier.ts pushFrameToInbox`).
+			*/
+			function sendInboxDeliverFrame(entry) {
+				if (socket.readyState !== socket.OPEN) return false;
+				const frame = {
+					type: "inbox:deliver",
+					entryId: entry.id,
+					inboxId: entry.inboxId,
+					chatId: entry.chatId,
+					message: entry.message
+				};
+				const validated = inboxDeliverFrameSchema$1.safeParse(frame);
+				if (!validated.success) app.log.error({
+					entryId: entry.id,
+					inboxId: entry.inboxId,
+					issues: validated.error.issues.map((i) => ({
+						path: i.path.join("."),
+						code: i.code,
+						message: i.message
+					}))
+				}, "inbox:deliver frame failed self-validation — wire shape drift");
+				socket.send(JSON.stringify(frame));
+				return true;
+			}
+			/**
+			* Build the per-socket push handler bound to a specific agent. Closes
+			* over `agentId`, `inboxId`, the socket, and the in-flight counter.
+			*
+			* Backpressure: when the agent is at-cap we drop the NOTIFY (entry
+			* stays `pending` server-side) and a debug log records the drop so
+			* staging can correlate "messages slow" reports against cap hits.
+			* The dropped row is replayed by `drainBacklogForAgent` once an ack
+			* frees a slot, or by the next NOTIFY when we're back below cap (§3.5).
+			*
+			* Multi-row claims: a single `(inboxId, messageId)` pair can map to
+			* more than one `inbox_entries` row (replyTo cross-chat case writes
+			* a second row with a different chatId). We push every row claimed
+			* by this NOTIFY in one go — see `claimAndBuildForPush`.
+			*
+			* The cap is intentionally **soft**: claim happens after the gate
+			* check, so an N>1 claim can nudge in-flight slightly past
+			* `inboxMaxInFlightPerAgent`. N is bounded by the
+			* `(inbox_id, message_id, chat_id)` unique constraint (≤2 today),
+			* so worst-case overshoot is small and the memory headroom in §3.5's
+			* 64MB estimate covers it.
+			*/
+			function makeInboxPushHandler(agentId, inboxId) {
+				return async (messageId) => {
+					const current = inboxInFlight.get(agentId) ?? 0;
+					if (current >= inboxMaxInFlightPerAgent) {
+						app.log.debug({
+							agentId,
+							inboxId,
+							messageId,
+							inFlightCount: current,
+							cap: inboxMaxInFlightPerAgent
+						}, "inbox push: at cap, dropping NOTIFY (will replay via post-ack drain)");
+						return;
+					}
+					let entries;
+					try {
+						entries = await claimAndBuildForPush(app.db, inboxId, messageId);
+					} catch (err) {
+						app.log.error({
+							err,
+							inboxId,
+							messageId,
+							agentId
+						}, "claimAndBuildForPush failed");
+						return;
+					}
+					if (entries.length === 0) return;
+					for (const entry of entries) {
+						inboxInFlight.set(agentId, (inboxInFlight.get(agentId) ?? 0) + 1);
+						if (!sendInboxDeliverFrame(entry)) {
+							inboxInFlight.set(agentId, Math.max(0, (inboxInFlight.get(agentId) ?? 1) - 1));
+							return;
+						}
+					}
+				};
+			}
+			/**
+			* Drain up to `INBOX_BACKLOG_BATCH_LIMIT` pending entries for an agent
+			* over the current WS, capped by the remaining in-flight budget so a
+			* full drain stays within the per-agent backpressure cap (§3.3, §3.5).
+			*
+			* Used in two places:
+			*   1. Right after `agent:bound` — covers reconnects where NOTIFYs
+			*      were dropped while the socket was offline.
+			*   2. Right after an `inbox:ack` — top up the in-flight slot just
+			*      freed, in case the previous NOTIFY was dropped at-cap.
+			*
+			* The cap is **soft**: this function reads `slotsFree` once before the
+			* `claimBacklogForPush` round-trip, and a NOTIFY-driven push handler
+			* may increment the counter concurrently. In the worst case in-flight
+			* temporarily exceeds the cap by the number of concurrent pushes. With
+			* the default cap of 32 and N ≤ 2 per push handler invocation, the
+			* memory headroom in §3.5's 64MB estimate covers this.
+			*/
+			async function drainBacklogForAgent(agentId, inboxId) {
+				if (socket.readyState !== socket.OPEN) return;
+				const slotsFree = inboxMaxInFlightPerAgent - (inboxInFlight.get(agentId) ?? 0);
+				if (slotsFree <= 0) return;
+				const limit = Math.min(slotsFree, INBOX_BACKLOG_BATCH_LIMIT);
+				let entries;
+				try {
+					entries = await claimBacklogForPush(app.db, inboxId, limit);
+				} catch (err) {
+					app.log.error({
+						err,
+						agentId,
+						inboxId,
+						limit
+					}, "claimBacklogForPush failed");
+					return;
+				}
+				for (const entry of entries) {
+					inboxInFlight.set(agentId, (inboxInFlight.get(agentId) ?? 0) + 1);
+					if (!sendInboxDeliverFrame(entry)) {
+						inboxInFlight.set(agentId, Math.max(0, (inboxInFlight.get(agentId) ?? 1) - 1));
+						return;
+					}
+				}
+			}
 			const sessionOpQueues = /* @__PURE__ */ new Map();
 			function chainSessionOp(agentId, chatId, op) {
 				const key = `${agentId}:${chatId}`;
@@ -12698,7 +14202,8 @@ function clientWsRoutes(notifier, instanceId) {
 						socket.send(JSON.stringify({
 							type: "server:welcome",
 							serverCommandVersion: app.commandVersion,
-							serverTimeMs: Date.now()
+							serverTimeMs: Date.now(),
+							capabilities: { wsInboxDeliver: true }
 						}));
 					} catch (err) {
 						const message = err instanceof Error ? err.message : "auth failure";
@@ -12715,6 +14220,7 @@ function clientWsRoutes(notifier, instanceId) {
 					try {
 						if (type === "client:register") {
 							const data = clientRegisterSchema.parse(msg);
+							clientWantsWsInboxDeliver = data.wireCapabilities?.wsInboxDeliver === true;
 							try {
 								await registerClient(app.db, {
 									clientId: data.clientId,
@@ -12751,7 +14257,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({
@@ -12787,6 +14294,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);
@@ -12821,6 +14329,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,
@@ -12832,7 +14344,9 @@ function clientWsRoutes(notifier, instanceId) {
 								agentId: agent.id,
 								inboxId: agent.inboxId
 							});
-							notifier.subscribe(agent.inboxId, socket);
+							const wsPushActive = pushUseWsDataPlane();
+							if (wsPushActive) notifier.subscribe(agent.inboxId, socket, makeInboxPushHandler(agent.id, agent.inboxId));
+							else notifier.subscribe(agent.inboxId, socket);
 							socket.send(JSON.stringify({
 								type: "agent:bound",
 								ref,
@@ -12840,6 +14354,12 @@ function clientWsRoutes(notifier, instanceId) {
 								displayName: agent.displayName,
 								agentType: agent.type
 							}));
+							if (wsPushActive) drainBacklogForAgent(agent.id, agent.inboxId).catch((err) => {
+								app.log.error({
+									err,
+									agentId: agent.id
+								}, "post-bind backlog drain crashed");
+							});
 						} else if (type === "agent:unbind") {
 							const agentId = parsed.data.agentId;
 							if (!agentId || !boundAgents.has(agentId)) {
@@ -12854,6 +14374,7 @@ function clientWsRoutes(notifier, instanceId) {
 							await unbindAgent(app.db, agentId);
 							unbindAgentFromClient(agentId);
 							boundAgents.delete(agentId);
+							inboxInFlight.delete(agentId);
 							socket.send(JSON.stringify({
 								type: "agent:unbound",
 								agentId
@@ -12955,6 +14476,35 @@ function clientWsRoutes(notifier, instanceId) {
 							}
 							const payload = sessionCompletionMessageSchema.parse(msg);
 							if (shouldNotify(agentId, `session_completed:${payload.chatId}`)) notifyAgentEvent(app.db, agentId, "session_completed", "low", payload.chatId).catch(() => {});
+						} else if (type === "inbox:ack") {
+							const payloadResult = inboxAckFrameSchema.safeParse(msg);
+							if (!payloadResult.success) {
+								socket.send(JSON.stringify({
+									type: "error",
+									message: "Malformed inbox:ack frame"
+								}));
+								return;
+							}
+							const { entryId } = payloadResult.data;
+							try {
+								const ackedEntry = await ackEntryByIdForBoundAgents(app.db, entryId, [...boundAgents.values()].map((a) => a.inboxId));
+								if (!ackedEntry) return;
+								const owner = [...boundAgents.values()].find((a) => a.inboxId === ackedEntry.inboxId);
+								if (owner) {
+									inboxInFlight.set(owner.agentId, Math.max(0, (inboxInFlight.get(owner.agentId) ?? 1) - 1));
+									drainBacklogForAgent(owner.agentId, owner.inboxId).catch((err) => {
+										app.log.error({
+											err,
+											agentId: owner.agentId
+										}, "post-ack backlog drain crashed");
+									});
+								}
+							} catch (err) {
+								app.log.error({
+									err,
+									entryId
+								}, "inbox:ack handling failed");
+							}
 						} else if (type === "heartbeat") {
 							if (clientId) {
 								await heartbeatClient(app.db, clientId);
@@ -13169,7 +14719,8 @@ const authIdentities = pgTable("auth_identities", {
 }, (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)
+	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 —
@@ -13342,19 +14893,20 @@ 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:
+* Create a fresh default team org for a brand-new user, plus the matching
+* admin membership + 1:1 human agent. Slug strategy:
 *
-*   - First try: `${login}-personal`
+*   - First try: `${login}` (lowercased, sanitized)
 *   - 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降级").
+* Display name is the user's GitHub real name (or login as fallback). No
+* "Personal Team" suffix — the user might invite teammates later, and we
+* don't want a label that reads like a private sandbox to be the team name
+* other members see. Users rename freely via Settings.
 */
 async function createPersonalTeam(db, input) {
-	const baseSlug = sanitizeOrgSlug(`${input.loginSeed}-personal`);
-	const displayName = `${input.userDisplayName}'s Personal Team`;
+	const baseSlug = sanitizeOrgSlug(input.loginSeed);
+	const displayName = input.userDisplayName;
 	const orgId = uuidv7();
 	return {
 		organizationId: orgId,
@@ -13640,9 +15192,7 @@ async function githubOauthRoutes(app) {
 		return completeOauthFlow(app, request, reply, profile, next);
 	});
 	app.get("/dev-callback", async (request, reply) => {
-		const isProd = process.env.NODE_ENV === "production";
-		const devEnabled = oauthCfg?.devCallbackEnabled === true;
-		if (isProd || !devEnabled) return reply.status(404).send({ error: "Not found" });
+		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, {
@@ -14046,7 +15596,7 @@ async function inferWizardStep(app, m) {
 * landing page.
 */
 async function publicInvitePreviewRoute(app) {
-	const { previewInvitation } = await import("./invitation-BTlGMy0o-dIoR8JRj.mjs");
+	const { previewInvitation } = await import("./invitation-D3feYxet-366MNOor.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);
@@ -14076,7 +15626,7 @@ async function adminInvitationRoutes(app) {
 		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-dIoR8JRj.mjs");
+		const { rotateInvitation } = await import("./invitation-D3feYxet-366MNOor.mjs");
 		const inv = await rotateInvitation(app.db, m.organizationId, m.userId);
 		return {
 			id: inv.id,
@@ -15443,6 +16993,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,
@@ -15468,13 +17019,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,
@@ -15581,7 +17145,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: {
@@ -16672,4 +18241,4 @@ function registerSaaSConnectCommand(program) {
 	});
 }
 //#endregion
-export { FirstTreeHubSDK as $, checkWebSocket as A, ClientRuntime as B, checkClientConfig as C, checkServerConfig as D, checkNodeVersion as E, resolveCliInvocation as F, resolveReplyToFromEnv as G, rotateClientIdWithBackup as H, uninstallClientService as I, blank as J, fail as K, ensurePostgres as L, getClientServiceStatus as M, installClientService as N, checkServerHealth as O, isServiceSupported as P, ClientOrgMismatchError as Q, isDockerAvailable as R, checkBackgroundService as S, checkDocker as T, createOwner as U, handleClientOrgMismatch as V, hasUser as W, setJsonMode as X, print as Y, status as Z, runHomeMigration as _, declineUpdate as a, runMigrations as b, COMMAND_VERSION as c, promptMissingFields as d, SdkError as et, formatCheckReport as f, saveOnboardState as g, onboardCreate as h, createExecuteUpdate as i, configureClientLoggerForService as it, printResults as j, checkServerReachable as k, isInteractive as l, onboardCheck as m, deriveHubUrlFromToken as n, cleanWorkspaces as nt, promptUpdate as o, loadOnboardState as p, success as q, registerSaaSConnectCommand as r, applyClientLoggerConfig as rt, startServer as s, HubUrlDerivationError as t, SessionRegistry as tt, promptAddAgent as u, createApiNameResolver as v, checkDatabase as w, checkAgentConfigs as x, migrateLocalAgentDirs as y, stopPostgres as z };
+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 };