@deadragdoll/tellymcp 0.0.9 → 0.0.11

package/dist/services/features/telegram-mcp/gateway.service.js

@@ -8,6 +8,7 @@ const node_crypto_1 = require("node:crypto");
 const node_path_1 = __importDefault(require("node:path"));
 const db_1 = require("../../../lib/mixins/db");
 const gatewayReplyResolution_1 = require("./src/features/distributed-gateway/model/gatewayReplyResolution");
+const gatewayScope_1 = require("./src/shared/lib/gatewayScope");
 const ensuredb_service_1 = require("./ensuredb.service");
 exports.TELEGRAM_MCP_GATEWAY_SERVICE_NAME = "telegramMcp.gateway";
 const MCP_SCHEMA = process.env.DB_SCHEME || "mcp";
@@ -63,12 +64,124 @@ const TelegramMcpGatewayService = {
             }
             return text;
         },
+        async resolveOwnerUserUuidFilter(input) {
+            const explicitOwnerUserUuid = this.normalizeOptionalText?.(input.owner_user_uuid);
+            if (explicitOwnerUserUuid) {
+                return explicitOwnerUserUuid;
+            }
+            const telegramUserId = this.normalizeOptionalText?.(input.telegram_user_id);
+            if (!telegramUserId) {
+                return null;
+            }
+            const user = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_users")
+                .where({ telegram_user_id: telegramUserId })
+                .first("gateway_user_uuid");
+            return user?.gateway_user_uuid
+                ? String(user.gateway_user_uuid)
+                : "__missing_gateway_user__";
+        },
+        async upsertGatewayUserRecord(input) {
+            const telegramUserId = this.requireText?.(input.telegram_user_id, "telegram_user_id");
+            const telegramChatId = this.normalizeOptionalText?.(input.telegram_chat_id);
+            const telegramUsername = this.normalizeOptionalText?.(input.telegram_username);
+            const telegramDisplayName = this.normalizeOptionalText?.(input.telegram_display_name);
+            const now = new Date().toISOString();
+            const existing = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_users")
+                .where({ telegram_user_id: telegramUserId })
+                .first();
+            if (existing) {
+                await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_users")
+                    .where({ gateway_user_uuid: existing.gateway_user_uuid })
+                    .update({
+                    ...(telegramChatId ? { telegram_chat_id: telegramChatId } : {}),
+                    ...(telegramUsername ? { telegram_username: telegramUsername } : {}),
+                    ...(telegramDisplayName ? { telegram_display_name: telegramDisplayName } : {}),
+                    updated_at: now,
+                    last_auth_at: now,
+                });
+                return {
+                    gateway_user_uuid: String(existing.gateway_user_uuid),
+                    created: false,
+                    updated_at: now,
+                };
+            }
+            const gatewayUserUuid = (0, node_crypto_1.randomUUID)();
+            await this.db.withSchema(MCP_SCHEMA).table("gateway_users").insert({
+                gateway_user_uuid: gatewayUserUuid,
+                telegram_user_id: telegramUserId,
+                ...(telegramChatId ? { telegram_chat_id: telegramChatId } : {}),
+                ...(telegramUsername ? { telegram_username: telegramUsername } : {}),
+                ...(telegramDisplayName ? { telegram_display_name: telegramDisplayName } : {}),
+                created_at: now,
+                updated_at: now,
+                last_auth_at: now,
+            });
+            return {
+                gateway_user_uuid: gatewayUserUuid,
+                created: true,
+                updated_at: now,
+            };
+        },
+        async resolveGatewayUserRouteRecord(input) {
+            const explicitGatewayUserUuid = this.normalizeOptionalText?.(input.gateway_user_uuid);
+            const clientUuid = this.normalizeOptionalText?.(input.client_uuid);
+            let gatewayUserUuid = explicitGatewayUserUuid;
+            if (!gatewayUserUuid && clientUuid) {
+                const client = await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_clients")
+                    .where({ client_uuid: clientUuid })
+                    .first("owner_user_uuid");
+                gatewayUserUuid =
+                    client?.owner_user_uuid ? String(client.owner_user_uuid) : null;
+            }
+            if (!gatewayUserUuid) {
+                return null;
+            }
+            const user = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_users")
+                .where({ gateway_user_uuid: gatewayUserUuid })
+                .first("gateway_user_uuid", "telegram_user_id", "telegram_chat_id", "telegram_username", "telegram_display_name");
+            if (!user?.gateway_user_uuid || !user.telegram_user_id) {
+                return null;
+            }
+            return {
+                gateway_user_uuid: String(user.gateway_user_uuid),
+                telegram_user_id: Number(user.telegram_user_id),
+                telegram_chat_id: typeof user.telegram_chat_id === "number"
+                    ? user.telegram_chat_id
+                    : user.telegram_chat_id
+                        ? Number(user.telegram_chat_id)
+                        : null,
+                ...(user.telegram_username
+                    ? { telegram_username: String(user.telegram_username) }
+                    : {}),
+                ...(user.telegram_display_name
+                    ? { telegram_display_name: String(user.telegram_display_name) }
+                    : {}),
+            };
+        },
         async registerClientRecord(input) {
             const clientUuid = this.normalizeOptionalText?.(input.client_uuid) || (0, node_crypto_1.randomUUID)();
             const now = new Date().toISOString();
+            const scopeKey = (0, gatewayScope_1.resolveGatewayScopeKey)(input);
             const clientLabel = this.normalizeOptionalText?.(input.client_label);
             const botUsername = this.normalizeOptionalText?.(input.bot_username);
             const tokenFingerprint = this.normalizeOptionalText?.(input.bot_token_fingerprint);
+            const ownerUserUuid = this.normalizeOptionalText?.(input.owner_user_uuid) ||
+                (input.meta &&
+                    typeof input.meta === "object" &&
+                    !Array.isArray(input.meta) &&
+                    typeof input.meta.gateway_user_uuid === "string"
+                    ? this.normalizeOptionalText?.(input.meta.gateway_user_uuid)
+                    : null);
             const meta = input.meta && typeof input.meta === "object" && !Array.isArray(input.meta)
                 ? input.meta
                 : {};
@@ -78,11 +191,17 @@ const TelegramMcpGatewayService = {
                 .where({ client_uuid: clientUuid })
                 .first();
             if (existing) {
+                const existingScopeKey = this.normalizeOptionalText?.(existing.scope_key);
+                if (existingScopeKey && scopeKey && existingScopeKey !== scopeKey) {
+                    throw new Error("Client is already bound to a different gateway scope.");
+                }
                 await this.db
                     .withSchema(MCP_SCHEMA)
                     .table("gateway_clients")
                     .where({ client_uuid: clientUuid })
                     .update({
+                    ...(ownerUserUuid ? { owner_user_uuid: ownerUserUuid } : {}),
+                    ...(scopeKey ? { scope_key: scopeKey } : {}),
                     ...(clientLabel ? { client_label: clientLabel } : {}),
                     ...(botUsername ? { bot_username: botUsername } : {}),
                     ...(tokenFingerprint ? { bot_token_fingerprint: tokenFingerprint } : {}),
@@ -98,6 +217,8 @@ const TelegramMcpGatewayService = {
             }
             await this.db.withSchema(MCP_SCHEMA).table("gateway_clients").insert({
                 client_uuid: clientUuid,
+                ...(ownerUserUuid ? { owner_user_uuid: ownerUserUuid } : {}),
+                ...(scopeKey ? { scope_key: scopeKey } : {}),
                 ...(clientLabel ? { client_label: clientLabel } : {}),
                 ...(botUsername ? { bot_username: botUsername } : {}),
                 ...(tokenFingerprint ? { bot_token_fingerprint: tokenFingerprint } : {}),
@@ -112,9 +233,334 @@ const TelegramMcpGatewayService = {
                 updated_at: now,
             };
         },
+        async clearLiveConsolesRecord(input = {}) {
+            const connectionId = this.normalizeOptionalText?.(input.connection_id);
+            const clientUuid = this.normalizeOptionalText?.(input.client_uuid);
+            const query = this.db.withSchema(MCP_SCHEMA).table("gateway_live_consoles");
+            if (connectionId) {
+                query.where({ connection_id: connectionId });
+            }
+            if (clientUuid) {
+                query.where({ client_uuid: clientUuid });
+            }
+            const deleted = await query.del();
+            return { deleted };
+        },
+        async removeLiveConsolesRecord(input) {
+            const clientUuid = this.normalizeOptionalText?.(input.client_uuid);
+            const connectionId = this.normalizeOptionalText?.(input.connection_id);
+            if (!clientUuid && !connectionId) {
+                throw new Error("client_uuid or connection_id is required");
+            }
+            const query = this.db.withSchema(MCP_SCHEMA).table("gateway_live_consoles");
+            if (clientUuid) {
+                query.where({ client_uuid: clientUuid });
+            }
+            if (connectionId) {
+                query.where({ connection_id: connectionId });
+            }
+            const deleted = await query.del();
+            return { deleted };
+        },
+        async pruneGatewayStateRecord() {
+            const deleted = {};
+            const truncate = async (tableName) => {
+                deleted[tableName] = await this.db.withSchema(MCP_SCHEMA).table(tableName).del();
+            };
+            await truncate("gateway_live_consoles");
+            await truncate("gateway_session_links");
+            await truncate("gateway_deliveries");
+            await truncate("gateway_message_artifacts");
+            await truncate("gateway_messages");
+            await truncate("gateway_project_consoles");
+            await truncate("gateway_sessions");
+            await truncate("gateway_project_members");
+            await truncate("gateway_projects");
+            await truncate("gateway_clients");
+            await truncate("gateway_users");
+            return { deleted };
+        },
+        async syncLiveConsolesRecord(input) {
+            const clientUuid = this.requireText?.(input.client_uuid, "client_uuid");
+            const connectionId = this.requireText?.(input.connection_id, "connection_id");
+            const now = new Date().toISOString();
+            const gatewayUserUuid = this.normalizeOptionalText?.(input.gateway_user_uuid);
+            const clientLabel = this.normalizeOptionalText?.(input.client_label);
+            const systemUsername = this.normalizeOptionalText?.(input.system_username);
+            const namespace = this.normalizeOptionalText?.(input.namespace);
+            const nodeId = this.normalizeOptionalText?.(input.node_id);
+            const packageVersion = this.normalizeOptionalText?.(input.package_version);
+            const protocolVersion = this.normalizeOptionalText?.(input.protocol_version);
+            const sessionTools = Array.isArray(input.session_tools)
+                ? input.session_tools.flatMap((item) => {
+                    if (!item || typeof item !== "object") {
+                        return [];
+                    }
+                    const record = item;
+                    const localSessionId = this.normalizeOptionalText?.(record.local_session_id);
+                    if (!localSessionId) {
+                        return [];
+                    }
+                    return [
+                        {
+                            local_session_id: localSessionId,
+                            session_label: this.normalizeOptionalText?.(record.session_label) ?? null,
+                            tools_hash: this.normalizeOptionalText?.(record.tools_hash) ?? null,
+                            cwd: this.normalizeOptionalText?.(record.cwd) ?? null,
+                        },
+                    ];
+                })
+                : [];
+            await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_clients")
+                .where({ client_uuid: clientUuid })
+                .update({
+                ...(gatewayUserUuid ? { owner_user_uuid: gatewayUserUuid } : {}),
+                ...(clientLabel ? { client_label: clientLabel } : {}),
+                updated_at: now,
+                last_seen_at: now,
+            });
+            await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_live_consoles")
+                .where({ connection_id: connectionId })
+                .del();
+            for (const sessionTool of sessionTools) {
+                const existing = await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_live_consoles")
+                    .where({
+                    client_uuid: clientUuid,
+                    local_session_id: sessionTool.local_session_id,
+                })
+                    .first("live_console_uuid", "connected_at");
+                const payload = {
+                    connection_id: connectionId,
+                    client_uuid: clientUuid,
+                    local_session_id: sessionTool.local_session_id,
+                    ...(sessionTool.session_label
+                        ? { session_label: sessionTool.session_label }
+                        : {}),
+                    ...(sessionTool.cwd ? { cwd: sessionTool.cwd } : {}),
+                    ...(sessionTool.tools_hash ? { tools_hash: sessionTool.tools_hash } : {}),
+                    ...(gatewayUserUuid ? { gateway_user_uuid: gatewayUserUuid } : {}),
+                    ...(clientLabel ? { client_label: clientLabel } : {}),
+                    ...(systemUsername ? { system_username: systemUsername } : {}),
+                    ...(namespace ? { namespace } : {}),
+                    ...(nodeId ? { node_id: nodeId } : {}),
+                    ...(packageVersion ? { package_version: packageVersion } : {}),
+                    ...(protocolVersion ? { protocol_version: protocolVersion } : {}),
+                    meta: this.db.raw(`?::jsonb`, [
+                        JSON.stringify({
+                            ...(sessionTool.cwd ? { cwd: sessionTool.cwd } : {}),
+                        }),
+                    ]),
+                    last_seen_at: now,
+                };
+                if (existing?.live_console_uuid) {
+                    await this.db
+                        .withSchema(MCP_SCHEMA)
+                        .table("gateway_live_consoles")
+                        .where({ live_console_uuid: existing.live_console_uuid })
+                        .update(payload);
+                    continue;
+                }
+                await this.db.withSchema(MCP_SCHEMA).table("gateway_live_consoles").insert({
+                    live_console_uuid: (0, node_crypto_1.randomUUID)(),
+                    ...payload,
+                    connected_at: now,
+                });
+            }
+            return {
+                client_uuid: clientUuid,
+                connection_id: connectionId,
+                total: sessionTools.length,
+            };
+        },
+        async listLiveClientsRecord(input = {}) {
+            const scopeKey = (0, gatewayScope_1.resolveGatewayScopeKey)(input);
+            const ownerUserUuid = await this.resolveOwnerUserUuidFilter?.(input);
+            const rows = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_live_consoles as lc")
+                .join("gateway_clients as c", "c.client_uuid", "lc.client_uuid")
+                .modify((query) => {
+                if (scopeKey) {
+                    query.where("c.scope_key", scopeKey);
+                }
+                if (ownerUserUuid) {
+                    query.where("c.owner_user_uuid", ownerUserUuid);
+                }
+            })
+                .select("lc.client_uuid", "lc.local_session_id", "lc.session_label", "lc.tools_hash", "lc.gateway_user_uuid", "lc.client_label", "lc.system_username", "lc.namespace", "lc.node_id", "lc.package_version", "lc.protocol_version", "lc.last_seen_at")
+                .orderBy("lc.client_uuid", "asc")
+                .orderBy("lc.local_session_id", "asc");
+            const grouped = new Map();
+            for (const row of rows) {
+                const current = grouped.get(String(row.client_uuid)) ?? {
+                    client_uuid: String(row.client_uuid),
+                    ...(row.gateway_user_uuid
+                        ? { gateway_user_uuid: String(row.gateway_user_uuid) }
+                        : {}),
+                    ...(row.client_label ? { client_label: String(row.client_label) } : {}),
+                    ...(row.system_username
+                        ? { system_username: String(row.system_username) }
+                        : {}),
+                    ...(row.namespace ? { namespace: String(row.namespace) } : {}),
+                    ...(row.node_id ? { node_id: String(row.node_id) } : {}),
+                    ...(row.package_version
+                        ? { package_version: String(row.package_version) }
+                        : {}),
+                    ...(row.protocol_version
+                        ? { protocol_version: String(row.protocol_version) }
+                        : {}),
+                    session_tools: [],
+                };
+                current.session_tools.push({
+                    local_session_id: String(row.local_session_id),
+                    ...(row.session_label ? { session_label: String(row.session_label) } : {}),
+                    ...(row.tools_hash ? { tools_hash: String(row.tools_hash) } : {}),
+                });
+                grouped.set(current.client_uuid, current);
+            }
+            return {
+                clients: Array.from(grouped.values()).sort((left, right) => left.client_uuid.localeCompare(right.client_uuid)),
+            };
+        },
+        async listLiveConsolesRecord(input = {}) {
+            const scopeKey = (0, gatewayScope_1.resolveGatewayScopeKey)(input);
+            const ownerUserUuid = await this.resolveOwnerUserUuidFilter?.(input);
+            const filterClientUuid = this.normalizeOptionalText?.(input.client_uuid);
+            const rows = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_live_consoles as lc")
+                .join("gateway_clients as c", "c.client_uuid", "lc.client_uuid")
+                .leftJoin("gateway_users as u", "u.gateway_user_uuid", "c.owner_user_uuid")
+                .leftJoin("gateway_project_consoles as pc", function joinProjectConsole() {
+                this.on("pc.client_uuid", "=", "lc.client_uuid")
+                    .andOn("pc.local_session_id", "=", "lc.local_session_id")
+                    .andOnVal("pc.status", "=", "active");
+            })
+                .leftJoin("gateway_projects as p", "p.project_uuid", "pc.project_uuid")
+                .modify((query) => {
+                if (scopeKey) {
+                    query.where("c.scope_key", scopeKey);
+                }
+                if (ownerUserUuid) {
+                    query.where("c.owner_user_uuid", ownerUserUuid);
+                }
+                if (filterClientUuid) {
+                    query.where("lc.client_uuid", filterClientUuid);
+                }
+            })
+                .select("lc.client_uuid", "lc.local_session_id", "lc.cwd", "lc.session_label", "lc.client_label", "lc.system_username", "lc.node_id", "lc.package_version", "lc.protocol_version", "c.bot_username", "pc.project_uuid", "p.name as project_name", this.db.raw("nullif(u.telegram_username, '') as telegram_username"), this.db.raw("nullif(u.telegram_display_name, '') as telegram_display_name"))
+                .orderBy("lc.client_uuid", "asc")
+                .orderBy("lc.local_session_id", "asc");
+            const merged = new Map();
+            for (const row of rows) {
+                const key = `${row.client_uuid}:${row.local_session_id}`;
+                const current = merged.get(key);
+                const projectUuids = new Set(current?.project_uuids ?? []);
+                const projectNames = new Set(current?.project_names ?? []);
+                if (row.project_uuid) {
+                    projectUuids.add(String(row.project_uuid));
+                }
+                if (row.project_name) {
+                    projectNames.add(String(row.project_name));
+                }
+                merged.set(key, {
+                    session_id: key,
+                    client_uuid: String(row.client_uuid),
+                    local_session_id: String(row.local_session_id),
+                    cwd: current?.cwd ?? (row.cwd ? String(row.cwd) : null),
+                    session_label: current?.session_label ??
+                        (row.session_label ? String(row.session_label) : null),
+                    client_label: current?.client_label ??
+                        (row.client_label ? String(row.client_label) : null),
+                    system_username: current?.system_username ??
+                        (row.system_username ? String(row.system_username) : null),
+                    telegram_username: current?.telegram_username ??
+                        (row.telegram_username ? String(row.telegram_username) : null),
+                    telegram_display_name: current?.telegram_display_name ??
+                        (row.telegram_display_name ? String(row.telegram_display_name) : null),
+                    bot_username: current?.bot_username ??
+                        (row.bot_username ? String(row.bot_username) : null),
+                    node_id: current?.node_id ?? (row.node_id ? String(row.node_id) : null),
+                    package_version: current?.package_version ??
+                        (row.package_version ? String(row.package_version) : null),
+                    protocol_version: current?.protocol_version ??
+                        (row.protocol_version ? String(row.protocol_version) : null),
+                    project_uuids: Array.from(projectUuids),
+                    project_names: Array.from(projectNames),
+                    connected: true,
+                    registered: projectUuids.size > 0,
+                });
+            }
+            return {
+                sessions: Array.from(merged.values()).sort((left, right) => left.session_id.localeCompare(right.session_id)),
+            };
+        },
+        async resolveLiveConsoleRecord(input) {
+            const sessionId = this.requireText?.(input.sessionId ?? input.session_id, "sessionId");
+            if (!sessionId) {
+                throw new Error("sessionId is required");
+            }
+            const ownerUserUuid = await this.resolveOwnerUserUuidFilter?.(input);
+            const compositeSeparatorIndex = sessionId.indexOf(":");
+            const clientUuid = compositeSeparatorIndex > 0 ? sessionId.slice(0, compositeSeparatorIndex).trim() : "";
+            const localSessionId = compositeSeparatorIndex > 0
+                ? sessionId.slice(compositeSeparatorIndex + 1).trim()
+                : sessionId;
+            if (clientUuid && localSessionId) {
+                const row = await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_live_consoles as lc")
+                    .join("gateway_clients as c", "c.client_uuid", "lc.client_uuid")
+                    .where("lc.client_uuid", clientUuid)
+                    .where("lc.local_session_id", localSessionId)
+                    .modify((query) => {
+                    if (ownerUserUuid) {
+                        query.where("c.owner_user_uuid", ownerUserUuid);
+                    }
+                })
+                    .first("lc.client_uuid", "lc.local_session_id", "lc.session_label");
+                return row
+                    ? {
+                        client_uuid: String(row.client_uuid),
+                        local_session_id: String(row.local_session_id),
+                        ...(row.session_label ? { session_label: String(row.session_label) } : {}),
+                    }
+                    : null;
+            }
+            const rows = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_live_consoles as lc")
+                .join("gateway_clients as c", "c.client_uuid", "lc.client_uuid")
+                .where("lc.local_session_id", localSessionId)
+                .modify((query) => {
+                if (ownerUserUuid) {
+                    query.where("c.owner_user_uuid", ownerUserUuid);
+                }
+            })
+                .select("lc.client_uuid", "lc.local_session_id", "lc.session_label");
+            if (rows.length === 0) {
+                return null;
+            }
+            if (rows.length > 1) {
+                throw new Error(`Console session_id '${localSessionId}' is ambiguous across live clients. Use the canonical gateway session_id format client_uuid:local_session_id.`);
+            }
+            const row = rows[0];
+            return {
+                client_uuid: String(row.client_uuid),
+                local_session_id: String(row.local_session_id),
+                ...(row.session_label ? { session_label: String(row.session_label) } : {}),
+            };
+        },
         async createProjectRecord(input) {
             const clientUuid = this.requireText?.(input.client_uuid, "client_uuid");
             const name = this.requireText?.(input.name, "name");
+            const localSessionId = this.requireText?.(input.local_session_id, "local_session_id");
             const client = await this.db
                 .withSchema(MCP_SCHEMA)
                 .table("gateway_clients")
@@ -130,31 +576,68 @@ const TelegramMcpGatewayService = {
             const projectUuid = (0, node_crypto_1.randomUUID)();
             const inviteToken = (0, node_crypto_1.randomUUID)();
             const now = new Date().toISOString();
-            await this.db.withSchema(MCP_SCHEMA).table("gateway_projects").insert({
-                project_uuid: projectUuid,
-                name,
-                invite_token: inviteToken,
-                created_by_client_uuid: clientUuid,
-                ...(ownerTelegramUserId
-                    ? { owner_telegram_user_id: ownerTelegramUserId }
-                    : {}),
-                ...(ownerTelegramUsername
-                    ? { owner_telegram_username: ownerTelegramUsername }
-                    : {}),
-                ...(ownerDisplayName ? { owner_display_name: ownerDisplayName } : {}),
-                is_active: true,
-                created_at: now,
-                updated_at: now,
+            await this.db.transaction(async (trx) => {
+                await trx.withSchema(MCP_SCHEMA).table("gateway_projects").insert({
+                    project_uuid: projectUuid,
+                    name,
+                    invite_token: inviteToken,
+                    created_by_client_uuid: clientUuid,
+                    ...(ownerTelegramUserId
+                        ? { owner_telegram_user_id: ownerTelegramUserId }
+                        : {}),
+                    ...(ownerTelegramUsername
+                        ? { owner_telegram_username: ownerTelegramUsername }
+                        : {}),
+                    ...(ownerDisplayName ? { owner_display_name: ownerDisplayName } : {}),
+                    is_active: true,
+                    created_at: now,
+                    updated_at: now,
+                });
+                await trx.withSchema(MCP_SCHEMA).table("gateway_project_members").insert({
+                    project_uuid: projectUuid,
+                    client_uuid: clientUuid,
+                    role: "owner",
+                    status: "active",
+                    ...(ownerTelegramUserId ? { telegram_user_id: ownerTelegramUserId } : {}),
+                    ...(ownerTelegramUsername ? { telegram_username: ownerTelegramUsername } : {}),
+                    ...(ownerDisplayName ? { display_name: ownerDisplayName } : {}),
+                    joined_at: now,
+                });
             });
-            await this.db.withSchema(MCP_SCHEMA).table("gateway_project_members").insert({
-                project_uuid: projectUuid,
-                client_uuid: clientUuid,
-                role: "owner",
-                status: "active",
-                ...(ownerTelegramUserId ? { telegram_user_id: ownerTelegramUserId } : {}),
-                ...(ownerTelegramUsername ? { telegram_username: ownerTelegramUsername } : {}),
-                ...(ownerDisplayName ? { display_name: ownerDisplayName } : {}),
-                joined_at: now,
+            let registration;
+            try {
+                registration = await this.registerProjectConsoleForSession?.({
+                    client_uuid: clientUuid,
+                    project_uuid: projectUuid,
+                    local_session_id: localSessionId,
+                    ...(this.normalizeOptionalText?.(input.label)
+                        ? { label: this.normalizeOptionalText?.(input.label) }
+                        : {}),
+                    ...(this.normalizeOptionalText?.(input.cwd)
+                        ? { cwd: this.normalizeOptionalText?.(input.cwd) }
+                        : {}),
+                    status: "active",
+                    ...(input.meta && typeof input.meta === "object" && !Array.isArray(input.meta)
+                        ? { meta: input.meta }
+                        : {}),
+                });
+                if (!registration?.session_uuid) {
+                    throw new Error(`Project ${projectUuid} was created, but console registration for ${clientUuid}:${localSessionId} failed.`);
+                }
+            }
+            catch (error) {
+                await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_projects")
+                    .where({ project_uuid: projectUuid })
+                    .del();
+                throw error;
+            }
+            this.logger.info("Gateway project created and console bound", {
+                projectUuid,
+                clientUuid,
+                localSessionId,
+                sessionUuid: registration.session_uuid,
             });
             return {
                 project_uuid: projectUuid,
@@ -166,6 +649,7 @@ const TelegramMcpGatewayService = {
         async joinProjectRecord(input) {
             const clientUuid = this.requireText?.(input.client_uuid, "client_uuid");
             const inviteToken = this.requireText?.(input.invite_token, "invite_token");
+            const localSessionId = this.requireText?.(input.local_session_id, "local_session_id");
             const client = await this.db
                 .withSchema(MCP_SCHEMA)
                 .table("gateway_clients")
@@ -178,14 +662,21 @@ const TelegramMcpGatewayService = {
             const memberTelegramUserId = this.normalizeOptionalText?.(clientMeta.telegram_user_id);
             const memberTelegramUsername = this.normalizeOptionalText?.(clientMeta.telegram_username);
             const memberDisplayName = this.normalizeOptionalText?.(clientMeta.telegram_display_name);
+            const memberScopeKey = this.normalizeOptionalText?.(client.scope_key);
             const project = await this.db
                 .withSchema(MCP_SCHEMA)
-                .table("gateway_projects")
-                .where({ invite_token: inviteToken, is_active: true })
+                .table("gateway_projects as p")
+                .leftJoin("gateway_clients as owner_client", "owner_client.client_uuid", "p.created_by_client_uuid")
+                .where({ "p.invite_token": inviteToken, "p.is_active": true })
+                .select("p.*", "owner_client.scope_key as owner_scope_key")
                 .first();
             if (!project) {
                 throw new Error("Project invite token is invalid or inactive");
             }
+            const ownerScopeKey = this.normalizeOptionalText?.(project.owner_scope_key);
+            if (memberScopeKey && ownerScopeKey && memberScopeKey !== ownerScopeKey) {
+                throw new Error("Project belongs to a different gateway scope.");
+            }
             const existing = await this.db
                 .withSchema(MCP_SCHEMA)
                 .table("gateway_project_members")
@@ -228,6 +719,42 @@ const TelegramMcpGatewayService = {
                         joined_at: new Date().toISOString(),
                     });
                 }
+                try {
+                    const registration = await this.registerProjectConsoleForSession?.({
+                        client_uuid: clientUuid,
+                        project_uuid: String(project.project_uuid),
+                        local_session_id: localSessionId,
+                        ...(this.normalizeOptionalText?.(input.label)
+                            ? { label: this.normalizeOptionalText?.(input.label) }
+                            : {}),
+                        ...(this.normalizeOptionalText?.(input.cwd)
+                            ? { cwd: this.normalizeOptionalText?.(input.cwd) }
+                            : {}),
+                        status: "active",
+                        ...(input.meta && typeof input.meta === "object" && !Array.isArray(input.meta)
+                            ? { meta: input.meta }
+                            : {}),
+                    });
+                    if (!registration?.session_uuid) {
+                        throw new Error(`Project ${String(project.project_uuid)} membership exists, but console registration for ${clientUuid}:${localSessionId} failed.`);
+                    }
+                }
+                catch (error) {
+                    if (existing.status !== "active") {
+                        await this.db
+                            .withSchema(MCP_SCHEMA)
+                            .table("gateway_project_members")
+                            .where({
+                            project_uuid: project.project_uuid,
+                            client_uuid: clientUuid,
+                        })
+                            .update({
+                            status: existing.status,
+                            joined_at: existing.joined_at,
+                        });
+                    }
+                    throw error;
+                }
                 return {
                     project_uuid: project.project_uuid,
                     invite_token: project.invite_token,
@@ -254,6 +781,37 @@ const TelegramMcpGatewayService = {
                 ...(memberDisplayName ? { display_name: memberDisplayName } : {}),
                 joined_at: new Date().toISOString(),
             });
+            try {
+                const registration = await this.registerProjectConsoleForSession?.({
+                    client_uuid: clientUuid,
+                    project_uuid: String(project.project_uuid),
+                    local_session_id: localSessionId,
+                    ...(this.normalizeOptionalText?.(input.label)
+                        ? { label: this.normalizeOptionalText?.(input.label) }
+                        : {}),
+                    ...(this.normalizeOptionalText?.(input.cwd)
+                        ? { cwd: this.normalizeOptionalText?.(input.cwd) }
+                        : {}),
+                    status: "active",
+                    ...(input.meta && typeof input.meta === "object" && !Array.isArray(input.meta)
+                        ? { meta: input.meta }
+                        : {}),
+                });
+                if (!registration?.session_uuid) {
+                    throw new Error(`Project ${String(project.project_uuid)} was joined, but console registration for ${clientUuid}:${localSessionId} failed.`);
+                }
+            }
+            catch (error) {
+                await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_project_members")
+                    .where({
+                    project_uuid: project.project_uuid,
+                    client_uuid: clientUuid,
+                })
+                    .del();
+                throw error;
+            }
             const notifyRows = await this.db
                 .withSchema(MCP_SCHEMA)
                 .table("gateway_project_members")
@@ -302,38 +860,30 @@ const TelegramMcpGatewayService = {
                 .withSchema(MCP_SCHEMA)
                 .table("gateway_sessions")
                 .where({
-                project_uuid: projectUuid,
                 client_uuid: clientUuid,
                 local_session_id: localSessionId,
             })
                 .first();
-            const payload = {
+            const existingProjectConsole = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_project_consoles")
+                .where({
                 project_uuid: projectUuid,
                 client_uuid: clientUuid,
                 local_session_id: localSessionId,
+            })
+                .first("project_console_uuid");
+            const payload = {
+                client_uuid: clientUuid,
+                local_session_id: localSessionId,
                 ...(this.normalizeOptionalText?.(input.label)
                     ? { label: this.normalizeOptionalText?.(input.label) }
                     : {}),
                 ...(this.normalizeOptionalText?.(input.cwd)
                     ? { cwd: this.normalizeOptionalText?.(input.cwd) }
                     : {}),
-                ...(this.normalizeOptionalText?.(input.tmux_session_name)
-                    ? { tmux_session_name: this.normalizeOptionalText?.(input.tmux_session_name) }
-                    : {}),
-                ...(this.normalizeOptionalText?.(input.tmux_window_name)
-                    ? { tmux_window_name: this.normalizeOptionalText?.(input.tmux_window_name) }
-                    : {}),
-                ...(Number.isInteger(input.tmux_window_index)
-                    ? { tmux_window_index: input.tmux_window_index }
-                    : {}),
-                ...(this.normalizeOptionalText?.(input.tmux_pane_id)
-                    ? { tmux_pane_id: this.normalizeOptionalText?.(input.tmux_pane_id) }
-                    : {}),
-                ...(Number.isInteger(input.tmux_pane_index)
-                    ? { tmux_pane_index: input.tmux_pane_index }
-                    : {}),
-                ...(this.normalizeOptionalText?.(input.tmux_target)
-                    ? { tmux_target: this.normalizeOptionalText?.(input.tmux_target) }
+                ...(this.normalizeOptionalText?.(input.terminal_target)
+                    ? { terminal_target: this.normalizeOptionalText?.(input.terminal_target) }
                     : {}),
                 status: this.normalizeOptionalText?.(input.status) || "active",
                 meta: this.db.raw(`?::jsonb`, [
@@ -349,6 +899,36 @@ const TelegramMcpGatewayService = {
                     .table("gateway_sessions")
                     .where({ session_uuid: existing.session_uuid })
                     .update(payload);
+                if (existingProjectConsole?.project_console_uuid) {
+                    await this.db
+                        .withSchema(MCP_SCHEMA)
+                        .table("gateway_project_consoles")
+                        .where({ project_console_uuid: existingProjectConsole.project_console_uuid })
+                        .update({
+                        gateway_session_uuid: existing.session_uuid,
+                        status: "active",
+                        updated_at: now,
+                    });
+                }
+                else {
+                    await this.db.withSchema(MCP_SCHEMA).table("gateway_project_consoles").insert({
+                        project_console_uuid: (0, node_crypto_1.randomUUID)(),
+                        project_uuid: projectUuid,
+                        client_uuid: clientUuid,
+                        local_session_id: localSessionId,
+                        gateway_session_uuid: existing.session_uuid,
+                        status: "active",
+                        joined_at: now,
+                        updated_at: now,
+                    });
+                }
+                this.logger.info("Gateway project console session registered", {
+                    projectUuid,
+                    clientUuid,
+                    localSessionId,
+                    sessionUuid: existing.session_uuid,
+                    created: false,
+                });
                 return {
                     session_uuid: existing.session_uuid,
                     created: false,
@@ -361,37 +941,118 @@ const TelegramMcpGatewayService = {
                 ...payload,
                 created_at: now,
             });
+            if (existingProjectConsole?.project_console_uuid) {
+                await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_project_consoles")
+                    .where({ project_console_uuid: existingProjectConsole.project_console_uuid })
+                    .update({
+                    gateway_session_uuid: sessionUuid,
+                    status: "active",
+                    updated_at: now,
+                });
+            }
+            else {
+                await this.db.withSchema(MCP_SCHEMA).table("gateway_project_consoles").insert({
+                    project_console_uuid: (0, node_crypto_1.randomUUID)(),
+                    project_uuid: projectUuid,
+                    client_uuid: clientUuid,
+                    local_session_id: localSessionId,
+                    gateway_session_uuid: sessionUuid,
+                    status: "active",
+                    joined_at: now,
+                    updated_at: now,
+                });
+            }
+            this.logger.info("Gateway project console session registered", {
+                projectUuid,
+                clientUuid,
+                localSessionId,
+                sessionUuid,
+                created: true,
+            });
             return {
                 session_uuid: sessionUuid,
                 created: true,
                 updated_at: now,
             };
         },
-        async unregisterSessionRecord(input) {
-            const clientUuid = this.requireText?.(input.client_uuid, "client_uuid");
-            const localSessionId = this.requireText?.(input.local_session_id, "local_session_id");
-            const deleted = await this.db
+        async registerProjectConsoleForSession(input) {
+            const result = await this.registerSessionRecord?.(input);
+            if (!result?.session_uuid) {
+                throw new Error("Console registration returned no session_uuid.");
+            }
+            return result;
+        },
+        async listClientsRecord(input = {}) {
+            const scopeKey = (0, gatewayScope_1.resolveGatewayScopeKey)(input);
+            const ownerUserUuid = await this.resolveOwnerUserUuidFilter?.(input);
+            const rows = await this.db
                 .withSchema(MCP_SCHEMA)
-                .table("gateway_sessions")
-                .where({
-                client_uuid: clientUuid,
-                local_session_id: localSessionId,
+                .table("gateway_clients as c")
+                .leftJoin("gateway_live_consoles as lc", "c.client_uuid", "lc.client_uuid")
+                .modify((query) => {
+                if (scopeKey) {
+                    query.where("c.scope_key", scopeKey);
+                }
+                if (ownerUserUuid) {
+                    query.where("c.owner_user_uuid", ownerUserUuid);
+                }
             })
-                .del();
+                .groupBy("c.client_uuid", "c.client_label", this.db.raw("nullif(c.meta->>'namespace', '')"), this.db.raw("nullif(c.meta->>'node_id', '')"), this.db.raw("nullif(c.meta->>'system_username', '')"), this.db.raw("nullif(c.meta->>'telegram_username', '')"), this.db.raw("nullif(c.meta->>'telegram_display_name', '')"), "c.bot_username", "c.last_seen_at", "c.updated_at")
+                .select("c.client_uuid", "c.client_label", this.db.raw("nullif(c.meta->>'namespace', '') as namespace"), this.db.raw("nullif(c.meta->>'node_id', '') as node_id"), this.db.raw("nullif(c.meta->>'system_username', '') as system_username"), this.db.raw("nullif(c.meta->>'telegram_username', '') as telegram_username"), this.db.raw("nullif(c.meta->>'telegram_display_name', '') as telegram_display_name"), "c.bot_username", "c.last_seen_at", "c.updated_at", this.db.raw("count(lc.live_console_uuid) as session_count"))
+                .orderBy("c.last_seen_at", "desc")
+                .orderBy("c.client_uuid", "asc");
+            this.logger.info("Gateway clients list queried", {
+                count: rows.length,
+                clientUuids: rows
+                    .map((row) => String(row.client_uuid ?? ""))
+                    .filter(Boolean),
+                ...(scopeKey ? { scopeKey } : {}),
+            });
             return {
-                local_session_id: localSessionId,
-                deleted,
+                clients: rows.map((row) => ({
+                    client_uuid: String(row.client_uuid),
+                    client_label: row.client_label ? String(row.client_label) : null,
+                    namespace: row.namespace ? String(row.namespace) : null,
+                    node_id: row.node_id ? String(row.node_id) : null,
+                    system_username: row.system_username ? String(row.system_username) : null,
+                    telegram_username: row.telegram_username ? String(row.telegram_username) : null,
+                    telegram_display_name: row.telegram_display_name ? String(row.telegram_display_name) : null,
+                    bot_username: row.bot_username ? String(row.bot_username) : null,
+                    ...(row.last_seen_at ? { last_seen_at: String(row.last_seen_at) } : {}),
+                    ...(row.updated_at ? { updated_at: String(row.updated_at) } : {}),
+                    session_count: Number(row.session_count || 0),
+                })),
             };
         },
         async listProjectsRecord(input) {
             const clientUuid = this.requireText?.(input.client_uuid, "client_uuid");
+            const localSessionId = this.normalizeOptionalText?.(input.local_session_id);
+            const scopeKey = (0, gatewayScope_1.resolveGatewayScopeKey)(input);
             const rows = await this.db
                 .withSchema(MCP_SCHEMA)
                 .table("gateway_project_members as m")
                 .join("gateway_projects as p", "p.project_uuid", "m.project_uuid")
+                .join("gateway_clients as c", "c.client_uuid", "m.client_uuid")
                 .where("m.client_uuid", clientUuid)
                 .where("m.status", "active")
                 .where("p.is_active", true)
+                .modify((query) => {
+                if (localSessionId) {
+                    query.whereExists(function matchBoundConsole() {
+                        this.select(this.client.raw("1"))
+                            .from("mcp.gateway_project_consoles as pc")
+                            .whereRaw("pc.project_uuid = m.project_uuid")
+                            .whereRaw("pc.client_uuid = m.client_uuid")
+                            .where("pc.status", "active")
+                            .where("pc.local_session_id", localSessionId);
+                    });
+                }
+                if (scopeKey) {
+                    query.where("c.scope_key", scopeKey);
+                }
+            })
                 .select("p.project_uuid", "p.name", "p.invite_token", "m.role", "m.status", "m.joined_at")
                 .orderBy("p.name", "asc");
             return {
@@ -443,6 +1104,19 @@ const TelegramMcpGatewayService = {
                 .update({
                 status: "left",
             });
+            if (updated > 0) {
+                await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_project_consoles")
+                    .where({
+                    client_uuid: clientUuid,
+                    project_uuid: projectUuid,
+                })
+                    .update({
+                    status: "inactive",
+                    updated_at: new Date().toISOString(),
+                });
+            }
             const notifyRows = updated > 0
                 ? await this.db
                     .withSchema(MCP_SCHEMA)
@@ -456,6 +1130,16 @@ const TelegramMcpGatewayService = {
                 })
                     .distinct("client_uuid")
                 : [];
+            if (updated > 0 && notifyRows.length === 0) {
+                await this.db
+                    .withSchema(MCP_SCHEMA)
+                    .table("gateway_projects")
+                    .where({ project_uuid: projectUuid })
+                    .update({
+                    is_active: false,
+                    updated_at: new Date().toISOString(),
+                });
+            }
             return {
                 project_uuid: projectUuid,
                 left: updated > 0,
@@ -510,6 +1194,14 @@ const TelegramMcpGatewayService = {
                 .table("gateway_projects")
                 .where({ project_uuid: projectUuid })
                 .del();
+            await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_project_consoles")
+                .where({ project_uuid: projectUuid })
+                .update({
+                status: "inactive",
+                updated_at: new Date().toISOString(),
+            });
             return {
                 project_uuid: projectUuid,
                 deleted: deleted > 0,
@@ -540,27 +1232,37 @@ const TelegramMcpGatewayService = {
             }
             const rows = await this.db
                 .withSchema(MCP_SCHEMA)
-                .table("gateway_sessions as s")
-                .leftJoin("gateway_clients as c", "c.client_uuid", "s.client_uuid")
+                .table("gateway_project_consoles as pc")
+                .leftJoin("gateway_live_consoles as lc", function joinLiveConsole() {
+                this.on("lc.client_uuid", "=", "pc.client_uuid").andOn("lc.local_session_id", "=", "pc.local_session_id");
+            })
+                .leftJoin("gateway_clients as c", "c.client_uuid", "pc.client_uuid")
+                .leftJoin("gateway_users as u", "u.gateway_user_uuid", "c.owner_user_uuid")
                 .leftJoin("gateway_project_members as m", function joinMember() {
-                this.on("m.project_uuid", "=", "s.project_uuid").andOn("m.client_uuid", "=", "s.client_uuid");
+                this.on("m.project_uuid", "=", "pc.project_uuid").andOn("m.client_uuid", "=", "pc.client_uuid");
             })
-                .where("s.project_uuid", projectUuid)
-                .where("s.status", "active")
+                .where("pc.project_uuid", projectUuid)
+                .where("pc.status", "active")
                 .where("m.status", "active")
-                .select("s.session_uuid", "s.project_uuid", "s.client_uuid", "s.local_session_id", "s.label", "s.status", "s.updated_at", "c.client_label", this.db.raw("coalesce(nullif(m.telegram_username, ''), nullif(c.meta->>'telegram_username', '')) as telegram_username"), "c.bot_username", "m.joined_at")
-                .orderByRaw("coalesce(s.label, s.local_session_id) asc")
-                .orderBy("s.updated_at", "desc");
+                .orderBy("pc.client_uuid", "asc")
+                .orderBy("pc.joined_at", "asc")
+                .orderBy("pc.updated_at", "desc")
+                .select("pc.gateway_session_uuid as session_uuid", "pc.project_uuid", "pc.client_uuid", "pc.local_session_id", "pc.status", "pc.updated_at", "lc.session_label as label", "c.client_label", this.db.raw("coalesce(nullif(u.telegram_display_name, ''), nullif(m.display_name, ''), nullif(c.meta->>'telegram_display_name', '')) as display_name"), this.db.raw("coalesce(nullif(u.telegram_username, ''), nullif(m.telegram_username, ''), nullif(c.meta->>'telegram_username', '')) as telegram_username"), this.db.raw("nullif(c.meta->>'system_username', '') as system_username"), "c.bot_username", "m.joined_at")
+                .orderByRaw("coalesce(lc.session_label, pc.local_session_id) asc")
+                .orderBy("pc.updated_at", "desc");
             return {
                 sessions: rows.map((row) => ({
-                    session_uuid: row.session_uuid,
+                    session_uuid: row.session_uuid ??
+                        `${String(row.client_uuid)}:${String(row.local_session_id)}`,
                     project_uuid: row.project_uuid,
                     client_uuid: row.client_uuid,
                     local_session_id: row.local_session_id,
                     label: row.label ?? null,
                     status: row.status,
                     client_label: row.client_label ?? null,
+                    display_name: row.display_name ?? null,
                     telegram_username: row.telegram_username ?? null,
+                    system_username: row.system_username ?? null,
                     bot_username: row.bot_username ?? null,
                     ...(row.joined_at ? { joined_at: String(row.joined_at) } : {}),
                     ...(row.updated_at ? { updated_at: String(row.updated_at) } : {}),
@@ -582,14 +1284,18 @@ const TelegramMcpGatewayService = {
                 : kind === "question" || kind === "request";
             const targetSession = await this.db
                 .withSchema(MCP_SCHEMA)
-                .table("gateway_sessions as s")
-                .leftJoin("gateway_clients as c", "c.client_uuid", "s.client_uuid")
-                .leftJoin("gateway_projects as p", "p.project_uuid", "s.project_uuid")
-                .where({
-                "s.session_uuid": targetSessionId,
-                "s.status": "active",
+                .table("gateway_project_consoles as pc")
+                .join("gateway_sessions as s", "s.session_uuid", "pc.gateway_session_uuid")
+                .leftJoin("gateway_clients as c", "c.client_uuid", "pc.client_uuid")
+                .leftJoin("gateway_projects as p", "p.project_uuid", "pc.project_uuid")
+                .where("pc.gateway_session_uuid", targetSessionId)
+                .modify((query) => {
+                if (requestedProjectUuid) {
+                    query.where("pc.project_uuid", requestedProjectUuid);
+                }
             })
-                .select("s.*", "p.name as project_name", this.db.raw("coalesce(nullif(c.meta->>'telegram_display_name', ''), nullif(c.meta->>'telegram_username', ''), c.client_label, c.bot_username) as target_actor_label"))
+                .where("pc.status", "active")
+                .select("s.*", "pc.project_uuid", "p.name as project_name", this.db.raw("coalesce(nullif(c.meta->>'telegram_display_name', ''), nullif(c.meta->>'telegram_username', ''), c.client_label, c.bot_username) as target_actor_label"))
                 .first();
             if (!targetSession) {
                 throw new Error(`Target project session ${targetSessionId} was not found.`);
@@ -598,18 +1304,26 @@ const TelegramMcpGatewayService = {
                 requestedProjectUuid !== String(targetSession.project_uuid)) {
                 throw new Error("Target session does not belong to the requested project.");
             }
-            const sourceSession = await this.db
+            const sourceProjectConsole = await this.db
                 .withSchema(MCP_SCHEMA)
-                .table("gateway_sessions")
+                .table("gateway_project_consoles")
                 .where({
                 project_uuid: String(targetSession.project_uuid),
                 client_uuid: clientUuid,
                 local_session_id: localSessionId,
                 status: "active",
             })
+                .first("gateway_session_uuid");
+            if (!sourceProjectConsole?.gateway_session_uuid) {
+                throw new Error(`Active project session '${localSessionId}' is not registered for client ${clientUuid} in project ${targetSession.project_uuid}.`);
+            }
+            const sourceSession = await this.db
+                .withSchema(MCP_SCHEMA)
+                .table("gateway_sessions")
+                .where({ session_uuid: String(sourceProjectConsole.gateway_session_uuid) })
                 .first();
             if (!sourceSession) {
-                throw new Error(`Active project session '${localSessionId}' is not registered for client ${clientUuid} in project ${targetSession.project_uuid}.`);
+                throw new Error(`Gateway session anchor for '${localSessionId}' was not found in project ${targetSession.project_uuid}.`);
             }
             const shareId = (0, node_crypto_1.randomUUID)();
             const messageUuid = (0, node_crypto_1.randomUUID)();
@@ -642,7 +1356,7 @@ const TelegramMcpGatewayService = {
             });
             await this.db.withSchema(MCP_SCHEMA).table("gateway_messages").insert({
                 message_uuid: messageUuid,
-                project_uuid: sourceSession.project_uuid,
+                project_uuid: String(targetSession.project_uuid),
                 from_session_uuid: sourceSession.session_uuid,
                 to_session_uuid: targetSession.session_uuid,
                 kind,
@@ -720,6 +1434,7 @@ const TelegramMcpGatewayService = {
                 ...(targetSession.project_name
                     ? { project_name: targetSession.project_name }
                     : {}),
+                project_uuid: String(targetSession.project_uuid),
                 ...(targetSession.target_actor_label
                     ? { target_actor_label: targetSession.target_actor_label }
                     : {}),
@@ -730,7 +1445,7 @@ const TelegramMcpGatewayService = {
                 share_id: shareId,
                 delivery_status: "queued",
                 note_path: `gateway://shares/${shareId}.md`,
-                share_index_path: "gateway://SHARED_INDEX.md",
+                xchange_record_id: shareId,
                 copied_artifacts: artifactRefs.map((artifact) => trimOptionalText(artifact.original_name) ||
                     trimOptionalText(artifact.relative_path) ||
                     trimOptionalText(artifact.file_path) ||
@@ -746,6 +1461,7 @@ const TelegramMcpGatewayService = {
                     ...(targetSession.project_name
                         ? { project_name: targetSession.project_name }
                         : {}),
+                    project_uuid: String(targetSession.project_uuid),
                     source_actor_label: sourceSession.label ?? sourceSession.local_session_id,
                     kind,
                     summary,
@@ -761,7 +1477,6 @@ const TelegramMcpGatewayService = {
                     target_session_label: targetSession.label ?? targetSession.local_session_id,
                     created_at: now,
                     note_relative_path: `shares/${shareId}.md`,
-                    share_index_file_name: "SHARED_INDEX.md",
                     artifacts: queuedArtifacts,
                 },
             };
@@ -844,7 +1559,6 @@ const TelegramMcpGatewayService = {
                         target_session_label: row.target_session_label ?? row.target_local_session_id,
                         created_at: String(row.created_at),
                         note_relative_path: `shares/${shareId}.md`,
-                        share_index_file_name: "SHARED_INDEX.md",
                         artifacts: artifactsByMessage.get(row.message_uuid) ?? [],
                     };
                 }),
@@ -1016,6 +1730,22 @@ const TelegramMcpGatewayService = {
         },
     },
     actions: {
+        upsertGatewayUser: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.upsertGatewayUserRecord?.(ctx.params);
+            },
+        },
+        resolveGatewayUserRoute: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.resolveGatewayUserRouteRecord?.(ctx.params);
+            },
+        },
         registerClient: {
             async handler(ctx) {
                 if (!GATEWAY_ENABLED) {
@@ -1024,6 +1754,62 @@ const TelegramMcpGatewayService = {
                 return this.registerClientRecord?.(ctx.params);
             },
         },
+        syncLiveConsoles: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.syncLiveConsolesRecord?.(ctx.params);
+            },
+        },
+        clearLiveConsoles: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.clearLiveConsolesRecord?.(ctx.params);
+            },
+        },
+        removeLiveConsoles: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.removeLiveConsolesRecord?.(ctx.params);
+            },
+        },
+        pruneGatewayState: {
+            async handler() {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.pruneGatewayStateRecord?.();
+            },
+        },
+        listLiveClients: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.listLiveClientsRecord?.(ctx.params);
+            },
+        },
+        listLiveConsoles: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.listLiveConsolesRecord?.(ctx.params);
+            },
+        },
+        resolveLiveConsole: {
+            async handler(ctx) {
+                if (!GATEWAY_ENABLED) {
+                    throw new Error("Gateway service is disabled in client mode");
+                }
+                return this.resolveLiveConsoleRecord?.(ctx.params);
+            },
+        },
         createProject: {
             async handler(ctx) {
                 if (!GATEWAY_ENABLED) {
@@ -1048,12 +1834,12 @@ const TelegramMcpGatewayService = {
                 return this.registerSessionRecord?.(ctx.params);
             },
         },
-        unregisterSession: {
+        listClients: {
             async handler(ctx) {
                 if (!GATEWAY_ENABLED) {
                     throw new Error("Gateway service is disabled in client mode");
                 }
-                return this.unregisterSessionRecord?.(ctx.params);
+                return this.listClientsRecord?.(ctx.params);
             },
         },
         listProjects: {
@@ -1137,5 +1923,14 @@ const TelegramMcpGatewayService = {
             },
         },
     },
+    async started() {
+        if (!GATEWAY_ENABLED) {
+            return;
+        }
+        const cleared = await this.clearLiveConsolesRecord?.();
+        this.logger.info("Gateway live consoles registry cleared on startup", {
+            deleted: cleared?.deleted ?? 0,
+        });
+    },
 };
 exports.default = TelegramMcpGatewayService;