@axiom-lattice/gateway 4.8.3 → 4.9.0

package/dist/index.mjs

@@ -3,6 +3,16 @@ import {
   getFilenameFromPath,
   sendBufferWithRange
 } from "./chunk-EMYRCJOI.mjs";
+import {
+  PathOutsideRootError,
+  ProjectFileValidationError,
+  filesystemRootDirectory,
+  formatFileRefsSection,
+  isBinaryContentType,
+  isPathWithinRoot,
+  resolvePathWithinRoot,
+  saveProjectFile
+} from "./chunk-YKTXW6F6.mjs";
 import {
   PluginToolScopeError,
   invokePluginTool
@@ -14,6 +24,16 @@ import "./chunk-EXPERMZR.mjs";
 import {
   CollectionService
 } from "./chunk-PWHUWFXL.mjs";
+import {
+  A2A_KEY_CHANGED_TOPIC,
+  handleA2AKeyChanged,
+  publishA2AKeyChanged,
+  refreshStoreKeyMap
+} from "./chunk-HYYLYIMH.mjs";
+import {
+  A2AAuthService,
+  parseEnvKeys
+} from "./chunk-GPHOYR3X.mjs";
 import {
   createOrphanRecoveryRuntime,
   createTaskRunLiveness,
@@ -33,16 +53,6 @@ import {
   getQrCode,
   getQrCodeStatus
 } from "./chunk-6CUQGDJI.mjs";
-import {
-  PathOutsideRootError,
-  ProjectFileValidationError,
-  filesystemRootDirectory,
-  formatFileRefsSection,
-  isBinaryContentType,
-  isPathWithinRoot,
-  resolvePathWithinRoot,
-  saveProjectFile
-} from "./chunk-YKTXW6F6.mjs";
 import "./chunk-NFEGQTCC.mjs";
 
 // src/index.ts
@@ -5122,9 +5132,9 @@ var SandboxService = class {
     );
     return rewritten;
   }
-  generateErrorHtml(assistantId, threadId, vmIsolation, errorMessage4) {
-    const encodedError = encodeURIComponent(errorMessage4);
-    return ERROR_HTML.replace("{assistantId}", assistantId).replace("{threadId}", threadId).replace("{vmIsolation}", vmIsolation).replace("{errorMessage}", errorMessage4);
+  generateErrorHtml(assistantId, threadId, vmIsolation, errorMessage6) {
+    const encodedError = encodeURIComponent(errorMessage6);
+    return ERROR_HTML.replace("{assistantId}", assistantId).replace("{threadId}", threadId).replace("{vmIsolation}", vmIsolation).replace("{errorMessage}", errorMessage6);
   }
 };
 var sandboxService = new SandboxService();
@@ -8642,6 +8652,16 @@ async function fetchPluginUiResource(backend, tenantId, pluginType, resource) {
   if (!plugin) throw new Error(`plugin "${pluginType}" not found`);
   const tool = (plugin.meta.tools ?? []).find((t2) => t2.ui?.resource === resource);
   if (!tool?.ui) throw new Error(`plugin "${pluginType}" has no tool declaring ui resource "${resource}"`);
+  const inline = plugin.meta.uiResources?.[resource];
+  if (inline) {
+    return {
+      mimeType: inline.mimeType ?? "text/html;profile=mcp-app",
+      html: inline.html,
+      csp: inline.csp ?? tool.ui.csp,
+      permissions: tool.ui.permissions,
+      prefersBorder: tool.ui.prefersBorder
+    };
+  }
   const html = await backend.catalog.readPluginFile(tenantId, pluginType, resource);
   return {
     mimeType: "text/html",
@@ -10853,9 +10873,9 @@ async function createChannelInstallation(request, reply) {
     };
   } catch (error) {
     console.error("Failed to create channel installation:", error);
-    const errorMessage4 = error instanceof Error ? error.message.toLowerCase() : "";
+    const errorMessage6 = error instanceof Error ? error.message.toLowerCase() : "";
     const errorCode = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
-    if (errorMessage4.includes("duplicate") || errorMessage4.includes("unique constraint") || errorCode === "23505") {
+    if (errorMessage6.includes("duplicate") || errorMessage6.includes("unique constraint") || errorCode === "23505") {
       reply.code(409);
       return {
         success: false,
@@ -11899,6 +11919,7 @@ import {
   createTaskLifecycleService,
   createTrustedAgentMessageDispatcher,
   executionAuthorityRegistry,
+  getReplicaId as getReplicaId6,
   getStoreLattice as getStoreLattice17,
   ManagedTaskStartError,
   modelLatticeManager as modelLatticeManager3,
@@ -12663,6 +12684,12 @@ var ProjectTaskExecutionService = class {
     return room;
   }
   async requireMembership(task, project, room) {
+    if (isRosterExemptProject(project) && this.deps.ensurePublicOwner) {
+      try {
+        await this.deps.ensurePublicOwner({ tenantId: task.tenantId, projectId: task.projectId, assistantId: task.ownerId });
+      } catch {
+      }
+    }
     const found = snapshotBotMembership(await this.deps.bots.findByAssistant(
       task.tenantId,
       task.projectId,
@@ -16141,6 +16168,42 @@ var ModelProviderService = class {
     }
     return registered;
   }
+  /**
+   * Bring this replica's registry in line with one provider's current state.
+   *
+   * @param tenantId Tenant scope (only the default tenant registers).
+   * @param providerId Provider to reconcile; omit to re-hydrate the tenant.
+   * @remarks A missing provider removes every registry key under its
+   * `${providerId}/` prefix; legacy keys registered through `/api/models` are
+   * left untouched.
+   */
+  async reconcileProvider(tenantId, providerId2) {
+    if (!this.shouldRegister(tenantId)) {
+      return;
+    }
+    if (!providerId2) {
+      await this.hydrateRegistry();
+      return;
+    }
+    const provider = await this.deps.providerStore.getProviderById(tenantId, providerId2);
+    if (!provider) {
+      const prefix = `${providerId2}/`;
+      for (const modelKey2 of this.deps.registry.listRegistered(tenantId)) {
+        if (modelKey2.startsWith(prefix)) {
+          this.deps.registry.remove(tenantId, modelKey2);
+        }
+      }
+      return;
+    }
+    const models = await this.deps.providerStore.listModels(tenantId, providerId2);
+    const current = new Set(models.map((model) => toModelKey(providerId2, model.modelId)));
+    for (const modelKey2 of this.deps.registry.listRegistered(tenantId)) {
+      if (modelKey2.startsWith(`${providerId2}/`) && !current.has(modelKey2)) {
+        this.deps.registry.remove(tenantId, modelKey2);
+      }
+    }
+    this.syncRegistry(tenantId, provider, models);
+  }
   /**
    * Create a provider configuration. Does not run discovery.
    */
@@ -16173,7 +16236,9 @@ var ModelProviderService = class {
         id3,
         { ...input, enabled: input.enabled ?? true }
       );
-      return this.toPublicEntry(created, 0);
+      const entry = this.toPublicEntry(created, 0);
+      this.notifyChanged(tenantId, id3);
+      return entry;
     } catch (error) {
       throw this.mapStoreError(error);
     }
@@ -16226,6 +16291,7 @@ var ModelProviderService = class {
       }
       const models = await this.deps.providerStore.listModels(tenantId, id3);
       this.syncRegistry(tenantId, updated, models);
+      this.notifyChanged(tenantId, id3);
       return this.toPublicEntry(updated, models.length);
     } catch (error) {
       throw this.mapStoreError(error);
@@ -16243,6 +16309,7 @@ var ModelProviderService = class {
     for (const model of snapshot) {
       this.deps.registry.remove(tenantId, toModelKey(id3, model.modelId));
     }
+    this.notifyChanged(tenantId, id3);
   }
   /**
    * Discover the provider's models and replace its snapshot.
@@ -16320,6 +16387,7 @@ var ModelProviderService = class {
       }
       registered.push(...this.syncRegistry(tenantId, provider, snapshot));
     }
+    this.notifyChanged(tenantId, id3);
     return {
       discovered,
       registered,
@@ -16436,6 +16504,7 @@ var ModelProviderService = class {
       }
     }
     this.syncRegistry(tenantId, provider, models);
+    this.notifyChanged(tenantId, id3);
     return this.toPublicEntry(provider, models.length);
   }
   syncRegistry(tenantId, provider, models) {
@@ -16458,6 +16527,13 @@ var ModelProviderService = class {
     }
     return registered;
   }
+  /** Best-effort local mutation notification; never affects the operation. */
+  notifyChanged(tenantId, providerId2) {
+    try {
+      this.deps.onChanged?.(tenantId, providerId2);
+    } catch {
+    }
+  }
   /**
    * Enable or disable a single discovered model.
    */
@@ -16479,6 +16555,7 @@ var ModelProviderService = class {
     }
     const models = await this.deps.providerStore.listModels(tenantId, id3);
     this.syncRegistry(tenantId, provider, models);
+    this.notifyChanged(tenantId, id3);
     return this.toPublicEntry(provider, models.length);
   }
   /**
@@ -16800,6 +16877,10 @@ var ModelProviderController = class {
   async hydrateRegistry() {
     return this.service.hydrateRegistry();
   }
+  /** Reconciles one provider (or the tenant) after a foreign change. */
+  async reconcileProvider(tenantId, providerId2) {
+    return this.service.reconcileProvider(tenantId, providerId2);
+  }
   /** GET /api/model-providers */
   async listProviders(request, reply) {
     try {
@@ -16971,6 +17052,27 @@ function registerModelProviderRoutes(app2, controller) {
   );
 }
 
+// src/services/modelProviderSync.ts
+var MODEL_PROVIDER_CHANGED_TOPIC = "model-provider-changed";
+async function publishModelProviderChanged(outbox, owner, tenantId, providerId2) {
+  if (!tenantId) return;
+  try {
+    await outbox.append({
+      topic: MODEL_PROVIDER_CHANGED_TOPIC,
+      payload: { tenantId, providerId: providerId2 },
+      originReplicaId: owner
+    });
+  } catch {
+  }
+}
+async function handleModelProviderChanged(payload, reconcile) {
+  const parsed = payload;
+  const tenantId = parsed?.tenantId;
+  if (typeof tenantId !== "string" || tenantId.length === 0) return;
+  const providerId2 = typeof parsed?.providerId === "string" && parsed.providerId.length > 0 ? parsed.providerId : void 0;
+  await reconcile(tenantId, providerId2);
+}
+
 // src/services/collaboration/ProjectRoomService.ts
 import { randomUUID as randomUUID16 } from "crypto";
 var ProjectRoomService = class {
@@ -17214,19 +17316,149 @@ var ProjectRosterService = class {
    *
    * @param actor Authenticated tenant, user, and project scope.
    * @returns Stored memberships, or — for a public (general) project, which has
-   *   no authored roster — a synthetic active bot per available tenant agent.
-   * @remarks Eligibility is a project property: `kind === "public"` treats every
-   *   available agent as an implicit member; every other kind returns the stored
-   *   roster unchanged. The synthetic records are never persisted.
+   *   no authored roster — stored memberships plus a **virtual** entry per
+   *   remaining available tenant agent.
+   * @remarks Read-only. Eligibility is a project property: `kind === "public"`
+   *   derives the member set dynamically from the tenant's agents (excluding the
+   *   built-in coordinator and personal assistants). Persisted rows (built-in
+   *   coordinator + any agent already interacted with) are returned as-is; every
+   *   other eligible agent is a virtual entry whose id materializes
+   *   just-in-time on the first @mention / assignment / management action
+   *   ({@link ensurePublicProjectBot}). Virtual entries are never persisted.
    */
   async list(actor3) {
     await this.authorize(actor3, "read");
     const project = await this.deps.projects.getProjectById(actor3.tenantId, actor3.projectId);
     if (project?.kind !== "public") return this.deps.membershipStore.list(actor3.tenantId, actor3.projectId);
     const room = await this.deps.roomService.ensureMainRoom(actor3);
+    const persisted = await this.deps.membershipStore.list(actor3.tenantId, actor3.projectId);
+    const known = new Set(persisted.map((item) => item.assistantId));
+    const taken = new Set(persisted.map((item) => item.mentionName));
     const agents = await this.deps.agents.list(actor3.tenantId, actor3.userId);
     const now = /* @__PURE__ */ new Date();
-    return agents.map((agent) => publicProjectBot(project, room.id, agent, now));
+    const entries = [...persisted];
+    for (const agent of agents) {
+      if (agent.assistantId === ROOM_COORDINATOR_KEY) continue;
+      if (agent.ownerUserId !== void 0) continue;
+      if (known.has(agent.assistantId)) continue;
+      const mentionName = uniqueMentionName(agent.name, taken);
+      taken.add(mentionName);
+      entries.push(virtualPublicProjectBot(project, room, agent, mentionName, now));
+    }
+    return entries;
+  }
+  /**
+   * Just-in-time materializes one public-project agent into a real membership,
+   * presence thread, and binding.
+   *
+   * @param actor Authenticated tenant, user, and public-project scope.
+   * @param assistantId Eligible tenant agent to materialize.
+   * @returns The existing membership, or the newly materialized one.
+   * @remarks Serialized under the Project mutation mutex so concurrent touches
+   *   converge on one row; bounded to a single agent (unlike an eager sweep).
+   *   Returns an existing row (any status) unchanged, so an explicitly removed
+   *   agent is not resurrected.
+   */
+  async ensurePublicProjectBot(actor3, assistantId) {
+    await this.authorize(actor3, "read");
+    return this.withLock(actor3, () => this.materializePublicBot(actor3, assistantId));
+  }
+  /**
+   * Resolves a roster membership id to a real membership, materializing a
+   * public-project virtual entry just-in-time.
+   *
+   * @param actor Authenticated tenant, user, and project scope.
+   * @param membershipId A real membership id or a public virtual entry id.
+   * @returns The real membership (with a real presence thread).
+   * @remarks Read-capability path used by roster interactions that need an
+   *   addressable thread (e.g. "View agent work" on a not-yet-touched agent).
+   *   It performs only idempotent writes (materializing/repairing the anchor for
+   *   an entry the caller can already read), scoped to this project.
+   */
+  async ensureBotMembership(actor3, membershipId) {
+    await this.authorize(actor3, "read");
+    return this.withLock(actor3, async () => {
+      const existing = await this.deps.membershipStore.findById(actor3.tenantId, membershipId);
+      if (existing && existing.tenantId === actor3.tenantId && existing.projectId === actor3.projectId) {
+        await this.healBinding(existing);
+        return existing;
+      }
+      const assistantId = publicProjectBotAssistantId(actor3.projectId, membershipId);
+      if (assistantId !== void 0) return this.materializePublicBot(actor3, assistantId);
+      throw new ProjectRosterServiceError("ROSTER_MEMBER_NOT_FOUND", 404, "Roster member not found");
+    });
+  }
+  /**
+   * System (trusted) just-in-time materialization of a public-project agent.
+   *
+   * @param input Exact tenant, project, and eligible shared agent.
+   * @returns The existing or newly materialized membership.
+   * @remarks For trusted gateway paths that are not a human capability check
+   *   (e.g. starting a public-project task owned by this agent, so it has a room
+   *   anchor to post/reply). No human access check is performed; the owner must
+   *   be a shared tenant agent (personal assistants are rejected).
+   */
+  async ensurePublicProjectAgent(input) {
+    const actor3 = { tenantId: input.tenantId, userId: "", projectId: input.projectId };
+    return this.withLock(actor3, () => this.materializePublicBot(actor3, input.assistantId));
+  }
+  /** Unlocked single-agent materialization; callers must hold the Project lock. */
+  async materializePublicBot(actor3, assistantId) {
+    const project = await this.deps.projects.getProjectById(actor3.tenantId, actor3.projectId);
+    if (project?.kind !== "public") throw new ProjectRosterServiceError("ASSISTANT_NOT_FOUND", 404, "Public project not found");
+    const existing = await this.deps.membershipStore.findByAssistant(actor3.tenantId, actor3.projectId, assistantId);
+    if (existing) {
+      this.validateMembership(existing, actor3, { id: existing.roomId, workspaceId: existing.workspaceId }, assistantId, existing.roomThreadId);
+      await this.healBinding(existing);
+      return existing;
+    }
+    const agent = (await this.deps.agents.list(actor3.tenantId, actor3.userId)).find((item) => item.assistantId === assistantId);
+    if (!agent || agent.ownerUserId !== void 0) throw new ProjectRosterServiceError("ASSISTANT_NOT_FOUND", 404, "Agent not found");
+    const room = await this.deps.roomService.ensureMainRoom(actor3);
+    const taken = new Set((await this.deps.membershipStore.list(actor3.tenantId, actor3.projectId)).map((item) => item.mentionName));
+    const mentionName = uniqueMentionName(agent.name, taken);
+    let ids = await this.findSafePresence(actor3, room, assistantId);
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        await this.ensureThread(actor3, room, assistantId, ids.membershipId, ids.threadId);
+        break;
+      } catch (error) {
+        if (!(error instanceof ProjectRosterServiceError) || error.code !== "THREAD_CONFLICT") throw error;
+        ids = { membershipId: this.idFactory(), threadId: this.idFactory() };
+        if (attempt === 2) throw error;
+      }
+    }
+    let result;
+    try {
+      result = await this.deps.membershipStore.save({
+        id: ids.membershipId,
+        tenantId: actor3.tenantId,
+        workspaceId: room.workspaceId,
+        projectId: actor3.projectId,
+        roomId: room.id,
+        assistantId,
+        role: "specialist",
+        title: publicBotTitle(agent.name, assistantId),
+        mentionName,
+        status: "active",
+        roomThreadId: ids.threadId
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "ProjectBotMembershipIdConflictError") {
+        const raced = await this.deps.membershipStore.findByAssistant(actor3.tenantId, actor3.projectId, assistantId);
+        if (raced) return raced;
+      }
+      throw error;
+    }
+    if (result.kind !== "created" && result.kind !== "updated" && result.kind !== "reactivated") {
+      const raced = await this.deps.membershipStore.findByAssistant(actor3.tenantId, actor3.projectId, assistantId);
+      if (raced) return raced;
+      throw new ProjectRosterServiceError("ROSTER_CONFLICT", 409, `Roster ${result.kind.replace("_", " ")}`);
+    }
+    this.validateMembership(result.membership, actor3, room, assistantId, ids.threadId);
+    await this.deps.bindingLifecycle.ensure(result.membership);
+    this.publish(result.membership, result.kind === "created" ? "added" : "updated", `roster:${result.membership.id}:${result.membership.updatedAt.toISOString()}`);
+    return result.membership;
   }
   /** Adds or reactivates a bot and ensures its room-presence thread exists. */
   async add(actor3, input) {
@@ -17255,7 +17487,7 @@ var ProjectRosterService = class {
       try {
         result = await this.deps.membershipStore.save({ id: ids.membershipId, tenantId: actor3.tenantId, workspaceId: room.workspaceId, projectId: actor3.projectId, roomId: room.id, assistantId: input.assistantId, role: input.role, title: normalized.title, ...normalized.responsibility === void 0 ? {} : { responsibility: normalized.responsibility }, mentionName: normalized.mentionName, status: "active", roomThreadId: ids.threadId });
       } catch (error) {
-        if (error instanceof Error && ["ProjectBotMembershipIdConflictError", "DuplicateProjectBotMembershipError"].includes(error.name)) throw new ProjectRosterServiceError("ROSTER_CONFLICT", 409, "Roster membership conflict");
+        if (error instanceof Error && error.name === "ProjectBotMembershipIdConflictError") throw new ProjectRosterServiceError("ROSTER_CONFLICT", 409, "Roster membership conflict");
         throw error;
       }
       if (result.kind !== "created" && result.kind !== "updated" && result.kind !== "reactivated") throw new ProjectRosterServiceError("ROSTER_CONFLICT", 409, `Roster ${result.kind.replace("_", " ")}`);
@@ -17282,8 +17514,9 @@ var ProjectRosterService = class {
   async remove(actor3, input) {
     return this.withLock(actor3, async () => {
       await this.authorize(actor3, "manage");
-      const target = await this.target(actor3, input.membershipId);
-      this.requireCurrent(target, input.expectedUpdatedAt);
+      const { membership: target, materialized } = await this.target(actor3, input.membershipId);
+      const expected = materialized ? target.updatedAt : input.expectedUpdatedAt;
+      this.requireCurrent(target, expected);
       if (target.role === "coordinator") throw coordinatorProtected("The built-in room coordinator cannot be removed");
       for (const status of activeTaskStatuses) {
         const tasks = await this.deps.taskStore.list({ tenantId: actor3.tenantId, projectId: actor3.projectId, ownerType: "agent", ownerId: target.assistantId, status, limit: 1 });
@@ -17292,7 +17525,7 @@ var ProjectRosterService = class {
       await this.authorize(actor3, "manage");
       await this.deps.bindingLifecycle.remove(target);
       try {
-        const removed = await this.applyUpdate(actor3, target, { status: "removed" }, input.expectedUpdatedAt);
+        const removed = await this.applyUpdate(actor3, target, { status: "removed" }, expected);
         this.publish(removed, "removed", `roster:${removed.id}:${removed.updatedAt.toISOString()}`);
         return removed;
       } catch (error) {
@@ -17306,11 +17539,12 @@ var ProjectRosterService = class {
   async mutate(actor3, id3, expected, patch, lifecycle) {
     return this.withLock(actor3, async () => {
       await this.authorize(actor3, "manage");
-      const target = await this.target(actor3, id3);
-      this.requireCurrent(target, expected);
+      const { membership: target, materialized } = await this.target(actor3, id3);
+      const expectedAt = materialized ? target.updatedAt : expected;
+      this.requireCurrent(target, expectedAt);
       this.assertCoordinatorPolicy(target, patch, lifecycle);
       await this.authorize(actor3, "manage");
-      const updated = await this.applyUpdate(actor3, target, patch, expected);
+      const updated = await this.applyUpdate(actor3, target, patch, expectedAt);
       if (lifecycle === "pause") await this.deps.bindingLifecycle.pause(updated);
       else if (lifecycle === "resume") await this.deps.bindingLifecycle.resume(updated);
       else await this.applyLifecycle(updated);
@@ -17351,12 +17585,20 @@ var ProjectRosterService = class {
     }
     await this.deps.bindingLifecycle.ensure(membership);
   }
+  /** Best-effort, idempotent binding repair for an already-materialized active member. */
+  async healBinding(membership) {
+    if (membership.status !== "active") return;
+    try {
+      await this.deps.bindingLifecycle.ensure(membership);
+    } catch {
+    }
+  }
   async applyUpdate(actor3, target, patch, expectedUpdatedAt2) {
     let result;
     try {
       result = await this.deps.membershipStore.update({ tenantId: actor3.tenantId, id: target.id, patch, expectedUpdatedAt: expectedUpdatedAt2 });
     } catch (error) {
-      if (error instanceof Error && ["ProjectBotMembershipIdConflictError", "DuplicateProjectBotMembershipError"].includes(error.name)) throw new ProjectRosterServiceError("ROSTER_CONFLICT", 409, "Roster membership conflict");
+      if (error instanceof Error && error.name === "ProjectBotMembershipIdConflictError") throw new ProjectRosterServiceError("ROSTER_CONFLICT", 409, "Roster membership conflict");
       throw error;
     }
     if (result.kind === "updated") {
@@ -17371,7 +17613,18 @@ var ProjectRosterService = class {
     await this.deps.accessService.requireProjectAccess({ ...actor3, capability: capability2 });
   }
   async target(actor3, id3) {
-    const target = await this.deps.membershipStore.findById(actor3.tenantId, id3);
+    let target = await this.deps.membershipStore.findById(actor3.tenantId, id3);
+    let materialized = false;
+    if (!target || target.tenantId !== actor3.tenantId || target.projectId !== actor3.projectId) {
+      const assistantId = publicProjectBotAssistantId(actor3.projectId, id3);
+      if (assistantId !== void 0) {
+        const project = await this.deps.projects.getProjectById(actor3.tenantId, actor3.projectId);
+        if (project?.kind === "public") {
+          target = await this.materializePublicBot(actor3, assistantId);
+          materialized = true;
+        }
+      }
+    }
     if (!target || target.tenantId !== actor3.tenantId || target.projectId !== actor3.projectId) throw new ProjectRosterServiceError("ROSTER_MEMBER_NOT_FOUND", 404, "Roster member not found");
     const room = await this.deps.roomService.ensureMainRoom(actor3);
     const assistant = await this.deps.assistantStore.getAssistantById(actor3.tenantId, target.assistantId);
@@ -17381,7 +17634,7 @@ var ProjectRosterService = class {
     const thread = await this.deps.threadStore.getThreadById(actor3.tenantId, target.roomThreadId);
     if (!thread) throw new ProjectRosterServiceError("THREAD_CONFLICT", 409, "Presence thread not found");
     this.validateThread(thread, actor3.tenantId, this.expectedMetadata(room, actor3, target.id, target.assistantId), target.roomThreadId);
-    return target;
+    return { membership: target, materialized };
   }
   requireCurrent(target, expected) {
     if (!activeStatuses.includes(target.status)) throw new ProjectRosterServiceError("ROSTER_MEMBER_NOT_FOUND", 404, "Roster member not found");
@@ -17452,22 +17705,50 @@ var ProjectRosterService = class {
     );
   }
 };
-function publicProjectBot(project, roomId, agent, now) {
-  const id3 = `public-project-bot:${project.id}:${agent.assistantId}`;
+function uniqueMentionName(name, taken) {
+  let base = (name || "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!/^[a-z]/.test(base)) base = `agent-${base}`.replace(/^agent-$/, "agent");
+  base = base.slice(0, 32);
+  if (base.length < 2) base = "agent";
+  let candidate = base;
+  let suffix = 2;
+  while (taken.has(candidate)) {
+    const tail = `-${suffix}`;
+    candidate = `${base.slice(0, 32 - tail.length)}${tail}`;
+    suffix += 1;
+  }
+  return candidate;
+}
+function publicBotTitle(name, fallbackId) {
+  const trimmed = (name || "").trim();
+  if (trimmed.length === 0) return fallbackId.slice(0, 80);
+  return trimmed.slice(0, 80);
+}
+var PUBLIC_PROJECT_BOT_PREFIX = "public-project-bot:";
+function publicProjectBotId(projectId, assistantId) {
+  return `${PUBLIC_PROJECT_BOT_PREFIX}${projectId}:${assistantId}`;
+}
+function publicProjectBotAssistantId(projectId, membershipId) {
+  const prefix = `${PUBLIC_PROJECT_BOT_PREFIX}${projectId}:`;
+  return membershipId.startsWith(prefix) && membershipId.length > prefix.length ? membershipId.slice(prefix.length) : void 0;
+}
+function virtualPublicProjectBot(project, room, agent, mentionName, now) {
+  const id3 = publicProjectBotId(project.id, agent.assistantId);
   return {
     id: id3,
     tenantId: project.tenantId,
     workspaceId: project.workspaceId,
     projectId: project.id,
-    roomId,
+    roomId: room.id,
     assistantId: agent.assistantId,
     role: "specialist",
-    title: agent.name,
-    mentionName: agent.name,
+    title: publicBotTitle(agent.name, agent.assistantId),
+    mentionName,
     status: "active",
     roomThreadId: id3,
     joinedAt: now,
-    updatedAt: now
+    updatedAt: now,
+    provisional: true
   };
 }
 
@@ -17588,7 +17869,8 @@ var RoomMessageService = class {
     const room = await this.room(actor3, access.project);
     return this.persistNormalizedHumanMessage(actor3, snapshot, room);
   }
-  async persistNormalizedHumanMessage(actor3, snapshot, room) {
+  async persistNormalizedHumanMessage(actor3, input, room) {
+    const snapshot = await this.resolvePublicMentions(actor3, input);
     for (const membershipId of snapshot.botIds) await this.validateMentionIdentity(actor3, room, membershipId);
     let reply = null;
     if (snapshot.replyToMessageId !== void 0) {
@@ -17615,6 +17897,38 @@ var RoomMessageService = class {
     }
     return { message: validated, replayed };
   }
+  /**
+   * Rewrites public-project virtual mention ids to their real membership ids,
+   * materializing each mentioned agent just-in-time.
+   *
+   * @param actor Authenticated sender.
+   * @param snapshot Normalized message with possibly-virtual bot mention ids.
+   * @returns The snapshot unchanged, or one whose bot mentions carry real ids.
+   */
+  async resolvePublicMentions(actor3, snapshot) {
+    const resolver = this.deps.resolveMentionTarget;
+    if (!resolver || snapshot.botIds.length === 0) return snapshot;
+    let changed = false;
+    const seen = /* @__PURE__ */ new Set();
+    const mentions = [];
+    for (const mention of snapshot.mentions) {
+      if (mention.type !== "bot") {
+        mentions.push(mention);
+        continue;
+      }
+      const real = await resolver(actor3, actor3.projectId, mention.membershipId);
+      if (real !== mention.membershipId) changed = true;
+      if (seen.has(real)) {
+        changed = true;
+        continue;
+      }
+      seen.add(real);
+      mentions.push({ type: "bot", membershipId: real });
+    }
+    if (!changed) return snapshot;
+    const botIds = mentions.filter((mention) => mention.type === "bot").map((mention) => mention.membershipId);
+    return { ...snapshot, mentions, botIds };
+  }
   /**
    * Persists a human message, then resolves and dispatches its current targets.
    * Idempotent outcomes are single-flight and retained only in this service process; a
@@ -17853,6 +18167,12 @@ var RoomInterruptService = class {
       throw new RoomInterruptServiceError("ROOM_INTERRUPT_NOT_PENDING", 409, "Room interrupt is no longer pending");
     }
     const inputMessageId = this.idFactory();
+    let rosterExempt = false;
+    try {
+      rosterExempt = isRosterExemptProject(await this.deps.projects.getProjectById(membership.tenantId, membership.projectId));
+    } catch {
+      rosterExempt = false;
+    }
     await this.deps.dispatcher.dispatch(
       {
         tenant_id: scope.tenantId,
@@ -17877,7 +18197,8 @@ var RoomInterruptService = class {
             role: membership.role,
             title: membership.title,
             source: "project_room",
-            ...membership.responsibility === void 0 ? {} : { responsibility: membership.responsibility }
+            ...membership.responsibility === void 0 ? {} : { responsibility: membership.responsibility },
+            ...rosterExempt ? { rosterExempt: true } : {}
           }
         }
       }
@@ -17902,7 +18223,7 @@ var createRoomMessageSchema = z10.object({
   mentions: z10.array(z10.union([
     z10.object({ type: z10.literal("team") }).strict(),
     z10.object({ type: z10.literal("bot"), membershipId: id2 }).strict()
-  ])).optional(),
+  ])).max(50).optional(),
   replyToMessageId: id2.optional()
 }).strict();
 var addProjectMemberSchema = z10.object({ userId: id2, role: z10.enum(["owner", "admin", "member", "viewer"]) }).strict();
@@ -18061,6 +18382,12 @@ function registerProjectRosterRoutes(app2, deps) {
     const body = mutationExpectedUpdatedAtSchema.parse(request.body);
     return { data: await method.call(deps.service, getActor(request, p.projectId), { membershipId: p.membershipId, expectedUpdatedAt: body.expectedUpdatedAt }) };
   }));
+  app2.post("/api/projects/:projectId/bots/:membershipId/ensure", async (request, reply) => execute(reply, async () => {
+    const p = membershipParamsSchema.parse(request.params);
+    emptyObjectSchema.parse(request.body ?? {});
+    emptyObjectSchema.parse(request.query ?? {});
+    return { data: await deps.service.ensureBotMembership(getActor(request, p.projectId), p.membershipId) };
+  }));
   app2.delete("/api/projects/:projectId/bots/:membershipId", async (request, reply) => execute(reply, async () => {
     const p = membershipParamsSchema.parse(request.params);
     const q = mutationExpectedUpdatedAtSchema.parse(request.query);
@@ -18673,7 +19000,11 @@ function registerCoSpaceRoutes(app2, deps) {
 
 // src/routes/push-notifications.ts
 import { ZodError as ZodError7, z as z11 } from "zod";
-var subscriptionSchema = z11.object({ endpoint: z11.string().min(1), keys: z11.object({ p256dh: z11.string().min(1), auth: z11.string().min(1) }).strict() }).strict();
+var subscriptionSchema = z11.object({
+  endpoint: z11.string().min(1),
+  keys: z11.object({ p256dh: z11.string().min(1), auth: z11.string().min(1) }).strict(),
+  expirationTime: z11.number().nullable().optional()
+}).strict();
 var deleteSchema = z11.object({ endpoint: z11.string().min(1) }).strict();
 function actor2(request) {
   const user = request.user;
@@ -18964,6 +19295,12 @@ var RoomDispatchService = class {
     if (!source) throw new Error("Invalid project room dispatch message");
     const anchorMessageId = source.sourceId ?? source.id;
     const entries = await this.deps.resolver.resolve(source);
+    let rosterExempt = false;
+    try {
+      rosterExempt = isRosterExemptProject(await this.deps.projects.getProjectById(source.tenantId, source.projectId));
+    } catch {
+      rosterExempt = false;
+    }
     const results = [];
     for (const entry of entries) {
       if (entry.kind === "failure") {
@@ -19003,7 +19340,8 @@ var RoomDispatchService = class {
               role: membership.role,
               title: membership.title,
               source: "project_room",
-              ...membership.responsibility === void 0 ? {} : { responsibility: membership.responsibility }
+              ...membership.responsibility === void 0 ? {} : { responsibility: membership.responsibility },
+              ...rosterExempt ? { rosterExempt: true } : {}
             } }
           }
         });
@@ -21533,7 +21871,6 @@ function isSubscriptionGone(error) {
   const statusCode = error.statusCode;
   return statusCode === 404 || statusCode === 410;
 }
-var MAX_BODY = 140;
 var RoomPushNotifier = class {
   /** Creates a notifier from explicitly injected collaborators. */
   constructor(deps) {
@@ -21557,7 +21894,7 @@ var RoomPushNotifier = class {
     const title = await this.deps.resolveTitle?.(message) ?? message.roomId;
     const payload = {
       title,
-      body: message.content.text.slice(0, MAX_BODY),
+      body: "notification",
       tag: message.projectId,
       url: this.deps.buildUrl?.(message) ?? "/"
     };
@@ -22367,6 +22704,14 @@ async function transferGovernedDispatchOwner(task, options, deps) {
     return result.task;
   });
 }
+function broadcastModelProviderChanged(tenantId, providerId2) {
+  if (!tenantId) return;
+  try {
+    const outbox = getStoreLattice17("default", "outbox").store;
+    void publishModelProviderChanged(outbox, getReplicaId6(), tenantId, providerId2);
+  } catch {
+  }
+}
 var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
   const webAppStore = getStoreLattice17("default", "agentWebApp").store;
   const assistantStore = getStoreLattice17("default", "assistant").store;
@@ -22482,7 +22827,8 @@ var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
       });
       return String(await agent.getRunStatus());
     },
-    dispatcher: createTrustedAgentMessageDispatcher((scope) => agentInstanceManager6.getAgent(scope))
+    dispatcher: createTrustedAgentMessageDispatcher((scope) => agentInstanceManager6.getAgent(scope)),
+    projects: projectStore
   });
   const membershipService = new ProjectMembershipService({ membershipStore: projectMembershipStore, userTenantLinkStore, accessService, projectMutationMutex: projectMutationMutex2, roomStore: projectRoomStore, realtime, onRealtimeFailure: realtime && channelDeps?.warn ? ({ code, membershipId }) => channelDeps.warn?.("project-room:membership-realtime-failed", { code, membershipId }) : void 0 });
   const rosterService = new ProjectRosterService({
@@ -22490,7 +22836,7 @@ var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
     roomService,
     membershipStore: projectBotMembershipStore,
     projects: projectStore,
-    agents: { list: async (tenantId, userId) => (await collectTenantAssistants(tenantId, userId)).map((assistant) => ({ assistantId: assistant.id, name: assistant.name })) },
+    agents: { list: async (tenantId, userId) => (await collectTenantAssistants(tenantId, userId)).map((assistant) => ({ assistantId: assistant.id, name: assistant.name, ...assistant.ownerUserId === void 0 ? {} : { ownerUserId: assistant.ownerUserId } })) },
     threadStore,
     assistantStore,
     taskStore,
@@ -22504,7 +22850,8 @@ var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
     resolver: new RoomTargetResolver({ botStore: projectBotMembershipStore }),
     installation,
     bindings: bindingLifecycle,
-    router: channelDeps.router
+    router: channelDeps.router,
+    projects: projectStore
   }) : new UnavailableRoomDispatcher();
   const coordinatorWakeNotifier = dispatcher instanceof RoomDispatchService ? new CoordinatorWakeNotifier({
     tasks: taskStore,
@@ -22524,6 +22871,12 @@ var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
     botStore: projectBotMembershipStore,
     messageStore: projectRoomMessageStore,
     dispatcher,
+    resolveMentionTarget: async (actor3, projectId, membershipId) => {
+      const assistantId = publicProjectBotAssistantId(projectId, membershipId);
+      if (assistantId === void 0) return membershipId;
+      const membership = await rosterService.ensurePublicProjectBot({ tenantId: actor3.tenantId, userId: actor3.userId, projectId }, assistantId);
+      return membership.id;
+    },
     realtime,
     onRealtimeFailure: realtime && channelDeps?.warn ? (event) => channelDeps.warn?.("project-room:message-realtime-callback-failed", {
       code: event.code,
@@ -22540,6 +22893,7 @@ var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
     threadStore,
     realtime,
     log: options.projectTaskLog,
+    ensurePublicOwner: (scope) => rosterService.ensurePublicProjectAgent(scope),
     ...coordinatorWakeNotifier === void 0 ? {} : { coordinatorWake: coordinatorWakeNotifier }
   }) : { reason: void 0 };
   const projectTaskComposition = "composition" in projectTaskRuntime ? projectTaskRuntime.composition : void 0;
@@ -22667,7 +23021,8 @@ var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
       has: (tenantId, modelKey2) => modelLatticeManager3.hasLatticeWithTenant(tenantId, modelKey2),
       remove: (tenantId, modelKey2) => modelLatticeManager3.removeLatticeWithTenant(tenantId, modelKey2),
       listRegistered: (tenantId) => modelLatticeManager3.getLatticeKeysByTenant(tenantId)
-    }
+    },
+    onChanged: (tenantId, providerId2) => broadcastModelProviderChanged(tenantId, providerId2)
   }, { authRequired: process.env.AUTH_REQUIRED === "true" });
   registerModelProviderRoutes(app2, modelProviderController);
   void modelProviderController.hydrateRegistry().catch(() => void 0);
@@ -23126,7 +23481,8 @@ var registerLatticeRoutes = (app2, channelDeps, options = {}) => {
   return {
     ...projectTaskComposition ? { projectTaskRuntime: projectTaskComposition.lease } : {},
     ...projectTaskUnavailableReason ? { projectTaskUnavailableReason } : {},
-    ...projectRoomRealtimeRuntime ? { projectRoomRealtimeRuntime } : {}
+    ...projectRoomRealtimeRuntime ? { projectRoomRealtimeRuntime } : {},
+    modelProviderController
   };
 };
 function tryCreateProjectTaskRuntime(input) {
@@ -23197,20 +23553,24 @@ function createRuntime(input, stores, log2) {
     workspace_id: task.workspaceId,
     project_id: task.projectId
   });
-  const execution = new ProjectTaskExecutionService({
-    tasks: input.taskStore,
-    projects: input.projectStore,
-    rooms: input.projectRoomStore,
-    bots: input.projectBotMembershipStore,
-    threads,
-    lifecycle,
-    dispatcher: createTrustedAgentMessageDispatcher((scope) => agentInstanceManager6.getAgent(scope)),
-    queue: stores.queue,
-    agentFor
-  }, {
-    settlementTimeoutMs: PROJECT_TASK_SETTLEMENT_TIMEOUT_MS,
-    lifecycleSettlementTimeoutMs: PROJECT_TASK_LIFECYCLE_SETTLEMENT_TIMEOUT_MS
-  });
+  const execution = new ProjectTaskExecutionService(
+    {
+      tasks: input.taskStore,
+      projects: input.projectStore,
+      rooms: input.projectRoomStore,
+      bots: input.projectBotMembershipStore,
+      threads,
+      lifecycle,
+      dispatcher: createTrustedAgentMessageDispatcher((scope) => agentInstanceManager6.getAgent(scope)),
+      queue: stores.queue,
+      agentFor,
+      ...input.ensurePublicOwner === void 0 ? {} : { ensurePublicOwner: input.ensurePublicOwner }
+    },
+    {
+      settlementTimeoutMs: PROJECT_TASK_SETTLEMENT_TIMEOUT_MS,
+      lifecycleSettlementTimeoutMs: PROJECT_TASK_LIFECYCLE_SETTLEMENT_TIMEOUT_MS
+    }
+  );
   const observer = new ProjectTaskObserver({
     tasks: input.taskStore,
     workItems: input.taskWorkItemStore,
@@ -25088,6 +25448,40 @@ var _AgentTaskConsumer = class _AgentTaskConsumer {
 _AgentTaskConsumer.agent_run_endpoint = "http://localhost:4001/api/runs";
 var AgentTaskConsumer = _AgentTaskConsumer;
 
+// src/services/gracefulShutdown.ts
+function createGracefulShutdown(options) {
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const exit = options.exit ?? ((code) => process.exit(code));
+  let started = false;
+  let exited = false;
+  const doExit = (code) => {
+    if (exited) return;
+    exited = true;
+    exit(code);
+  };
+  return async (signal) => {
+    if (started) return;
+    started = true;
+    options.log?.info(`Received ${signal}; shutting down gracefully`, { signal });
+    const timer = setTimeout(() => {
+      options.log?.warn("Graceful shutdown timed out; forcing exit", { signal, timeoutMs });
+      doExit(1);
+    }, timeoutMs);
+    timer.unref?.();
+    for (const step of options.steps) {
+      try {
+        await step();
+      } catch (error) {
+        options.log?.warn("Graceful shutdown step failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    clearTimeout(timer);
+    doExit(0);
+  };
+}
+
 // src/index.ts
 import {
   registerLoggerLattice,
@@ -25103,7 +25497,7 @@ import {
   createTrustedAgentMessageDispatcher as createTrustedAgentMessageDispatcher2,
   runAsLeader,
   configureCoordinationLeaseStore,
-  getReplicaId as getReplicaId6,
+  getReplicaId as getReplicaId7,
   taskLifecycleNotifier as taskLifecycleNotifier3,
   projectTaskAdmissionNotifier as projectTaskAdmissionNotifier2,
   scheduleLatticeManager as scheduleLatticeManager2,
@@ -25112,7 +25506,9 @@ import {
   agentLatticeManager as agentLatticeManager5,
   configurePluginCatalogSync,
   PLUGIN_CATALOG_CHANGED_TOPIC,
-  getSandboxPluginCatalog as getSandboxPluginCatalog3
+  getSandboxPluginCatalog as getSandboxPluginCatalog3,
+  getSandBoxManager as getSandBoxManager4,
+  installPluginHost
 } from "@axiom-lattice/core";
 
 // src/channels/ChannelInfrastructure.ts
@@ -25220,7 +25616,7 @@ function validateRoomTrustedDispatch(message, options, binding, agentId) {
     "inputMessageId",
     "role",
     "title"
-  ], ["responsibility", "source"]);
+  ], ["responsibility", "source", "rosterExempt"]);
   if (!binding || !targetEnvelope || !target || !context || !authority || typeof authority.expectedRoomThreadId !== "string" || authority.expectedRoomThreadId.length === 0 || trusted?.executionMode !== "followup") return false;
   const expectedSender = `room:${context.roomId}:membership:${context.membershipId}`;
   return targetEnvelope.adapterChannel === "room" && targetEnvelope.channelInstallationId === message.channelInstallationId && target.sourceRoomMessageId === context.sourceRoomMessageId && target.targetMembershipId === context.membershipId && target.inputMessageId === context.inputMessageId && message.tenantId === context.tenantId && message.sender.id === expectedSender && message.conversation?.id === context.roomId && message.conversation?.type === "group" && binding.tenantId === context.tenantId && binding.channel === "room" && binding.channelInstallationId === message.channelInstallationId && binding.senderId === expectedSender && binding.agentId === context.assistantId && binding.workspaceId === context.workspaceId && binding.projectId === context.projectId && binding.threadId === authority.expectedRoomThreadId && binding.threadMode === "fixed" && agentId === context.assistantId;
@@ -25781,9 +26177,942 @@ async function prepareProjectTaskRuntime(runtime, log2) {
   }
 }
 
+// src/services/plugins/PluginDeploymentRuntimeStartup.ts
+import { setPluginDeploymentService } from "@axiom-lattice/core";
+
+// src/services/plugins/PluginDeploymentService.ts
+import { randomUUID as randomUUID28 } from "crypto";
+import {
+  PLUGIN_HOST_DIR,
+  PluginDeploymentRuntimeRegistry
+} from "@axiom-lattice/core";
+
+// src/services/plugins/pluginDeploymentNaming.ts
+import { createHash as createHash10 } from "crypto";
+var PLUGIN_GUEST_PORT = 8080;
+var SANDBOX_NAME_HASH_LENGTH = 16;
+function pluginSandboxName(tenantId, pluginType) {
+  if (!tenantId || typeof tenantId !== "string") {
+    throw new Error("pluginSandboxName: tenantId must be a non-empty string");
+  }
+  if (!pluginType || typeof pluginType !== "string") {
+    throw new Error("pluginSandboxName: pluginType must be a non-empty string");
+  }
+  const hash = createHash10("sha256").update(`${tenantId}\0${pluginType}`).digest("hex").slice(0, SANDBOX_NAME_HASH_LENGTH);
+  return `plugin-${hash}`;
+}
+
+// src/services/plugins/PluginDeploymentService.ts
+var PLUGIN_HOST_SERVER_PATH = `${PLUGIN_HOST_DIR}/server.js`;
+var DEFAULT_PLUGIN_IDLE_TIMEOUT_MS = 15 * 60 * 1e3;
+var DEFAULT_PLUGIN_HEALTH_TIMEOUT_MS = 3e4;
+var DEFAULT_PLUGIN_HEALTH_POLL_INTERVAL_MS = 500;
+var DEFAULT_PLUGIN_HEALTH_PROBE_TIMEOUT_MS = 5e3;
+var PLUGIN_DEPLOYMENT_LEASE_KEY = "plugin-deployment:reconcile";
+var PLUGIN_DEPLOYMENT_LEASE_TTL_MS = 6e4;
+var PLUGIN_TYPE_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var PluginDeploymentError = class extends Error {
+  /**
+   * @param code - Machine-readable failure code.
+   * @param message - Human-readable description.
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = "PluginDeploymentError";
+    this.code = code;
+  }
+};
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function buildBootstrapEntrypoint(pluginType) {
+  return [
+    "sh",
+    "-c",
+    `while [ ! -f ${PLUGIN_HOST_SERVER_PATH} ]; do sleep 0.2; done; exec node ${PLUGIN_HOST_SERVER_PATH} --type ${pluginType} --port ${PLUGIN_GUEST_PORT}`
+  ];
+}
+var PluginDeploymentService = class {
+  /**
+   * @param deps - Injected store, sandbox manager, catalog, installer, lease, and seams.
+   */
+  constructor(deps) {
+    this.store = deps.store;
+    this.sandboxManager = deps.sandboxManager;
+    this.catalog = deps.catalog;
+    this.installPluginHost = deps.installPluginHost;
+    this.lease = deps.lease;
+    this.registry = deps.registry ?? new PluginDeploymentRuntimeRegistry({ now: deps.clock ?? Date.now });
+    this.now = deps.clock ?? Date.now;
+    this.logger = deps.logger ?? { info: () => void 0 };
+    this.limits = deps.limits ?? {};
+    this.serviceBaseUrl = (deps.serviceBaseUrl ?? process.env.MICROSANDBOX_SERVICE_URL ?? "").replace(
+      /\/$/,
+      ""
+    );
+    this.serviceKey = deps.serviceKey;
+    this.fetchImpl = deps.fetchImpl ?? fetch;
+    this.sleep = deps.sleep ?? ((ms) => new Promise((resolve3) => setTimeout(resolve3, ms)));
+    this.defaultMode = deps.defaultMode ?? "onDemand";
+    this.defaultIdleTimeoutMs = deps.defaultIdleTimeoutMs ?? DEFAULT_PLUGIN_IDLE_TIMEOUT_MS;
+    this.providerName = deps.providerName ?? "default";
+    this.image = deps.image;
+    this.healthTimeoutMs = deps.healthTimeoutMs ?? DEFAULT_PLUGIN_HEALTH_TIMEOUT_MS;
+    this.healthPollIntervalMs = deps.healthPollIntervalMs ?? DEFAULT_PLUGIN_HEALTH_POLL_INTERVAL_MS;
+    this.healthProbeTimeoutMs = deps.healthProbeTimeoutMs ?? DEFAULT_PLUGIN_HEALTH_PROBE_TIMEOUT_MS;
+    this.replicaId = deps.replicaId ?? String(process.pid);
+    this.listAllDeployments = deps.listAllDeployments;
+  }
+  /**
+   * Provision a resident sandbox for a published tenant plugin.
+   *
+   * Validates the plugin against the tenant catalog, enforces limits, resolves a
+   * deterministic sandbox with the bootstrap entrypoint and exposed guest port,
+   * installs the host server, waits for `/health`, and upserts a `running`
+   * {@link PluginDeployment}. Re-deploying an existing deployment reuses the same
+   * sandbox name and record (idempotent).
+   *
+   * @param tenantId - Tenant that owns the plugin.
+   * @param pluginType - Plugin type (directory key).
+   * @param options - Lifecycle mode and overrides.
+   * @returns The stored deployment record.
+   * @throws PluginDeploymentError with `PLUGIN_NOT_FOUND`, `INVALID_PLUGIN_TYPE`,
+   *   `LIMIT_EXCEEDED`, `BACKEND_UNSUPPORTED`, `SANDBOX_CREATE_FAILED`, or
+   *   `HEALTH_TIMEOUT`.
+   */
+  async deploy(tenantId, pluginType, options = {}) {
+    const snapshot = await this.catalog.ensureLoaded(tenantId);
+    const manifest = snapshot.manifests[pluginType];
+    if (!manifest) {
+      throw new PluginDeploymentError(
+        "PLUGIN_NOT_FOUND",
+        `plugin "${pluginType}" is not published for tenant "${tenantId}"`
+      );
+    }
+    if (!PLUGIN_TYPE_RE.test(pluginType)) {
+      throw new PluginDeploymentError(
+        "INVALID_PLUGIN_TYPE",
+        `plugin type "${pluginType}" is not a valid kebab-case identifier`
+      );
+    }
+    const existing = await this.store.get(tenantId, pluginType);
+    if (!existing) {
+      await this.assertWithinLimits(tenantId);
+    }
+    const mode = options.mode ?? existing?.mode ?? this.defaultMode;
+    const idleTimeoutMs = options.idleTimeoutMs ?? existing?.idleTimeoutMs ?? this.defaultIdleTimeoutMs;
+    const name = pluginSandboxName(tenantId, pluginType);
+    const config = this.buildSandboxConfig(
+      tenantId,
+      pluginType,
+      mode,
+      idleTimeoutMs,
+      options.image ?? this.image
+    );
+    let sandbox;
+    try {
+      sandbox = await this.sandboxManager.createSandbox(name, config);
+      await this.installPluginHost(sandbox);
+    } catch (error) {
+      throw new PluginDeploymentError(
+        "SANDBOX_CREATE_FAILED",
+        `failed to provision sandbox "${name}": ${errorMessage4(error)}`
+      );
+    }
+    const endpoint = await this.resolveEndpoint(sandbox);
+    const health = await this.waitForHealth(endpoint);
+    if (!health.ok) {
+      const failedAt = this.nowIso();
+      await this.store.upsert(
+        this.buildRecord({
+          id: existing?.id ?? randomUUID28(),
+          tenantId,
+          pluginType,
+          pluginVersion: manifest.version,
+          mode,
+          status: "failed",
+          sandboxName: name,
+          endpoint,
+          idleTimeoutMs,
+          provider: options.provider ?? this.providerName,
+          image: options.image ?? this.image,
+          lastHealthAt: failedAt,
+          lastError: health.error,
+          createdAt: existing?.createdAt
+        })
+      );
+      throw new PluginDeploymentError(
+        "HEALTH_TIMEOUT",
+        `resident host for plugin "${pluginType}" did not become healthy: ${health.error ?? "unknown"}`
+      );
+    }
+    const record = this.buildRecord({
+      id: existing?.id ?? randomUUID28(),
+      tenantId,
+      pluginType,
+      pluginVersion: manifest.version,
+      mode,
+      status: "running",
+      sandboxName: name,
+      endpoint,
+      idleTimeoutMs,
+      provider: options.provider ?? this.providerName,
+      image: options.image ?? this.image,
+      lastHealthAt: this.nowIso(),
+      createdAt: existing?.createdAt
+    });
+    const stored = await this.store.upsert(record);
+    const key = this.registryKey(tenantId, pluginType);
+    this.registry.setEndpoint(key, endpoint);
+    this.registry.markHealthy(key);
+    this.logger.info(
+      { event: "plugin.deployment.deployed", tenantId, pluginType, mode, endpoint },
+      "plugin deployment running"
+    );
+    return stored;
+  }
+  /**
+   * Delete a deployment's sandbox and record.
+   *
+   * Sandbox deletion is best-effort: a provider failure is logged but does not
+   * prevent the record from being removed.
+   *
+   * @param tenantId - Tenant that owns the plugin.
+   * @param pluginType - Plugin type.
+   * @returns Whether a deployment record was removed.
+   */
+  async undeploy(tenantId, pluginType) {
+    const name = pluginSandboxName(tenantId, pluginType);
+    try {
+      await this.sandboxManager.deleteSandbox(name);
+    } catch (error) {
+      this.logger.warn?.(
+        { event: "plugin.deployment.undeploy.sandbox_failed", tenantId, pluginType, error: errorMessage4(error) },
+        "best-effort sandbox delete failed"
+      );
+    }
+    const undeployed = await this.store.delete(tenantId, pluginType);
+    this.registry.clear(this.registryKey(tenantId, pluginType));
+    this.logger.info(
+      { event: "plugin.deployment.undeployed", tenantId, pluginType, undeployed },
+      "plugin deployment removed"
+    );
+    return { undeployed };
+  }
+  /**
+   * Read the durable deployment status and refresh it with a live `/health`.
+   *
+   * When a `running` record exists, a single `/health` probe updates
+   * `lastHealthAt`/`lastError`; the probe never throws.
+   *
+   * @param tenantId - Tenant that owns the plugin.
+   * @param pluginType - Plugin type.
+   * @returns The status view (with `status: "absent"` when no record exists).
+   */
+  async status(tenantId, pluginType) {
+    const record = await this.store.get(tenantId, pluginType);
+    if (!record) {
+      return { status: "absent" };
+    }
+    let lastHealthAt = record.lastHealthAt;
+    let lastError = record.lastError;
+    if (record.status === "running" && record.endpoint) {
+      const health = await this.probeHealth(record.endpoint);
+      const key = this.registryKey(tenantId, pluginType);
+      if (health.ok) {
+        this.registry.markHealthy(key);
+        lastHealthAt = this.nowIso();
+        lastError = void 0;
+      } else {
+        this.registry.markUnhealthy(key, health.error ?? "health probe failed");
+        lastHealthAt = this.nowIso();
+        lastError = health.error ?? "health probe failed";
+      }
+      await this.store.updateStatus(tenantId, pluginType, { lastHealthAt, lastError });
+    }
+    return {
+      status: record.status,
+      endpoint: record.endpoint,
+      mode: record.mode,
+      lastHealthAt,
+      ...lastError === void 0 ? {} : { lastError },
+      sandboxName: record.sandboxName,
+      port: record.port
+    };
+  }
+  /**
+   * List every resident deployment for a tenant.
+   *
+   * Reads the durable store directly (no `/health` probe) and maps each record
+   * to the minimal view the read-only `manage_plugin deployments` MCP App needs.
+   *
+   * @param tenantId - Tenant whose deployments are listed.
+   * @returns One minimal entry per stored deployment.
+   */
+  async list(tenantId) {
+    const records = await this.store.listByTenant(tenantId);
+    return records.map((record) => ({
+      pluginType: record.pluginType,
+      status: record.status,
+      mode: record.mode,
+      ...record.endpoint === void 0 ? {} : { endpoint: record.endpoint },
+      ...record.lastHealthAt === void 0 ? {} : { lastHealthAt: record.lastHealthAt },
+      ...record.lastError === void 0 ? {} : { lastError: record.lastError }
+    }));
+  }
+  /**
+   * Read a deployment's stored record without probing its host.
+   *
+   * The catalog executor uses this to decide whether a plugin tool call should
+   * route to the resident service. Unlike {@link status} it never issues a
+   * `/health` probe and resolves `undefined` when no record exists.
+   *
+   * @param tenantId - Tenant that owns the plugin.
+   * @param pluginType - Plugin type.
+   * @returns The minimal `{ status, endpoint, mode }` view, or `undefined`.
+   */
+  async getDeployment(tenantId, pluginType) {
+    const record = await this.store.get(tenantId, pluginType);
+    if (!record) return void 0;
+    return { status: record.status, endpoint: record.endpoint, mode: record.mode };
+  }
+  /**
+   * Ensure an existing on-demand deployment is running and healthy.
+   *
+   * Paused/stopped deployments are resumed (or re-provisioned when the sandbox
+   * is gone) and their status is refreshed. Concurrent calls for the same plugin
+   * are coalesced by the runtime registry's single-flight.
+   *
+   * @param tenantId - Tenant that owns the plugin.
+   * @param pluginType - Plugin type.
+   */
+  async ensureRunning(tenantId, pluginType) {
+    const record = await this.store.get(tenantId, pluginType);
+    if (!record) return;
+    if (record.status === "running" && record.endpoint) return;
+    const key = this.registryKey(tenantId, pluginType);
+    await this.registry.ensureRunning(key, async () => {
+      const config = this.buildSandboxConfig(
+        tenantId,
+        pluginType,
+        record.mode,
+        record.idleTimeoutMs,
+        record.imageRef ?? this.image
+      );
+      let sandbox;
+      try {
+        sandbox = await this.sandboxManager.getSandbox(record.sandboxName);
+        await sandbox.start();
+      } catch {
+        try {
+          sandbox = await this.sandboxManager.createSandbox(record.sandboxName, config);
+          await this.installPluginHost(sandbox);
+        } catch (error) {
+          throw new PluginDeploymentError(
+            "SANDBOX_CREATE_FAILED",
+            `failed to provision sandbox "${record.sandboxName}": ${errorMessage4(error)}`
+          );
+        }
+      }
+      const endpoint = await this.resolveEndpoint(sandbox);
+      const health = await this.waitForHealth(endpoint);
+      if (!health.ok) {
+        await this.store.updateStatus(tenantId, pluginType, {
+          status: "failed",
+          endpoint,
+          lastHealthAt: this.nowIso(),
+          lastError: health.error ?? "health probe failed"
+        });
+        throw new PluginDeploymentError(
+          "HEALTH_TIMEOUT",
+          `resident host for plugin "${pluginType}" did not become healthy: ${health.error ?? "unknown"}`
+        );
+      }
+      await this.store.updateStatus(tenantId, pluginType, {
+        status: "running",
+        endpoint,
+        lastHealthAt: this.nowIso(),
+        lastError: void 0
+      });
+      this.registry.setEndpoint(key, endpoint);
+      this.registry.markHealthy(key);
+    });
+  }
+  /**
+   * Reconcile the store against the provider at startup.
+   *
+   * Lease-gated and never throws: for each stored deployment it verifies the
+   * sandbox still exists, refreshes the endpoint, and marks missing/unreadable
+   * sandboxes `failed` with a diagnostic. Runs are best-effort.
+   *
+   * @returns A summary of the pass.
+   */
+  async startupReconcile() {
+    if (!await this.acquireLease()) {
+      return { ran: false, checked: 0, refreshed: 0, failed: 0 };
+    }
+    const records = await this.listAll();
+    let refreshed = 0;
+    let failed = 0;
+    for (const record of records) {
+      try {
+        const sandbox = await this.sandboxManager.getSandbox(record.sandboxName);
+        const sandboxStatus = await sandbox.getStatus();
+        if (sandboxStatus === "unknown") {
+          throw new Error("sandbox not found");
+        }
+        const endpoint = typeof sandbox.getEndpoint === "function" ? (await sandbox.getEndpoint(record.port || PLUGIN_GUEST_PORT)).endpoint : record.endpoint;
+        await this.store.updateStatus(record.tenantId, record.pluginType, {
+          status: sandboxStatus === "running" ? "running" : record.status,
+          ...endpoint === void 0 ? {} : { endpoint },
+          lastError: void 0
+        });
+        if (endpoint !== void 0) {
+          this.registry.setEndpoint(this.registryKey(record.tenantId, record.pluginType), endpoint);
+        }
+        refreshed += 1;
+      } catch (error) {
+        failed += 1;
+        this.logger.warn?.(
+          {
+            event: "plugin.deployment.reconcile.failed",
+            tenantId: record.tenantId,
+            pluginType: record.pluginType,
+            sandboxName: record.sandboxName,
+            error: errorMessage4(error)
+          },
+          "stored plugin deployment has no reachable sandbox"
+        );
+        await this.safeUpdateStatus(record.tenantId, record.pluginType, {
+          status: "failed",
+          lastError: `startup reconcile: ${errorMessage4(error)}`
+        });
+      }
+    }
+    this.logger.info(
+      { event: "plugin.deployment.reconcile", checked: records.length, refreshed, failed },
+      "plugin deployment startup reconcile complete"
+    );
+    return { ran: true, checked: records.length, refreshed, failed };
+  }
+  /**
+   * Probe every running deployment's `/health` and refresh its health record.
+   *
+   * Lease-gated and never throws. Unhealthy `alwaysOn` deployments are
+   * re-provisioned best-effort.
+   *
+   * @returns A summary of the pass.
+   */
+  async healthWatchdog() {
+    if (!await this.acquireLease()) {
+      return { ran: false, checked: 0, healthy: 0, unhealthy: 0 };
+    }
+    const records = await this.listAll();
+    let healthy = 0;
+    let unhealthy = 0;
+    for (const record of records) {
+      if (record.status !== "running" || !record.endpoint) continue;
+      const key = this.registryKey(record.tenantId, record.pluginType);
+      const health = await this.probeHealth(record.endpoint);
+      if (health.ok) {
+        healthy += 1;
+        this.registry.markHealthy(key);
+        await this.safeUpdateStatus(record.tenantId, record.pluginType, {
+          lastHealthAt: this.nowIso(),
+          lastError: void 0
+        });
+        continue;
+      }
+      unhealthy += 1;
+      this.registry.markUnhealthy(key, health.error ?? "health probe failed");
+      await this.safeUpdateStatus(record.tenantId, record.pluginType, {
+        lastHealthAt: this.nowIso(),
+        lastError: health.error ?? "health probe failed"
+      });
+      if (record.mode === "alwaysOn") {
+        await this.restartBestEffort(record, key);
+      }
+    }
+    this.logger.info(
+      { event: "plugin.deployment.watchdog", checked: healthy + unhealthy, healthy, unhealthy },
+      "plugin deployment health watchdog complete"
+    );
+    return { ran: true, checked: healthy + unhealthy, healthy, unhealthy };
+  }
+  /**
+   * Best-effort re-provision and health-check of an unhealthy `alwaysOn`
+   * deployment.
+   *
+   * @param record - Deployment to restart.
+   * @param key - Runtime registry key.
+   */
+  async restartBestEffort(record, key) {
+    try {
+      const config = this.buildSandboxConfig(
+        record.tenantId,
+        record.pluginType,
+        record.mode,
+        record.idleTimeoutMs,
+        record.imageRef ?? this.image
+      );
+      let sandbox;
+      try {
+        sandbox = await this.sandboxManager.createSandbox(record.sandboxName, config);
+        await sandbox.start().catch(() => void 0);
+        await this.installPluginHost(sandbox);
+      } catch (error) {
+        throw new PluginDeploymentError(
+          "SANDBOX_CREATE_FAILED",
+          `failed to provision sandbox "${record.sandboxName}": ${errorMessage4(error)}`
+        );
+      }
+      const endpoint = await this.resolveEndpoint(sandbox);
+      const health = await this.waitForHealth(endpoint);
+      if (!health.ok) {
+        await this.safeUpdateStatus(record.tenantId, record.pluginType, {
+          endpoint,
+          lastError: health.error ?? "health probe failed"
+        });
+        return;
+      }
+      await this.safeUpdateStatus(record.tenantId, record.pluginType, {
+        status: "running",
+        endpoint,
+        lastHealthAt: this.nowIso(),
+        lastError: void 0
+      });
+      this.registry.setEndpoint(key, endpoint);
+      this.registry.markHealthy(key);
+    } catch (error) {
+      this.logger.warn?.(
+        {
+          event: "plugin.deployment.watchdog.restart_failed",
+          tenantId: record.tenantId,
+          pluginType: record.pluginType,
+          error: errorMessage4(error)
+        },
+        "best-effort alwaysOn restart failed"
+      );
+    }
+  }
+  /**
+   * Build the sandbox creation config for a plugin deployment.
+   *
+   * @param tenantId - Tenant id.
+   * @param pluginType - Plugin type.
+   * @param mode - Lifecycle strategy.
+   * @param idleTimeoutMs - On-demand idle timeout in milliseconds.
+   * @param image - Optional image override for this provisioning.
+   * @returns The provider-facing config.
+   */
+  buildSandboxConfig(tenantId, pluginType, mode, idleTimeoutMs, image = this.image) {
+    return {
+      assistant_id: "",
+      thread_id: pluginSandboxName(tenantId, pluginType),
+      tenantId,
+      entrypoint: buildBootstrapEntrypoint(pluginType),
+      exposePorts: [PLUGIN_GUEST_PORT],
+      // `alwaysOn` deployments never expire; on-demand deployments are
+      // time-boxed by the service (finalized with the lifecycle work in
+      // Plan 4 Task 6). The provider expects seconds, not milliseconds.
+      timeoutSeconds: mode === "alwaysOn" ? null : Math.max(1, Math.round(idleTimeoutMs / 1e3)),
+      ...image === void 0 ? {} : { image }
+    };
+  }
+  /**
+   * Resolve the routable endpoint for the published guest port.
+   *
+   * @param sandbox - Provisioned sandbox instance.
+   * @returns The relative proxy path or scheme-less host endpoint.
+   * @throws PluginDeploymentError with `BACKEND_UNSUPPORTED` when the provider
+   *   does not implement `getEndpoint`.
+   */
+  async resolveEndpoint(sandbox) {
+    if (typeof sandbox.getEndpoint !== "function") {
+      throw new PluginDeploymentError(
+        "BACKEND_UNSUPPORTED",
+        "sandbox provider does not support resident plugin services (missing getEndpoint)"
+      );
+    }
+    const { endpoint } = await sandbox.getEndpoint(PLUGIN_GUEST_PORT);
+    return endpoint;
+  }
+  /**
+   * Poll `/health` until the host answers healthy or the deadline passes.
+   *
+   * @param endpoint - Resolved endpoint route.
+   * @returns The final probe outcome.
+   */
+  async waitForHealth(endpoint) {
+    const deadline = Date.now() + this.healthTimeoutMs;
+    let last = { ok: false, error: "health not attempted" };
+    do {
+      last = await this.probeHealth(endpoint);
+      if (last.ok) return last;
+      if (Date.now() >= deadline) break;
+      await this.sleep(this.healthPollIntervalMs);
+    } while (Date.now() < deadline);
+    return last;
+  }
+  /**
+   * Issue a single `GET ${baseUrl}${endpoint}/health` request.
+   *
+   * Never throws; network/timeout/non-2xx/parse failures resolve `{ ok: false }`.
+   *
+   * @param endpoint - Resolved endpoint route.
+   * @returns The probe outcome.
+   */
+  async probeHealth(endpoint) {
+    const url = `${this.serviceBaseUrl}${endpoint}/health`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.healthProbeTimeoutMs);
+    try {
+      const response = await this.fetchImpl(url, {
+        method: "GET",
+        ...this.serviceKey === void 0 ? {} : { headers: { Authorization: `Bearer ${this.serviceKey}` } },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        return { ok: false, error: `health responded with HTTP ${response.status}` };
+      }
+      const body = await response.json().catch(() => void 0);
+      if (isRecord4(body) && body.ok === true) {
+        return { ok: true };
+      }
+      return { ok: false, error: "health returned an invalid envelope" };
+    } catch (error) {
+      return { ok: false, error: errorMessage4(error) };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * Enforce per-tenant and global deployment caps.
+   *
+   * @param tenantId - Tenant attempting to deploy.
+   * @throws PluginDeploymentError with `LIMIT_EXCEEDED`.
+   */
+  async assertWithinLimits(tenantId) {
+    const { maxPerTenant, maxGlobal } = this.limits;
+    if (maxPerTenant !== void 0) {
+      const tenantRecords = await this.store.listByTenant(tenantId);
+      if (tenantRecords.length >= maxPerTenant) {
+        throw new PluginDeploymentError(
+          "LIMIT_EXCEEDED",
+          `tenant "${tenantId}" reached the resident plugin limit (${maxPerTenant})`
+        );
+      }
+    }
+    if (maxGlobal !== void 0 && this.listAllDeployments) {
+      const all = await this.listAllDeployments();
+      if (all.length >= maxGlobal) {
+        throw new PluginDeploymentError(
+          "LIMIT_EXCEEDED",
+          `global resident plugin limit reached (${maxGlobal})`
+        );
+      }
+    }
+  }
+  /**
+   * Acquire the reconcile lease for this pass.
+   *
+   * @returns True when this replica may run the pass.
+   */
+  async acquireLease() {
+    try {
+      return await this.lease.tryAcquire(
+        PLUGIN_DEPLOYMENT_LEASE_KEY,
+        this.replicaId,
+        PLUGIN_DEPLOYMENT_LEASE_TTL_MS
+      );
+    } catch (error) {
+      this.logger.warn?.(
+        { event: "plugin.deployment.lease.failed", error: errorMessage4(error) },
+        "could not acquire reconcile lease; skipping pass"
+      );
+      return false;
+    }
+  }
+  /**
+   * List deployments for reconcile/watchdog, degrading to an empty list.
+   *
+   * @returns Stored deployments, or `[]` when no global lister is wired.
+   */
+  async listAll() {
+    if (!this.listAllDeployments) return [];
+    try {
+      return await this.listAllDeployments();
+    } catch (error) {
+      this.logger.warn?.(
+        { event: "plugin.deployment.list.failed", error: errorMessage4(error) },
+        "could not list plugin deployments"
+      );
+      return [];
+    }
+  }
+  /**
+   * Apply a status patch, swallowing store errors (used on the soft paths).
+   *
+   * @param tenantId - Tenant id.
+   * @param pluginType - Plugin type.
+   * @param patch - Partial deployment update.
+   */
+  async safeUpdateStatus(tenantId, pluginType, patch) {
+    try {
+      await this.store.updateStatus(tenantId, pluginType, patch);
+    } catch (error) {
+      this.logger.warn?.(
+        {
+          event: "plugin.deployment.store_update_failed",
+          tenantId,
+          pluginType,
+          error: errorMessage4(error)
+        },
+        "could not update plugin deployment status"
+      );
+    }
+  }
+  /**
+   * Assemble a durable deployment record.
+   *
+   * @param input - Record fields (optional fields fall back to now/undefined).
+   * @returns A fully populated deployment.
+   */
+  buildRecord(input) {
+    const now = this.nowIso();
+    return {
+      id: input.id,
+      tenantId: input.tenantId,
+      pluginType: input.pluginType,
+      pluginVersion: input.pluginVersion,
+      mode: input.mode,
+      status: input.status,
+      provider: input.provider,
+      sandboxName: input.sandboxName,
+      port: PLUGIN_GUEST_PORT,
+      endpoint: input.endpoint,
+      ...input.image === void 0 ? {} : { imageRef: input.image },
+      idleTimeoutMs: input.idleTimeoutMs,
+      ...input.lastHealthAt === void 0 ? {} : { lastHealthAt: input.lastHealthAt },
+      ...input.lastError === void 0 ? {} : { lastError: input.lastError },
+      createdAt: input.createdAt ?? now,
+      updatedAt: now
+    };
+  }
+  /**
+   * Compose the runtime registry key for a deployment.
+   *
+   * @param tenantId - Tenant id.
+   * @param pluginType - Plugin type.
+   * @returns `${tenantId}:${pluginType}`.
+   */
+  registryKey(tenantId, pluginType) {
+    return `${tenantId}:${pluginType}`;
+  }
+  /**
+   * Current time as an ISO string from the injected clock.
+   *
+   * @returns ISO-8601 timestamp.
+   */
+  nowIso() {
+    return new Date(this.now()).toISOString();
+  }
+};
+function errorMessage4(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/services/plugins/PluginDeploymentRuntimeStartup.ts
+var DEFAULT_PLUGIN_WATCHDOG_INTERVAL_MS = 3e4;
+var DEFAULT_PLUGIN_RECONCILE_DEADLINE_MS = 3e4;
+var DEFAULT_PLUGIN_MAX_PER_TENANT = 10;
+var DEFAULT_PLUGIN_MAX_GLOBAL = 100;
+var PLUGIN_DEPLOYMENT_RUNTIME_FLAG = "AXIOM_PLUGIN_DEPLOYMENT_RUNTIME";
+var PLUGIN_DEPLOYMENT_MAX_PER_TENANT_ENV = "PLUGIN_DEPLOYMENT_MAX_PER_TENANT";
+var PLUGIN_DEPLOYMENT_MAX_GLOBAL_ENV = "PLUGIN_DEPLOYMENT_MAX_GLOBAL";
+function isPluginDeploymentRuntimeEnabled(env = process.env) {
+  const flag = env[PLUGIN_DEPLOYMENT_RUNTIME_FLAG];
+  if (flag === "false" || flag === "0") return false;
+  if (flag === "true" || flag === "1") return true;
+  return Boolean(env.MICROSANDBOX_SERVICE_URL);
+}
+function readPluginDeploymentLimits(env = process.env) {
+  return {
+    maxPerTenant: parsePositiveInt(
+      env[PLUGIN_DEPLOYMENT_MAX_PER_TENANT_ENV],
+      DEFAULT_PLUGIN_MAX_PER_TENANT
+    ),
+    maxGlobal: parsePositiveInt(
+      env[PLUGIN_DEPLOYMENT_MAX_GLOBAL_ENV],
+      DEFAULT_PLUGIN_MAX_GLOBAL
+    )
+  };
+}
+function startPluginDeploymentRuntime(options) {
+  const { lease, holder, logger: logger7 } = options;
+  const forcedOn = process.env[PLUGIN_DEPLOYMENT_RUNTIME_FLAG] === "true" || process.env[PLUGIN_DEPLOYMENT_RUNTIME_FLAG] === "1";
+  const effectiveServiceBaseUrl = options.wiring.serviceBaseUrl ?? process.env.MICROSANDBOX_SERVICE_URL;
+  if (forcedOn && !effectiveServiceBaseUrl) {
+    logger7.warn(
+      `${PLUGIN_DEPLOYMENT_RUNTIME_FLAG} is enabled but MICROSANDBOX_SERVICE_URL is empty; skipping plugin deployment runtime`,
+      { holder }
+    );
+    return { reconcile: Promise.resolve(), dispose: async () => void 0 };
+  }
+  const register = options.register ?? ((service3) => setPluginDeploymentService(service3));
+  const setIntervalFn = options.setIntervalFn ?? setInterval;
+  const clearIntervalFn = options.clearIntervalFn ?? clearInterval;
+  const watchdogIntervalMs = options.watchdogIntervalMs ?? DEFAULT_PLUGIN_WATCHDOG_INTERVAL_MS;
+  const reconcileDeadlineMs = options.reconcileDeadlineMs ?? DEFAULT_PLUGIN_RECONCILE_DEADLINE_MS;
+  const createService = options.createService ?? ((deps2) => new PluginDeploymentService(deps2));
+  const deps = {
+    ...options.wiring,
+    lease,
+    replicaId: holder
+  };
+  const service2 = createService(deps);
+  register(service2);
+  logger7.info("plugin deployment runtime started", { holder });
+  const reconcile = runStartupReconcile(service2, reconcileDeadlineMs, logger7, holder);
+  let held = false;
+  let inFlight = false;
+  const tick = async () => {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      if (held) {
+        held = await renewLease(lease, holder, logger7);
+        if (!held) {
+          logger7.warn("plugin deployment lease lost; watchdog paused", { holder });
+        }
+      } else {
+        held = await acquireLease(lease, holder, logger7);
+        if (held) {
+          logger7.info("plugin deployment lease acquired", { holder });
+        }
+      }
+      if (!held) return;
+      await runWatchdog(service2, holder, logger7);
+    } finally {
+      inFlight = false;
+    }
+  };
+  const interval = setIntervalFn(() => {
+    void tick();
+  }, watchdogIntervalMs);
+  return {
+    reconcile,
+    async dispose() {
+      clearIntervalFn(interval);
+      if (held) {
+        try {
+          await lease.release(PLUGIN_DEPLOYMENT_LEASE_KEY, holder);
+        } catch (error) {
+          logger7.warn("plugin deployment lease release failed", {
+            holder,
+            error: errorMessage5(error)
+          });
+        }
+        held = false;
+      }
+      register(void 0);
+      logger7.info("plugin deployment runtime stopped", { holder });
+    }
+  };
+}
+async function runStartupReconcile(service2, deadlineMs, logger7, holder) {
+  try {
+    await withDeadline(service2.startupReconcile(), deadlineMs);
+    logger7.info("plugin deployment startup reconcile complete", { holder });
+  } catch (error) {
+    logger7.warn("plugin deployment startup reconcile failed", {
+      holder,
+      error: errorMessage5(error)
+    });
+  }
+}
+async function withDeadline(work, deadlineMs) {
+  const settled = work.then(() => void 0);
+  if (!Number.isFinite(deadlineMs) || deadlineMs <= 0) {
+    await settled;
+    return;
+  }
+  let timer;
+  const deadline = new Promise((resolve3) => {
+    timer = setTimeout(resolve3, deadlineMs);
+    unrefTimer(timer);
+  });
+  try {
+    await Promise.race([settled, deadline]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+async function acquireLease(lease, holder, logger7) {
+  try {
+    return await lease.tryAcquire(
+      PLUGIN_DEPLOYMENT_LEASE_KEY,
+      holder,
+      PLUGIN_DEPLOYMENT_LEASE_TTL_MS
+    );
+  } catch (error) {
+    logger7.warn("plugin deployment lease acquire failed", {
+      holder,
+      error: errorMessage5(error)
+    });
+    return false;
+  }
+}
+async function renewLease(lease, holder, logger7) {
+  try {
+    return await lease.renew(
+      PLUGIN_DEPLOYMENT_LEASE_KEY,
+      holder,
+      PLUGIN_DEPLOYMENT_LEASE_TTL_MS
+    );
+  } catch (error) {
+    logger7.warn("plugin deployment lease renew failed", {
+      holder,
+      error: errorMessage5(error)
+    });
+    return false;
+  }
+}
+async function runWatchdog(service2, holder, logger7) {
+  try {
+    await service2.healthWatchdog();
+  } catch (error) {
+    logger7.warn("plugin deployment health watchdog failed", {
+      holder,
+      error: errorMessage5(error)
+    });
+  }
+}
+function unrefTimer(timer) {
+  if (typeof timer === "object" && timer !== null && "unref" in timer) {
+    timer.unref?.();
+  }
+}
+function parsePositiveInt(value, fallback) {
+  if (value === void 0 || value.trim() === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.floor(parsed);
+}
+function errorMessage5(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/services/multiReplicaReadiness.ts
 import { getStoreLattice as getStoreLattice28 } from "@axiom-lattice/core";
-var SHARED_STORE_KINDS = ["lease", "outbox", "threadMessageQueue", "task", "taskWorkItem"];
+var SHARED_STORE_KINDS = [
+  "lease",
+  "outbox",
+  "threadMessageQueue",
+  "task",
+  "taskWorkItem",
+  "channelInstallation"
+];
 function storeClassName(kind) {
   try {
     return getStoreLattice28("default", kind).store.constructor?.name;
@@ -26055,6 +27384,7 @@ app.setErrorHandler((error, request, reply) => {
     error: error.message || "\u670D\u52A1\u5668\u5185\u90E8\u9519\u8BEF"
   });
 });
+var shutdownHandlersInstalled = false;
 function getConfiguredSandboxProvider() {
   const sandboxProviderType = process.env.SANDBOX_PROVIDER_TYPE || "microsandbox-remote";
   return createSandboxProvider({
@@ -26188,18 +27518,18 @@ var start = async (config) => {
       projectRoomRealtimeRuntime
     });
     try {
-      const { A2AAuthService, parseEnvKeys } = await import("./A2AAuthService-7UGQ7GMW.mjs");
+      const { A2AAuthService: A2AAuthService2, parseEnvKeys: parseEnvKeys2 } = await import("./A2AAuthService-7UGQ7GMW.mjs");
       const { registerA2AStandardRoutes } = await import("./a2a-standard-PBYPNHOA.mjs");
-      const a2a = await import("./a2a-FGYX2HH3.mjs");
+      const a2a = await import("./a2a-BHBLACJV.mjs");
       const a2aKeyStore = getStoreLattice29("default", "a2aApiKey").store;
       const assistantStore = getStoreLattice29("default", "assistant").store;
       const projectStore = getStoreLattice29("default", "project").store;
       const taskStore = getStoreLattice29("default", "task").store;
-      const authService = new A2AAuthService({
+      const authService = new A2AAuthService2({
         keyStore: a2aKeyStore,
         assistantStore,
         projectStore,
-        envKeyMap: parseEnvKeys(process.env.A2A_API_KEYS || ""),
+        envKeyMap: parseEnvKeys2(process.env.A2A_API_KEYS || ""),
         allowUnauthenticated: process.env.A2A_ALLOW_UNAUTHENTICATED === "true"
       });
       await authService.refresh();
@@ -26224,7 +27554,7 @@ var start = async (config) => {
       const { registerOpenCatalogRoutes } = await import("./open-catalog-SZQ435AY.mjs");
       const { registerOpenFilesRoutes } = await import("./open-files-X3HXVEEM.mjs");
       const { registerOpenAuditRoutes } = await import("./open-audit-UJ3NXCGW.mjs");
-      const { registerOpenExposureRoutes } = await import("./open-exposure-VU227IO3.mjs");
+      const { registerOpenExposureRoutes } = await import("./open-exposure-27ESFWTB.mjs");
       const { openLattice } = await import("./openLattice-Q6M5S6CY.mjs");
       const { createKbProvider } = await import("./kbProvider-2D6DZ34N.mjs");
       const { createOpenSandboxProvider } = await import("./sandboxProvider-DUYWHYJN.mjs");
@@ -26272,6 +27602,50 @@ var start = async (config) => {
       sandboxLatticeManager2.registerLattice("default", getConfiguredSandboxProvider());
       logger6.info("Registered sandbox manager from env configuration");
     }
+    if (isPluginDeploymentRuntimeEnabled()) {
+      try {
+        const pluginDeploymentStore = getStoreLattice29("default", "pluginDeployment").store;
+        const tenantStore = getStoreLattice29("default", "tenant").store;
+        const leaseStore2 = getStoreLattice29("default", "lease").store;
+        const listAllDeployments = async () => {
+          const tenants = await tenantStore.getAllTenants();
+          const lists = await Promise.all(
+            tenants.map(
+              (tenant2) => pluginDeploymentStore.listByTenant(tenant2.id).catch(() => [])
+            )
+          );
+          return lists.flat();
+        };
+        const pluginDeploymentRuntime = startPluginDeploymentRuntime({
+          wiring: {
+            store: pluginDeploymentStore,
+            sandboxManager: getSandBoxManager4(),
+            catalog: getSandboxPluginCatalog3(),
+            installPluginHost,
+            limits: readPluginDeploymentLimits(),
+            serviceKey: process.env.MICROSANDBOX_API_KEY,
+            listAllDeployments,
+            // The service logs fields-first; the gateway logger is message-first.
+            logger: {
+              info: (fields, message) => logger6.info(message ?? "plugin deployment", fields),
+              warn: (fields, message) => logger6.warn(message ?? "plugin deployment", fields),
+              error: (fields, message) => logger6.error(message ?? "plugin deployment", fields)
+            }
+          },
+          lease: leaseStore2,
+          holder: getReplicaId7(),
+          logger: logger6
+        });
+        app.addHook("onClose", async () => {
+          await pluginDeploymentRuntime.dispose();
+        });
+        logger6.info("Plugin deployment runtime started");
+      } catch (err) {
+        logger6.warn("Plugin deployment runtime unavailable", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
     try {
       const { ResourceController } = await import("./resources-2L3KSUUU.mjs");
       const sharedResourceStore = getStoreLattice29("default", "sharedResource").store;
@@ -26290,12 +27664,21 @@ var start = async (config) => {
       });
     }
     if (channelDeps && process.env.CHANNELS_ENABLED !== "false") {
-      const { connectAllChannels } = await import("@axiom-lattice/core");
+      const { connectAllChannels, disconnectAllChannels, ChannelConnectionLeader } = await import("@axiom-lattice/core");
       try {
-        await connectAllChannels(
-          (channel) => adapterRegistry.get(channel),
-          { deps: { router: channelDeps.router } }
-        );
+        const channelLeader = new ChannelConnectionLeader({
+          leaseStore: getStoreLattice29("default", "lease").store,
+          owner: getReplicaId7(),
+          connect: () => connectAllChannels((channel) => adapterRegistry.get(channel), {
+            deps: { router: channelDeps.router }
+          }),
+          disconnect: () => disconnectAllChannels((channel) => adapterRegistry.get(channel)),
+          log: { warn: (message, context) => logger6.warn(message, context) }
+        });
+        app.addHook("onClose", async () => {
+          await channelLeader.stop();
+        });
+        channelLeader.start();
       } catch (err) {
         logger6.error("Failed to start channel connections", {
           error: err instanceof Error ? err.message : String(err)
@@ -26307,20 +27690,20 @@ var start = async (config) => {
     const outboxStore = getStoreLattice29("default", "outbox").store;
     taskLifecycleNotifier3.setOutbox(outboxStore);
     projectTaskAdmissionNotifier2.setOutbox(outboxStore);
-    configurePluginCatalogSync({ outbox: outboxStore, owner: getReplicaId6() });
+    configurePluginCatalogSync({ outbox: outboxStore, owner: getReplicaId7() });
     bridgeAssistantEvents(
       (event, cb) => eventBus4.subscribe(event, cb),
       outboxStore,
-      getReplicaId6()
+      getReplicaId7()
     );
     if (projectRoomRealtimeRuntime) {
       projectRoomRealtimeRuntime.broker.setBroadcastHook((scope, serialized, sourceKey) => {
-        void publishRoomEvent(outboxStore, getReplicaId6(), scope, serialized, sourceKey);
+        void publishRoomEvent(outboxStore, getReplicaId7(), scope, serialized, sourceKey);
       });
     }
     const outboxPoller = new OutboxPoller({
       store: outboxStore,
-      owner: getReplicaId6(),
+      owner: getReplicaId7(),
       handlers: {
         "task-lifecycle": (payload) => taskLifecycleNotifier3.deliverFromOutbox(payload),
         "project-task-admission": (payload) => projectTaskAdmissionNotifier2.deliverFromOutbox(payload),
@@ -26328,6 +27711,7 @@ var start = async (config) => {
           if (projectRoomRealtimeRuntime) ingestRoomEvent(payload, projectRoomRealtimeRuntime.broker);
         },
         "assistant-changed": (payload) => handleAssistantChanged(payload, (tenantId) => agentLatticeManager5.initializeStoredAssistantsForTenant(tenantId)),
+        [A2A_KEY_CHANGED_TOPIC]: (payload) => handleA2AKeyChanged(payload, () => refreshStoreKeyMap()),
         [MCP_CONFIG_CHANGED_TOPIC]: (payload) => reconcileMcpConfigChange(payload, {
           store: getStoreLattice29("default", "mcp").store,
           manager: mcpManager3,
@@ -26336,6 +27720,11 @@ var start = async (config) => {
         [PLUGIN_CATALOG_CHANGED_TOPIC]: async (payload) => {
           const tenantId = payload?.tenantId;
           if (typeof tenantId === "string" && tenantId.length > 0) getSandboxPluginCatalog3().invalidate(tenantId);
+        },
+        [MODEL_PROVIDER_CHANGED_TOPIC]: async (payload) => {
+          const controller = routes.modelProviderController;
+          if (!controller) return;
+          await handleModelProviderChanged(payload, (tenantId, providerId2) => controller.reconcileProvider(tenantId, providerId2));
         }
       },
       log: logger6
@@ -26395,17 +27784,41 @@ var start = async (config) => {
       log: logger6
     });
     outboxRetention.start();
+    let agentTaskConsumer;
     const queueServiceConfig = config?.queueServiceConfig;
     if (queueServiceConfig) {
       setQueueServiceType(queueServiceConfig.type);
       if (queueServiceConfig.defaultStartPollingQueue) {
-        const agentTaskConsumer = new AgentTaskConsumer(target_port);
+        agentTaskConsumer = new AgentTaskConsumer(target_port);
         agentTaskConsumer.startPollingQueue();
       }
     }
     restoreMcpConnections().catch((error) => {
       logger6.error("MCP connection restoration failed", { error });
     });
+    if (config?.gracefulShutdown !== false && !shutdownHandlersInstalled) {
+      shutdownHandlersInstalled = true;
+      const gracefulShutdown = createGracefulShutdown({
+        timeoutMs: config?.gracefulShutdownTimeoutMs ?? 1e4,
+        log: {
+          info: (message, context) => logger6.info(message, context),
+          warn: (message, context) => logger6.warn(message, context)
+        },
+        steps: [
+          async () => {
+            await Promise.all(
+              agentInstanceManager9.getAllAgents().map((agent) => agent.abort().catch(() => void 0))
+            );
+          },
+          () => agentTaskConsumer?.stopPollingQueue(),
+          () => outboxPoller.stop(),
+          () => outboxRetention.stop(),
+          () => app.close()
+        ]
+      });
+      process.once("SIGTERM", () => void gracefulShutdown("SIGTERM"));
+      process.once("SIGINT", () => void gracefulShutdown("SIGINT"));
+    }
   } catch (err) {
     logger6.error("Server start failed", { error: err });
     process.exit(1);
@@ -26419,13 +27832,22 @@ var LatticeGateway = {
   AgentTaskConsumer
 };
 export {
+  A2AAuthService,
+  A2A_KEY_CHANGED_TOPIC,
   LatticeGateway,
+  MODEL_PROVIDER_CHANGED_TOPIC,
+  ModelProviderService,
   ProjectRoomEventBroker,
   ROOM_EVENT_TOPIC,
   createOrphanRecoveryRuntime,
   createRecoveryCallerDeps,
   createTaskRunLiveness,
+  handleA2AKeyChanged,
+  handleModelProviderChanged,
   ingestRoomEvent,
+  parseEnvKeys,
+  publishA2AKeyChanged,
+  publishModelProviderChanged,
   publishRoomEvent,
   recoverTask,
   recoverTopCaller,