@mastra/discord 1.2.1 → 1.3.0-alpha.0

package/dist/index.d.cts

@@ -265,6 +265,42 @@ interface DiscordInstallation {
   commandVersions?: Record<string, string>;
   /** When the installation was created. */
   installedAt: Date;
+  /**
+   * The bot's guild ids at the moment a pending invite was issued. Lets
+   * {@link DiscordProvider.reconcileInstallation} confirm the install after the
+   * operator completes the invite in another tab: exactly one guild appearing
+   * since the snapshot is the authorized guild, so the install activates
+   * without waiting for a first interaction. `undefined` when the snapshot
+   * couldn't be taken (or the bot is in too many guilds to page) — the install
+   * then activates only via the first interaction, as before. Cleared on
+   * activation.
+   */
+  guildSnapshot?: string[];
+  /**
+   * When the invite flow that owns {@link guildSnapshot} was last (re)started.
+   * The snapshot is only trusted for a bounded claim window after this moment
+   * (see `SNAPSHOT_TTL_MS` in `reconcile.ts`) — an abandoned Connect click must
+   * not claim a guild the bot joins days later. Set on every invite-flow
+   * `connect()`, including when the fetch that should have produced
+   * {@link guildSnapshot} failed. Cleared on activation.
+   */
+  snapshotAt?: Date;
+  /**
+   * The Discord application {@link guildSnapshot} was taken against. A baseline
+   * from app A says nothing about app B's membership — after `configure()`
+   * swaps the bot token, every guild B was already in would look newly
+   * authorized. Reconciliation and snapshot reuse require it to match the
+   * current app. Cleared on activation.
+   */
+  snapshotApplicationId?: string;
+  /**
+   * The guild `connect()` explicitly targeted (`options.guildId`) when the
+   * pending invite was issued, if any. Reconciliation only auto-activates this
+   * install on that guild — a different guild appearing in the bot's
+   * membership contradicts the caller's intent and waits for an authoritative
+   * first interaction instead. Cleared on activation.
+   */
+  targetGuildId?: string;
 }
 //#endregion
 //#region src/discord-provider.d.ts
@@ -372,8 +408,42 @@ declare class DiscordProvider implements ChannelProvider {
    * duration boundary. Contrast Telegram's clean `stopPolling()`.
    */
   disconnect(agentId: string): Promise<void>;
-  /** List installations (public info only — no secrets). */
+  /**
+   * List installations (public info only — no secrets). A pure read: pending
+   * installs are confirmed through the write-authorized
+   * {@link reconcileInstallation} path, never as a listing side effect.
+   */
   listInstallations(): Promise<ChannelInstallationInfo[]>;
+  /**
+   * Activate an agent's pending install if its invite has since been completed.
+   *
+   * The invite URL carries no `redirect_uri` (the app would have to allowlist
+   * every operator origin), so nothing calls back when the operator authorizes
+   * the bot — and a pending install has no adapter, so no interaction or
+   * gateway event can reach it either. Instead, each pending install carries a
+   * {@link DiscordInstallation.guildSnapshot} taken when the invite was issued;
+   * this diffs it against the bot's current membership and activates the
+   * install when exactly one new, uncontested guild has appeared (the full
+   * claim rules live in {@link planReconcile}). The claim analysis spans every
+   * install — other pending invites contest the diff — but only **this**
+   * agent's install can activate: the caller holds write access for this agent
+   * alone. Anything ambiguous stays pending and retries on the next call, with
+   * the first interaction as the authoritative fallback. Best-effort: failures
+   * log and resolve rather than throw.
+   *
+   * Called by the server's reconcile route (write-authorized); Studio invokes
+   * it on window focus while a connect is in flight. Returns the (possibly
+   * just-activated) installation's public info, or `null` when the agent has
+   * no installation.
+   *
+   * Limitation: the bot-invite URL is per-app, not per-install, so when the
+   * operator invites the bot to a new server *for an already-active install*
+   * (as `connect()`'s already-connected error suggests) while an invite for
+   * another agent is outstanding, nothing distinguishes the two intents — the
+   * new guild can be attributed to the pending install. Reconciliation is only
+   * reliable while a single invite flow is in progress.
+   */
+  reconcileInstallation(agentId: string): Promise<ChannelInstallationInfo | null>;
   /** The full installation for an agent (no secrets live on it), or `null`. */
   getInstallation(agentId: string): Promise<DiscordInstallation | null>;
   /** Whether the Discord app is configured (credentials resolvable). */

package/dist/index.d.ts

@@ -265,6 +265,42 @@ interface DiscordInstallation {
   commandVersions?: Record<string, string>;
   /** When the installation was created. */
   installedAt: Date;
+  /**
+   * The bot's guild ids at the moment a pending invite was issued. Lets
+   * {@link DiscordProvider.reconcileInstallation} confirm the install after the
+   * operator completes the invite in another tab: exactly one guild appearing
+   * since the snapshot is the authorized guild, so the install activates
+   * without waiting for a first interaction. `undefined` when the snapshot
+   * couldn't be taken (or the bot is in too many guilds to page) — the install
+   * then activates only via the first interaction, as before. Cleared on
+   * activation.
+   */
+  guildSnapshot?: string[];
+  /**
+   * When the invite flow that owns {@link guildSnapshot} was last (re)started.
+   * The snapshot is only trusted for a bounded claim window after this moment
+   * (see `SNAPSHOT_TTL_MS` in `reconcile.ts`) — an abandoned Connect click must
+   * not claim a guild the bot joins days later. Set on every invite-flow
+   * `connect()`, including when the fetch that should have produced
+   * {@link guildSnapshot} failed. Cleared on activation.
+   */
+  snapshotAt?: Date;
+  /**
+   * The Discord application {@link guildSnapshot} was taken against. A baseline
+   * from app A says nothing about app B's membership — after `configure()`
+   * swaps the bot token, every guild B was already in would look newly
+   * authorized. Reconciliation and snapshot reuse require it to match the
+   * current app. Cleared on activation.
+   */
+  snapshotApplicationId?: string;
+  /**
+   * The guild `connect()` explicitly targeted (`options.guildId`) when the
+   * pending invite was issued, if any. Reconciliation only auto-activates this
+   * install on that guild — a different guild appearing in the bot's
+   * membership contradicts the caller's intent and waits for an authoritative
+   * first interaction instead. Cleared on activation.
+   */
+  targetGuildId?: string;
 }
 //#endregion
 //#region src/discord-provider.d.ts
@@ -372,8 +408,42 @@ declare class DiscordProvider implements ChannelProvider {
    * duration boundary. Contrast Telegram's clean `stopPolling()`.
    */
   disconnect(agentId: string): Promise<void>;
-  /** List installations (public info only — no secrets). */
+  /**
+   * List installations (public info only — no secrets). A pure read: pending
+   * installs are confirmed through the write-authorized
+   * {@link reconcileInstallation} path, never as a listing side effect.
+   */
   listInstallations(): Promise<ChannelInstallationInfo[]>;
+  /**
+   * Activate an agent's pending install if its invite has since been completed.
+   *
+   * The invite URL carries no `redirect_uri` (the app would have to allowlist
+   * every operator origin), so nothing calls back when the operator authorizes
+   * the bot — and a pending install has no adapter, so no interaction or
+   * gateway event can reach it either. Instead, each pending install carries a
+   * {@link DiscordInstallation.guildSnapshot} taken when the invite was issued;
+   * this diffs it against the bot's current membership and activates the
+   * install when exactly one new, uncontested guild has appeared (the full
+   * claim rules live in {@link planReconcile}). The claim analysis spans every
+   * install — other pending invites contest the diff — but only **this**
+   * agent's install can activate: the caller holds write access for this agent
+   * alone. Anything ambiguous stays pending and retries on the next call, with
+   * the first interaction as the authoritative fallback. Best-effort: failures
+   * log and resolve rather than throw.
+   *
+   * Called by the server's reconcile route (write-authorized); Studio invokes
+   * it on window focus while a connect is in flight. Returns the (possibly
+   * just-activated) installation's public info, or `null` when the agent has
+   * no installation.
+   *
+   * Limitation: the bot-invite URL is per-app, not per-install, so when the
+   * operator invites the bot to a new server *for an already-active install*
+   * (as `connect()`'s already-connected error suggests) while an invite for
+   * another agent is outstanding, nothing distinguishes the two intents — the
+   * new guild can be attributed to the pending install. Reconciliation is only
+   * reliable while a single invite flow is in progress.
+   */
+  reconcileInstallation(agentId: string): Promise<ChannelInstallationInfo | null>;
   /** The full installation for an agent (no secrets live on it), or `null`. */
   getInstallation(agentId: string): Promise<DiscordInstallation | null>;
   /** Whether the Discord app is configured (credentials resolvable). */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/discord-provider.ts","../src/install-store.ts","../src/discord-client.ts","../src/commands.ts","../src/crypto.ts"],"mappings":";;;;;;;;;;;;cAgBa;;cAGA;;;;;;;;cASA;WACX;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;;;;;;;cAUW;;cAWA;;;;;;UAOI;;EAEf;;EAEA;;;KAIU;EAAiC;EAAc;;;;;;;;UAQ1C;;EAEf;;EAEA;;EAEA;;;;;;;;;;UAWe;;;;;;;;;EASf,MAAM,QAAQ;;;;;EAKd;;;;;;EAMA,UAAU;;;;;EAKV;;;;;;;EAOA;;;;;EAKA;;;;;;EAMA,WAAW;;;;;;;;;;EAUX;;;;;EAKA,YAAY;;;;;;;;EAQZ;;;;;EAKA;;;;;;EAMA,mBAAmB;;EAEnB,SAAS;;;;;;;;EAQT,YAAY;;;;;;EAMZ;;EASA,WAAW;;EAEX,cAAc;;EAEd,cAAc;;EAEd,QAAQ;;EAER,gBAAgB;;EAEhB,cAAc;;EAEd,oBAAoB;;EAEpB,mBAAmB;;EAEnB,OAAO;;EAEP,cAAc;;;;;;;;EAQd,cAAc;;;;;;;EAOd,QAAQ;;EAER,aAAa,cAAc,+BAA+B;;;UAI3C;;;;;;;EAOf;;EAEA;;;;;EAKA,WAAW;;EAEX;;;;;;;;;UAUe;;EAEf;;EAEA;;;;;EAKA;;;;;EAKA;;EAEA;;EAEA;;EAEA,WAAW;;;;;;EAMX,kBAAkB;;EAElB,aAAa;;;;;;;;;;;iBChQC,4BACd,QAAQ,KAAK;EAEb,WAAW;EACX;EACA,aAAa;EACb;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmCW,2BAA2B;;WAC7B;EAoCT,YAAY,SAAQ;;;;;EAYpB,SAAS,QAAQ;;;;;;;;;EAwCjB,aAAa;;EAoBb,WAAW;;;;;;EAgCL,cAAc;;;;;;;;;EAiCd,UAAU,aAAa,QAAQ,2BAA2B;;;;;;;;;;;;;;EAmE1D,QAAQ,iBAAiB,UAAS,wBAA6B,QAAQ;;;;;;;EA6EvE,cAAc,mBAAmB,kBAAkB,QAAQ;;;;;;;;;;EAmD3D,WAAW,kBAAkB;;EAY7B,qBAAqB,QAAQ;;EAO7B,gBAAgB,kBAAkB,QAAQ;;EAMhD;;EAKA,WAAW,yBAAyB;;;;;cCtdzB;;;;;;;;;;;;;cAgCA;;mBAEQ;mBACA;EAFnB,YACmB,SAAS,iBACT;;EAMb,gBAAgB,QAAQ;;EAaxB,cAAc,KAAK,mBAAmB;;EAUtC,mBAAmB;;EAOnB,WAAW,kBAAkB,QAAQ;;EAMrC,eAAe,oBAAoB,QAAQ;;;;;;;;;;;;;;;;EAoB3C,aAAa,kBAAkB,QAAQ;;EAqBvC,KAAK,cAAc,sBAAsB;;EAKzC,QAAQ,QAAQ;;EAMhB,cAAc,kBAAkB;;;iBA6DxB,mBAAmB,SAAS,sBAAsB;;;;;;;;UC/JjD;;EAEf;;EAEA;;;;;;EAMA;;;;;;;;;;;;iBAmBoB,eACpB,kBACA,gBACA,cACA,qBACA,iBACC,QAAQ;;;;;;;iBA+BW,YACpB,kBACA,sBACC,QAAQ;;;;;;;;;;;;;;iBAyBW,iBACpB,kBACA,iBACA,sBACC;;;;;;;;iBA8EmB,sBACpB,kBACA,uBACA,iBACA,mBAAmB,kBACnB,sBACC;;;;;;;;iBAcmB,uBACpB,kBACA,uBACA,mBAAmB,kBACnB,sBACC;;UAOc;;EAEf;;EAEA;;EAEA;;;;;EAKA;;;;;;;;;iBAUc,eAAe,SAAS;;;;;;;;;cCjQ3B,2BAA2B;;;;;;;;;;iBAaxB,kBAAkB,cAAc,oCAAoC;;;;;;;iBAyBpE,aAAa,mBAAmB;;;;iBC3BhC,YAAY;;iBAKZ,QAAQ,mBAAmB;;iBAU3B,QAAQ,eAAe"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/discord-provider.ts","../src/install-store.ts","../src/discord-client.ts","../src/commands.ts","../src/crypto.ts"],"mappings":"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"}

package/dist/index.js

@@ -130,6 +130,37 @@ async function guildHealthCheck(botToken, guildId, apiBaseUrl = DISCORD_API_BASE
 	}
 	throw new Error(`Discord guild lookup failed for "${guildId}": ${await describeError(response)}`);
 }
+/** Guilds-per-page for `GET /users/@me/guilds` (Discord's documented maximum). */
+const GUILD_PAGE_LIMIT = 200;
+/**
+* Pages we're willing to walk when listing the bot's guilds. The listing feeds
+* the pending-install snapshot diff, whose multiple-new-guilds guard keeps an
+* *incomplete* listing safe (reconcile just stays pending) — so a hard cap is
+* preferable to an unbounded walk on a bot in thousands of guilds.
+*/
+const GUILD_PAGE_MAX_PAGES = 10;
+/**
+* The ids of every guild the bot is a member of, via `GET /users/@me/guilds`
+* (Bot auth), following `after`-cursor pagination. Returns `null` instead of a
+* partial listing when the bot is in more guilds than {@link GUILD_PAGE_MAX_PAGES}
+* covers — callers diffing snapshots must not mistake a truncated page for the
+* full membership. Throws on request failure.
+*
+* @see https://discord.com/developers/docs/resources/user#get-current-user-guilds
+*/
+async function listBotGuildIds(botToken, apiBaseUrl = DISCORD_API_BASE_URL) {
+	const ids = [];
+	let after;
+	for (let page = 0; page < GUILD_PAGE_MAX_PAGES; page++) {
+		const response = await discordRequest(botToken, "GET", `/users/@me/guilds${`?limit=${GUILD_PAGE_LIMIT}${after ? `&after=${after}` : ""}`}`, apiBaseUrl);
+		if (!response.ok) throw new Error(`Discord guild listing failed: ${await describeError(response)}`);
+		const batch = await response.json();
+		for (const guild of batch) ids.push(guild.id);
+		if (batch.length < GUILD_PAGE_LIMIT) return ids;
+		after = batch[batch.length - 1].id;
+	}
+	return null;
+}
 /** Map normalized commands to the Discord bulk-overwrite `CHAT_INPUT` payload. */
 function toCommandPayload(commands) {
 	return commands.map((c) => ({
@@ -430,7 +461,11 @@ var DiscordInstallStore = class {
 			guildIds: install.guildIds,
 			displayName: install.displayName,
 			commands: install.commands,
-			commandVersions: install.commandVersions
+			commandVersions: install.commandVersions,
+			guildSnapshot: install.guildSnapshot,
+			snapshotAt: install.snapshotAt?.toISOString(),
+			snapshotApplicationId: install.snapshotApplicationId,
+			targetGuildId: install.targetGuildId
 		};
 		return {
 			id: install.id,
@@ -454,7 +489,11 @@ var DiscordInstallStore = class {
 			displayName: data.displayName,
 			commands: data.commands,
 			commandVersions: data.commandVersions,
-			installedAt: record.createdAt
+			installedAt: record.createdAt,
+			guildSnapshot: data.guildSnapshot,
+			snapshotAt: data.snapshotAt ? new Date(data.snapshotAt) : void 0,
+			snapshotApplicationId: data.snapshotApplicationId,
+			targetGuildId: data.targetGuildId
 		};
 	}
 };
@@ -469,6 +508,78 @@ function toInstallationInfo(install) {
 		installedAt: install.installedAt
 	};
 }
+/**
+* Whether an install's invite flow is still *live*: started against the
+* current application and within {@link SNAPSHOT_TTL_MS}. Deliberately
+* independent of whether the baseline fetch succeeded — a live flow with a
+* missing baseline still poisons attribution (see {@link planReconcile}),
+* while rows from before these fields existed (no `snapshotAt`) are treated
+* as not live and fall back to first-interaction activation.
+*/
+function isInviteFlowLive(installation, applicationId, now) {
+	return installation.status === "pending" && installation.snapshotApplicationId === applicationId && installation.snapshotAt != null && now.getTime() - installation.snapshotAt.getTime() <= 18e5;
+}
+/**
+* Whether a pending install can reconcile at all: a live invite flow (see
+* {@link isInviteFlowLive}) *with* a membership baseline to diff against.
+* Used as a cheap pre-check before the membership fetch.
+*/
+function hasReconcilableSnapshot(installation, applicationId, now) {
+	return installation.guildSnapshot != null && isInviteFlowLive(installation, applicationId, now);
+}
+/**
+* Decide which pending installs the completed-invite reconcile pass may
+* activate, and on which guild. Pure claim analysis over plain data — all
+* store reads, membership fetches, and activations happen in the caller
+* ({@link DiscordProvider.reconcileInstallation}).
+*
+* Rules, in order:
+* - Only installs with a live invite flow ({@link isInviteFlowLive}) take part.
+*   Expired/foreign-app baselines are ignored (first interaction remains their
+*   activation path), as are legacy rows without snapshot metadata.
+* - A live flow whose baseline fetch failed at connect time poisons the whole
+*   pass: any new guild might be ITS invite landing, so nothing is attributed.
+* - A guild any install already lists is owned and never claimed — it can
+*   still look "new" relative to a stale baseline.
+* - An install with an explicit {@link DiscordInstallation.targetGuildId}
+*   claims *only* that guild. The narrowing happens before claims are tallied,
+*   so a targeted install never contests a guild it would refuse anyway — but
+*   its target, if new, still blocks other installs from taking it.
+* - An install activates only on exactly one new guild, claimed by no other
+*   live install. Zero or multiple candidates, or a contested guild, stay
+*   pending and retry on the next pass.
+*/
+function planReconcile(input) {
+	const { installations, currentGuildIds, applicationId, now } = input;
+	const live = installations.filter((i) => isInviteFlowLive(i, applicationId, now));
+	const claimants = live.filter((i) => i.guildSnapshot != null);
+	if (claimants.length === 0) return [];
+	if (claimants.length !== live.length) return [];
+	const owned = new Set(installations.flatMap((i) => i.guildIds));
+	const diffs = claimants.map((installation) => {
+		const snapshot = new Set(installation.guildSnapshot);
+		let newGuilds = currentGuildIds.filter((id) => !snapshot.has(id) && !owned.has(id));
+		if (installation.targetGuildId != null) newGuilds = newGuilds.includes(installation.targetGuildId) ? [installation.targetGuildId] : [];
+		return {
+			installation,
+			newGuilds
+		};
+	});
+	const claims = /* @__PURE__ */ new Map();
+	for (const { newGuilds } of diffs) for (const id of newGuilds) claims.set(id, (claims.get(id) ?? 0) + 1);
+	const activations = [];
+	for (const { installation, newGuilds } of diffs) {
+		const guildId = newGuilds.length === 1 ? newGuilds[0] : void 0;
+		if (guildId == null || claims.get(guildId) > 1) continue;
+		activations.push({
+			installationId: installation.id,
+			agentId: installation.agentId,
+			webhookId: installation.webhookId,
+			guildId
+		});
+	}
+	return activations;
+}
 //#endregion
 //#region src/discord-provider.ts
 /**
@@ -726,39 +837,69 @@ var DiscordProvider = class {
 		const installedAt = existing?.installedAt ?? /* @__PURE__ */ new Date();
 		const commands = normalizeCommands(options.commands ?? this.#config.commands ?? DEFAULT_COMMANDS);
 		if (options.guildId && await guildHealthCheck(app.botToken, options.guildId, this.#apiBaseUrl())) {
-			const installation = {
+			const guildId = options.guildId;
+			return await this.#enqueueWebhookTask(webhookId, async () => {
+				const fresh = existing ? await store.getByWebhookId(webhookId) : null;
+				if (fresh?.status === "active") return {
+					type: "immediate",
+					installationId: fresh.id
+				};
+				const installation = {
+					id: installationId,
+					agentId,
+					webhookId,
+					status: "active",
+					guildIds: [guildId],
+					displayName,
+					commands: commands.length ? commands : void 0,
+					commandVersions: fresh?.commandVersions ?? existing?.commandVersions,
+					installedAt
+				};
+				await store.save(installation);
+				await this.#registerCommands(app, installation, guildId);
+				await this.#activateInstallation(installation);
+				this.#configured = true;
+				await this.#config.onInstall?.(installation);
+				return {
+					type: "immediate",
+					installationId
+				};
+			});
+		}
+		const outcome = await this.#enqueueWebhookTask(webhookId, async () => {
+			const fresh = existing ? await store.getByWebhookId(webhookId) : null;
+			if (fresh?.status === "active") return {
+				type: "immediate",
+				installationId: fresh.id
+			};
+			const base = fresh ?? existing;
+			const now = /* @__PURE__ */ new Date();
+			let guildSnapshot = base?.guildSnapshot != null && base.snapshotApplicationId === app.applicationId && base.snapshotAt != null && now.getTime() - base.snapshotAt.getTime() <= 18e5 ? base.guildSnapshot : void 0;
+			if (!guildSnapshot) try {
+				guildSnapshot = await listBotGuildIds(app.botToken, this.#apiBaseUrl()) ?? void 0;
+			} catch (err) {
+				console.warn("[Discord] Could not snapshot guild membership for pending install:", err);
+			}
+			const pending = {
 				id: installationId,
 				agentId,
 				webhookId,
-				status: "active",
-				guildIds: [options.guildId],
+				status: "pending",
+				guildIds: base?.guildIds ?? [],
 				displayName,
 				commands: commands.length ? commands : void 0,
-				commandVersions: existing?.commandVersions,
-				installedAt
+				commandVersions: base?.commandVersions,
+				installedAt,
+				guildSnapshot,
+				snapshotAt: now,
+				snapshotApplicationId: app.applicationId,
+				targetGuildId: options.guildId ?? base?.targetGuildId
 			};
-			await store.save(installation);
-			await this.#registerCommands(app, installation, options.guildId);
-			await this.#activateInstallation(installation);
-			this.#configured = true;
-			await this.#config.onInstall?.(installation);
-			return {
-				type: "immediate",
-				installationId
-			};
-		}
-		const pending = {
-			id: installationId,
-			agentId,
-			webhookId,
-			status: "pending",
-			guildIds: existing?.guildIds ?? [],
-			displayName,
-			commands: commands.length ? commands : void 0,
-			commandVersions: existing?.commandVersions,
-			installedAt
-		};
-		await store.save(pending);
+			await store.save(pending);
+			return pending;
+		});
+		if ("type" in outcome) return outcome;
+		const pending = outcome;
 		await this.#registerCommands(app, pending);
 		this.#configured = true;
 		return {
@@ -779,7 +920,22 @@ var DiscordProvider = class {
 	* `webhookId` is unknown.
 	*/
 	async activateGuild(webhookId, guildId) {
-		const next = (this.#activationChains.get(webhookId) ?? Promise.resolve()).catch(() => {}).then(() => this.#activateGuildNow(webhookId, guildId));
+		return this.#enqueueWebhookTask(webhookId, () => this.#activateGuildNow(webhookId, guildId));
+	}
+	#activationChains = /* @__PURE__ */ new Map();
+	/**
+	* Serialize every mutation of one webhook's installation row — activations,
+	* pending-row saves, runtime bring-up, disconnects — so each task's read
+	* happens *after* the previous task's save. Without the chain, two
+	* concurrent first-interactions can lose a guildId (both read the same row,
+	* second save overwrites the first) or fire onInstall twice; a connect's
+	* pending save can clobber a row a racing interaction just activated; and a
+	* disconnect can land mid-activation and be resurrected by its post-HTTP
+	* persistence. The chain entry is dropped once the last queued task settles
+	* so keys don't accumulate forever.
+	*/
+	async #enqueueWebhookTask(webhookId, task) {
+		const next = (this.#activationChains.get(webhookId) ?? Promise.resolve()).catch(() => {}).then(task);
 		this.#activationChains.set(webhookId, next);
 		try {
 			return await next;
@@ -787,7 +943,6 @@ var DiscordProvider = class {
 			if (this.#activationChains.get(webhookId) === next) this.#activationChains.delete(webhookId);
 		}
 	}
-	#activationChains = /* @__PURE__ */ new Map();
 	async #activateGuildNow(webhookId, guildId) {
 		const store = await this.#getStore();
 		const installation = await store.getByWebhookId(webhookId);
@@ -797,6 +952,10 @@ var DiscordProvider = class {
 		if (wasActive && known) return installation;
 		if (!known) installation.guildIds.push(guildId);
 		installation.status = "active";
+		delete installation.guildSnapshot;
+		delete installation.snapshotAt;
+		delete installation.snapshotApplicationId;
+		delete installation.targetGuildId;
 		await store.save(installation);
 		const app = await store.getAppConfig();
 		if (app) await this.#registerCommands(app, installation, guildId);
@@ -817,14 +976,98 @@ var DiscordProvider = class {
 		const store = await this.#getStore();
 		const existing = await store.getByAgent(agentId);
 		if (!existing) throw new Error(`No Discord installation found for agent "${agentId}"`);
-		this.#adapters.delete(existing.id);
-		await store.deleteByAgent(agentId);
+		await this.#enqueueWebhookTask(existing.webhookId, async () => {
+			this.#adapters.delete(existing.id);
+			await store.deleteByAgent(agentId);
+		});
 		this.#configured = await store.getAppConfig() != null || (await store.list()).some((i) => i.status === "active");
 	}
-	/** List installations (public info only — no secrets). */
+	/**
+	* List installations (public info only — no secrets). A pure read: pending
+	* installs are confirmed through the write-authorized
+	* {@link reconcileInstallation} path, never as a listing side effect.
+	*/
 	async listInstallations() {
 		return (await (await this.#getStore()).list()).map(toInstallationInfo);
 	}
+	/**
+	* Activate an agent's pending install if its invite has since been completed.
+	*
+	* The invite URL carries no `redirect_uri` (the app would have to allowlist
+	* every operator origin), so nothing calls back when the operator authorizes
+	* the bot — and a pending install has no adapter, so no interaction or
+	* gateway event can reach it either. Instead, each pending install carries a
+	* {@link DiscordInstallation.guildSnapshot} taken when the invite was issued;
+	* this diffs it against the bot's current membership and activates the
+	* install when exactly one new, uncontested guild has appeared (the full
+	* claim rules live in {@link planReconcile}). The claim analysis spans every
+	* install — other pending invites contest the diff — but only **this**
+	* agent's install can activate: the caller holds write access for this agent
+	* alone. Anything ambiguous stays pending and retries on the next call, with
+	* the first interaction as the authoritative fallback. Best-effort: failures
+	* log and resolve rather than throw.
+	*
+	* Called by the server's reconcile route (write-authorized); Studio invokes
+	* it on window focus while a connect is in flight. Returns the (possibly
+	* just-activated) installation's public info, or `null` when the agent has
+	* no installation.
+	*
+	* Limitation: the bot-invite URL is per-app, not per-install, so when the
+	* operator invites the bot to a new server *for an already-active install*
+	* (as `connect()`'s already-connected error suggests) while an invite for
+	* another agent is outstanding, nothing distinguishes the two intents — the
+	* new guild can be attributed to the pending install. Reconciliation is only
+	* reliable while a single invite flow is in progress.
+	*/
+	async reconcileInstallation(agentId) {
+		const store = await this.#getStore();
+		const existing = await store.getByAgent(agentId);
+		if (!existing) return null;
+		if (existing.status === "pending") {
+			const inflight = this.#reconcileInflight.get(agentId);
+			if (inflight) await inflight;
+			else {
+				const run = this.#reconcilePendingInstallation(store, agentId).finally(() => {
+					this.#reconcileInflight.delete(agentId);
+				});
+				this.#reconcileInflight.set(agentId, run);
+				await run;
+			}
+		}
+		const fresh = await store.getByAgent(agentId);
+		return fresh ? toInstallationInfo(fresh) : null;
+	}
+	#reconcileInflight = /* @__PURE__ */ new Map();
+	async #reconcilePendingInstallation(store, agentId) {
+		try {
+			const app = await store.getAppConfig();
+			if (!app) return;
+			const target = await store.getByAgent(agentId);
+			if (!target || target.status !== "pending") return;
+			if (!hasReconcilableSnapshot(target, app.applicationId, /* @__PURE__ */ new Date())) return;
+			const current = await listBotGuildIds(app.botToken, this.#apiBaseUrl());
+			if (!current) return;
+			const activation = planReconcile({
+				installations: await store.list(),
+				currentGuildIds: current,
+				applicationId: app.applicationId,
+				now: /* @__PURE__ */ new Date()
+			}).find((a) => a.agentId === agentId);
+			if (!activation) return;
+			await this.#enqueueWebhookTask(activation.webhookId, async () => {
+				const activated = await this.#activateGuildNow(activation.webhookId, activation.guildId);
+				if (!activated || this.#adapters.has(activated.id)) return;
+				try {
+					await this.#activateInstallation(activated);
+				} catch (err) {
+					this.#adapters.delete(activated.id);
+					throw err;
+				}
+			});
+		} catch (err) {
+			console.warn(`[Discord] Pending-install reconcile for agent "${agentId}" failed (will retry):`, err);
+		}
+	}
 	/** The full installation for an agent (no secrets live on it), or `null`. */
 	async getInstallation(agentId) {
 		return await (await this.#getStore()).getByAgent(agentId) ?? null;
@@ -908,7 +1151,14 @@ var DiscordProvider = class {
 				...versions,
 				[key]: hash
 			};
-			await (await this.#getStore()).save(installation);
+			const store = await this.#getStore();
+			const fresh = await store.getByWebhookId(installation.webhookId);
+			if (!fresh) return;
+			fresh.commandVersions = {
+				...fresh.commandVersions,
+				[key]: hash
+			};
+			await store.save(fresh);
 		} catch (err) {
 			console.warn(`[Discord] command registration failed (${scope}${guildId ? `, guild ${guildId}` : ""}):`, err);
 		}