@stigmer/server 3.17.0 → 3.18.0

package/src/domain/plugin/__tests__/plugin.test.ts

@@ -9,10 +9,14 @@
  * delete of a member is refused naming the plugin while the plugin's own
  * upgrade drops what the archive dropped; uninstall removes every member
  * and is refused while a user's own agent still references one; a slug an
- * unmanaged resource holds refuses the install; a bad overlay refuses
- * before any write. A second composition, under an authorizer that denies
- * `can_write_reserved_labels`, pins the reserved-label refusal the
- * open-source posture allows by design.
+ * unmanaged resource holds refuses the install, and a user's row is never
+ * adopted whichever side declares system content; a bad overlay refuses
+ * before any write. A second composition, under an authorizer that decides
+ * `can_write_reserved_labels` per test, pins the reserved-label refusal the
+ * open-source posture allows by design, and the one adoption the platform
+ * makes: an operator's plugin taking over the system-content row it
+ * replaces in place, the row's id and default instance kept, a member's
+ * identical push refused before the slug is judged.
  */
 import { mkdtempSync, rmSync } from "node:fs";
 import net from "node:net";
@@ -38,6 +42,7 @@ import {
   AgentSpecSchema,
   McpServerUsageSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { AgentInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/query_pb";
 import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
 import { PluginCommandController } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/command_pb";
@@ -59,6 +64,7 @@ import { createLogger } from "../../../boot/logger.js";
 import {
   PLUGIN_LABEL,
   PLUGIN_VERSION_LABEL,
+  SYSTEM_LABEL,
 } from "../../../pipeline/apiresource-labels.js";
 
 const silentLogger = createLogger({
@@ -507,6 +513,66 @@ describe("Plugin members are the plugin's to redefine", () => {
     );
   });
 
+  it("never adopts a user's agent: a same-slug row without the system label is refused even when the plugin declares system content, and a system row is refused by a plugin that does not", async () => {
+    // The open-source authorizer grants reserved-label writes to everyone,
+    // so this is the posture where the label alone would be a weak guard;
+    // the rule needs BOTH sides to carry it.
+    const name = uniqueName("users-own");
+    await agents.create(
+      createMessage(AgentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: createMessage(ApiResourceMetadataSchema, { org: ORG, name }),
+        spec: createMessage(AgentSpecSchema, {
+          instructions: "Mine, written by hand, under my own name.",
+        }),
+      }),
+    );
+    await expectCode(
+      plugins.push({ org: ORG, artifact: archiveOf(systemOverlay(name)) }),
+      Code.AlreadyExists,
+      `'${name}' exists in org '${ORG}' and is not managed by a plugin`,
+    );
+
+    const seeded = uniqueName("seeded-row");
+    await agents.create(
+      createMessage(AgentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: createMessage(ApiResourceMetadataSchema, {
+          org: ORG,
+          name: seeded,
+          labels: { [SYSTEM_LABEL]: "true" },
+        }),
+        spec: createMessage(AgentSpecSchema, {
+          instructions: "System content a plain plugin may not take over.",
+        }),
+      }),
+    );
+    await expectCode(
+      plugins.push({
+        org: ORG,
+        artifact: archiveOf(
+          withFile(
+            thermosLike(seeded),
+            "ai.stigmer/agent.yaml",
+            [
+              "apiVersion: agentic.stigmer.ai/v1",
+              "kind: Agent",
+              "metadata:",
+              `  name: ${seeded}`,
+              "spec:",
+              "  instructions: A plain overlay that declares no system content.",
+              "",
+            ].join("\n"),
+          ),
+        ),
+      }),
+      Code.AlreadyExists,
+      `'${seeded}' exists in org '${ORG}' and is not managed by a plugin`,
+    );
+  });
+
   it("refuses to install a slug another plugin holds, naming that plugin", async () => {
     const first = uniqueName("holder");
     const second = uniqueName("claimant");
@@ -705,7 +771,14 @@ describe("Plugin push under an authorizer that enforces reserved labels", () =>
   let enforcing: ComposedServer;
   let enforcingPlugins: Client<typeof PluginCommandController>;
   let enforcingQuery: Client<typeof PluginQueryController>;
+  let enforcingAgents: Client<typeof AgentCommandController>;
+  let enforcingAgentQuery: Client<typeof AgentQueryController>;
+  let enforcingInstanceQuery: Client<typeof AgentInstanceQueryController>;
   const observed: AuthzCheck[] = [];
+  // Who the caller is to this authorizer: a member (reserved labels denied,
+  // the hosted default) or the platform operator (granted). The tests flip
+  // it, so one composition shows both sides of every reserved-label rule.
+  let reservedLabels: "deny" | "allow" = "deny";
 
   beforeAll(async () => {
     enforcingDir = mkdtempSync(path.join(tmpdir(), "plugin-domain-enforcing-"));
@@ -714,10 +787,11 @@ describe("Plugin push under an authorizer that enforces reserved labels", () =>
       authorize(_caller, check) {
         if (check.permission === IamPermission.can_write_reserved_labels) {
           observed.push(check);
-          return Promise.resolve({
-            kind: "deny",
-            reason: "reserved labels are the platform's",
-          });
+          return Promise.resolve(
+            reservedLabels === "allow"
+              ? { kind: "allow" }
+              : { kind: "deny", reason: "reserved labels are the platform's" },
+          );
         }
         return Promise.resolve({ kind: "allow" });
       },
@@ -741,6 +815,12 @@ describe("Plugin push under an authorizer that enforces reserved labels", () =>
     });
     enforcingPlugins = createClient(PluginCommandController, transport);
     enforcingQuery = createClient(PluginQueryController, transport);
+    enforcingAgents = createClient(AgentCommandController, transport);
+    enforcingAgentQuery = createClient(AgentQueryController, transport);
+    enforcingInstanceQuery = createClient(
+      AgentInstanceQueryController,
+      transport,
+    );
   });
 
   afterAll(async () => {
@@ -799,4 +879,135 @@ describe("Plugin push under an authorizer that enforces reserved labels", () =>
     });
     expect(members).toHaveLength(3);
   });
+
+  it("adopts a system-content row the operator's plugin replaces: same id, same default instance, the plugin's definition, one warning", async () => {
+    reservedLabels = "allow";
+    const name = uniqueName("plg-adopt");
+    // The row the platform seeded before plugins existed: system content,
+    // no plugin label, a default instance of its own.
+    const seeded = await enforcingAgents.create(
+      createMessage(AgentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: createMessage(ApiResourceMetadataSchema, {
+          org: ORG,
+          name,
+          labels: { [SYSTEM_LABEL]: "true" },
+        }),
+        spec: createMessage(AgentSpecSchema, {
+          instructions: "The instructions the seedpack wrote, long ago.",
+        }),
+      }),
+    );
+    const seededId = seeded.metadata!.id;
+    const seededInstanceId = seeded.status?.defaultInstanceId ?? "";
+    expect(seededInstanceId).not.toBe("");
+
+    const installed = await enforcingPlugins.push({
+      org: ORG,
+      artifact: archiveOf(systemOverlay(name)),
+    });
+    expect(installed.status?.state).toBe(PluginState.READY);
+    const adopted = installed.status!.warnings.filter(
+      (warning) => warning.kind === "member-adopted",
+    );
+    expect(adopted).toHaveLength(1);
+    expect(adopted[0]!.path).toBe("ai.stigmer/agent.yaml");
+    expect(adopted[0]!.message).toContain(`agent '${name}' (${seededId})`);
+    expect(adopted[0]!.message).toContain("conversations continue");
+
+    const after = await enforcingAgentQuery.get({ value: seededId });
+    expect(after.metadata?.labels[PLUGIN_LABEL]).toBe(installed.metadata!.id);
+    expect(after.metadata?.labels[PLUGIN_VERSION_LABEL]).toBe(
+      installed.status!.digest,
+    );
+    expect(after.metadata?.labels[SYSTEM_LABEL]).toBe("true");
+    expect(after.spec?.instructions).toBe(
+      "You are the platform's own agent, re-homed under a plugin.",
+    );
+    expect(after.status?.defaultInstanceId).toBe(seededInstanceId);
+    const instance = await enforcingInstanceQuery.get({
+      value: seededInstanceId,
+    });
+    expect(instance.spec?.agentId).toBe(seededId);
+
+    const { members } = await enforcingQuery.listMembers({
+      value: installed.metadata!.id,
+    });
+    expect(
+      members.find((member) => member.kind === ApiResourceKind.agent)?.id,
+    ).toBe(seededId);
+
+    // The second push of the same archive converges without a write.
+    const again = await enforcingPlugins.push({
+      org: ORG,
+      artifact: archiveOf(systemOverlay(name)),
+    });
+    expect(again.status?.digest).toBe(installed.status?.digest);
+    expect(
+      (await enforcingAgentQuery.get({ value: seededId })).status
+        ?.defaultInstanceId,
+    ).toBe(seededInstanceId);
+    reservedLabels = "deny";
+  });
+
+  it("refuses the same archive from a member before the slug is judged, and leaves the seeded row untouched", async () => {
+    reservedLabels = "allow";
+    const name = uniqueName("plg-member");
+    const seeded = await enforcingAgents.create(
+      createMessage(AgentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: createMessage(ApiResourceMetadataSchema, {
+          org: ORG,
+          name,
+          labels: { [SYSTEM_LABEL]: "true" },
+        }),
+        spec: createMessage(AgentSpecSchema, {
+          instructions: "The instructions the seedpack wrote, long ago.",
+        }),
+      }),
+    );
+    reservedLabels = "deny";
+    const error = await expectCode(
+      enforcingPlugins.push({
+        org: ORG,
+        artifact: archiveOf(systemOverlay(name)),
+      }),
+      Code.InvalidArgument,
+    );
+    expect(error.rawMessage).toContain(
+      `cannot be set by a plugin (ai.stigmer/agent.yaml: ${SYSTEM_LABEL})`,
+    );
+    const untouched = await enforcingAgentQuery.get({
+      value: seeded.metadata!.id,
+    });
+    expect(untouched.metadata?.labels[PLUGIN_LABEL]).toBeUndefined();
+    expect(untouched.spec?.instructions).toBe(
+      "The instructions the seedpack wrote, long ago.",
+    );
+  });
 });
+
+/**
+ * A plugin whose agent overlay declares system content under the given
+ * name: the shape of the official `assistant` plugin, whose agent replaces
+ * the row the retired seedpack wrote under the same slug.
+ */
+function systemOverlay(name: string): PluginFixture {
+  return withFile(
+    thermosLike(name),
+    "ai.stigmer/agent.yaml",
+    [
+      "apiVersion: agentic.stigmer.ai/v1",
+      "kind: Agent",
+      "metadata:",
+      `  name: ${name}`,
+      "  labels:",
+      `    ${SYSTEM_LABEL}: "true"`,
+      "spec:",
+      "  instructions: You are the platform's own agent, re-homed under a plugin.",
+      "",
+    ].join("\n"),
+  );
+}

package/src/domain/plugin/constants.ts

@@ -44,9 +44,15 @@ export type MaterializedKindName = (typeof MATERIALIZATION_ORDER)[number];
 export const TRANSFER_LANE_NOT_CONFIGURED =
   "plugin artifact transfer lane is not configured on this server";
 
-/** Warning kinds the SERVER adds to the library's; the wire carries them as strings. */
+/**
+ * Warning kinds the SERVER adds to the library's; the wire carries them as
+ * strings, and the list in PluginWarning.kind's comment (plugin/v1/status.proto)
+ * is kept equal to this one because the SDK docs are generated from it.
+ */
 export const SERVER_WARNING_KINDS = {
   componentIgnored: "component-ignored",
+  /** A system-content row the plugin took over in place (members.ts, judgeSlug). */
+  memberAdopted: "member-adopted",
   modelHintUnresolved: "model-hint-unresolved",
   subAgentNameBuiltin: "sub-agent-name-builtin",
   versionNotTaggable: "version-not-taggable",

package/src/domain/plugin/materialize/plan.ts

@@ -19,6 +19,11 @@ import { PluginWarningSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v
 import type { PluginWarning } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
+import {
+  RESERVED_LABEL_TRUE,
+  SYSTEM_LABEL,
+  isSystemContent,
+} from "../../../pipeline/apiresource-labels.js";
 import { SERVER_WARNING_KINDS, VERSION_TAG_PATTERN } from "../constants.js";
 import type { PlannedMember } from "../members.js";
 import type { ParsedOverlays } from "../overlay/documents.js";
@@ -105,24 +110,38 @@ export function planMaterialization(
   );
   const workflows = planWorkflows(overlays.workflows, identity);
 
+  // `system` is read from the labels each member will be written with (the
+  // overlay author's, the plugin's two merged over them). A skill's request
+  // carries only the plugin's two, so a skill never declares system content
+  // and can never adopt a row; the overlay kinds can.
   const members: PlannedMember[] = [
     ...skills.map((skill) => ({
       kind: ApiResourceKind.skill,
       slug: skill.slug,
       name: skill.name,
+      system: skill.request.labels[SYSTEM_LABEL] === RESERVED_LABEL_TRUE,
     })),
     ...mcpServers.map((server) => ({
       kind: ApiResourceKind.mcp_server,
       slug: server.slug,
       name: server.name,
+      system: isSystemContent(server.resource.metadata),
     })),
     ...(agent === undefined
       ? []
-      : [{ kind: ApiResourceKind.agent, slug: agent.slug, name: agent.name }]),
+      : [
+          {
+            kind: ApiResourceKind.agent,
+            slug: agent.slug,
+            name: agent.name,
+            system: isSystemContent(agent.resource.metadata),
+          },
+        ]),
     ...workflows.map((workflow) => ({
       kind: ApiResourceKind.workflow,
       slug: workflow.slug,
       name: workflow.name,
+      system: isSystemContent(workflow.resource.metadata),
     })),
   ];
 

package/src/domain/plugin/members.ts

@@ -8,14 +8,17 @@
  * pattern.
  *
  * The same module answers the two questions a push asks before any write:
- * which planned slugs are already held in the organization, and by whom
- * (this plugin: an upgrade; another plugin or an unmanaged resource: a
- * refusal naming the holder); and whether the plugin's members already
- * converge on the head's digest (every planned member present, each
- * carrying `stigmer.ai/plugin-version` equal to it), which is what lets a
- * re-push of the same archive return without a child write.
+ * what to do about each planned slug in the organization (`judgeSlug`:
+ * free; ours, an upgrade; system content the plugin replaces, adopted;
+ * another plugin's or a user's, refused naming the holder); and whether the
+ * plugin's members already converge on the head's digest (every planned
+ * member present, each carrying `stigmer.ai/plugin-version` equal to it),
+ * which is what lets a re-push of the same archive return without a child
+ * write.
  *
- * Proven by __tests__/members.test.ts and the conformance suite's
+ * Proven by __tests__/members.test.ts (the slug decision on plain values,
+ * convergence, the dropped set), __tests__/plugin.test.ts (adoption and
+ * refusal through a composed server) and the conformance suite's
  * listMembers, collision and reconcile arms.
  */
 import { fromBinary } from "@bufbuild/protobuf";
@@ -31,6 +34,7 @@ import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/api
 import {
   PLUGIN_LABEL,
   PLUGIN_VERSION_LABEL,
+  isSystemContent,
   pluginIdOf,
 } from "../../pipeline/apiresource-labels.js";
 import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
@@ -56,6 +60,8 @@ export interface Member {
   readonly name: string;
   /** The `stigmer.ai/plugin-version` value it was last materialised from. */
   readonly version: string;
+  /** Whether the stored row carries `stigmer.ai/system` (isSystemContent). */
+  readonly system: boolean;
 }
 
 /** A member the plan intends to exist after this push. */
@@ -63,6 +69,8 @@ export interface PlannedMember {
   readonly kind: ApiResourceKind;
   readonly slug: string;
   readonly name: string;
+  /** Whether the member the plugin brings declares `stigmer.ai/system`. */
+  readonly system: boolean;
 }
 
 function memberOf(
@@ -75,6 +83,7 @@ function memberOf(
     slug: metadata.slug,
     name: metadata.name,
     version: metadata.labels[PLUGIN_VERSION_LABEL] ?? "",
+    system: isSystemContent(metadata),
   };
 }
 
@@ -145,6 +154,66 @@ export async function slugHolder(
   };
 }
 
+/**
+ * What a push does about one planned slug, decided before any write.
+ *
+ *   free              nothing holds it; the member is created
+ *   ours              this plugin's own member; the push is an upgrade
+ *   adopt             system content no plugin manages, and the plugin
+ *                     brings system content for the same slug: the child's
+ *                     apply (upsert-by-slug) rewrites the row in place, so
+ *                     its id, its default instance, every personal instance
+ *                     and every session bound to them survive
+ *   held-unmanaged    a resource no plugin manages and the rule above does
+ *                     not admit; refused naming it
+ *   held-by-plugin    another plugin's member; refused naming that plugin
+ *
+ * Adoption is deliberately narrow, "system replaces system": the held row's
+ * label narrows which rows are eligible (a user's row never carries it on
+ * an edition that enforces reserved labels), and the plugin's own claim to
+ * the label was charged to `can_write_reserved_labels` by the sanitiser
+ * moments before, so the grant is the caller's live permission and never
+ * the label alone (pipeline/apiresource-labels.ts). It never transfers a
+ * member between plugins: another plugin's slug is refused whatever labels
+ * either side carries. The one case it exists for is the platform re-homing
+ * the content it seeded before plugins existed (the default agent; the
+ * platform's own server) without orphaning a single conversation.
+ */
+export type SlugDecision =
+  | { readonly kind: "free" }
+  | { readonly kind: "ours"; readonly holder: Member }
+  | { readonly kind: "adopt"; readonly holder: Member }
+  | { readonly kind: "held-unmanaged"; readonly holder: Member }
+  | {
+      readonly kind: "held-by-plugin";
+      readonly holder: Member;
+      readonly pluginId: string;
+    };
+
+export function judgeSlug(
+  holder: SlugHolder,
+  planned: PlannedMember,
+  pluginId: string,
+): SlugDecision {
+  if (!holder.held) {
+    return { kind: "free" };
+  }
+  if (holder.byPlugin === pluginId) {
+    return { kind: "ours", holder: holder.holder };
+  }
+  if (holder.byPlugin !== undefined) {
+    return {
+      kind: "held-by-plugin",
+      holder: holder.holder,
+      pluginId: holder.byPlugin,
+    };
+  }
+  if (holder.holder.system && planned.system) {
+    return { kind: "adopt", holder: holder.holder };
+  }
+  return { kind: "held-unmanaged", holder: holder.holder };
+}
+
 /**
  * Whether the stored members already ARE the plan at this digest: every
  * planned member present, none extra, each stamped with the digest.

package/src/domain/plugin/push.ts

@@ -19,8 +19,10 @@
  * digest, READY, every member present and stamped with it) the controller
  * returns the head and the install chain never runs, so a re-push writes
  * nothing. Everything that can refuse — the archive, the package, the
- * overlay, a reserved label, a held slug, a missing permission, the level
- * — refuses in the plan chain BEFORE any write; the install chain's own
+ * overlay, a reserved label, a held slug (unless it is system content the
+ * plugin replaces, which is adopted in place: members.ts, judgeSlug), a
+ * missing permission, the level — refuses in the plan chain BEFORE any
+ * write; the install chain's own
  * failures are a child's, wrapped with the plugin's name, and leave a head
  * that says FAILED so the next push of the same archive converges.
  *
@@ -52,6 +54,7 @@ import {
   PluginStatusSchema,
   PluginWarningSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import type { PluginWarning } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import {
@@ -95,7 +98,7 @@ import { requireOperatorMaySetPublic } from "../../pipeline/steps/visibility-gat
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { openPluginArchive } from "./archive.js";
-import { VERSION_TAG_PATTERN } from "./constants.js";
+import { SERVER_WARNING_KINDS, VERSION_TAG_PATTERN } from "./constants.js";
 import type { OpenedPluginArchive } from "./archive.js";
 import type { PluginIdentity } from "./materialize/identity.js";
 import { McpServerOverlayError } from "./materialize/mcp-servers.js";
@@ -105,10 +108,11 @@ import type { PluginMaterializerProvider } from "./materialize/ports.js";
 import {
   droppedMembers,
   findMembers,
+  judgeSlug,
   membersConverge,
   slugHolder,
 } from "./members.js";
-import type { Member } from "./members.js";
+import type { Member, PlannedMember } from "./members.js";
 import { parseOverlays } from "./overlay/documents.js";
 import type { ParsedOverlays } from "./overlay/documents.js";
 import { OverlayParseError } from "./overlay/parse.js";
@@ -339,9 +343,11 @@ export function requestedVisibility(
 
 /**
  * PlanMaterialization — everything the push will write, checked whole:
- * every child slug against the organization (free, ours, or refused
- * naming the holder), the caller's permission for every member kind, and
- * the plugin's current members for the convergence and drop decisions.
+ * every child slug against the organization (free, ours, adopted system
+ * content, or refused naming the holder), the caller's permission for
+ * every member kind, and the plugin's current members for the convergence
+ * and drop decisions. An adopted slug is recorded as a warning on the plan,
+ * so the install receipt says which rows the plugin took over.
  */
 export function newPlanMaterializationStep(
   store: Store,
@@ -376,6 +382,7 @@ export function newPlanMaterializationStep(
         throw error;
       }
 
+      const adopted: PluginWarning[] = [];
       for (const member of plan.members) {
         let holder;
         try {
@@ -383,20 +390,41 @@ export function newPlanMaterializationStep(
         } catch (error) {
           throw internalError(error, "failed to check a member slug");
         }
-        if (!holder.held || holder.byPlugin === identity.id) {
-          continue;
-        }
+        const decision = judgeSlug(holder, member, identity.id);
         const noun = memberNoun(member.kind);
-        if (holder.byPlugin === undefined) {
-          throw alreadyExistsError(
-            noun,
-            `'${member.slug}' exists in org '${identity.org}' and is not managed by a plugin; rename or delete it first`,
-          );
+        switch (decision.kind) {
+          case "free":
+          case "ours":
+            break;
+          case "adopt":
+            adopted.push(
+              create(PluginWarningSchema, {
+                kind: SERVER_WARNING_KINDS.memberAdopted,
+                path: declaringDocumentOf(overlays, member),
+                message:
+                  `${noun} '${member.slug}' (${decision.holder.id}) was seeded by the platform before this plugin and is now managed by it; ` +
+                  "its definition is the plugin's, and its instances and conversations continue",
+              }),
+            );
+            break;
+          case "held-unmanaged":
+            throw alreadyExistsError(
+              noun,
+              `'${member.slug}' exists in org '${identity.org}' and is not managed by a plugin; rename or delete it first`,
+            );
+          case "held-by-plugin":
+            throw alreadyExistsError(
+              noun,
+              `'${member.slug}' is held by plugin '${await pluginSlugOf(store, decision.pluginId)}'`,
+            );
+          default: {
+            const exhaustive: never = decision;
+            throw internalError(
+              new Error(`unknown slug decision ${JSON.stringify(exhaustive)}`),
+              "failed to check a member slug",
+            );
+          }
         }
-        throw alreadyExistsError(
-          noun,
-          `'${member.slug}' is held by plugin '${await pluginSlugOf(store, holder.byPlugin)}'`,
-        );
       }
 
       const missing: string[] = [];
@@ -452,7 +480,12 @@ export function newPlanMaterializationStep(
       } catch (error) {
         throw internalError(error, "failed to list plugin members");
       }
-      ctx.set(PLUGIN_PLAN_KEY, plan);
+      // An adoption is something this push noticed and did not refuse, so it
+      // rides the plan's warnings onto the install receipt like the rest.
+      ctx.set(PLUGIN_PLAN_KEY, {
+        ...plan,
+        warnings: [...plan.warnings, ...adopted],
+      } satisfies MaterializationPlan);
       ctx.set(EXISTING_MEMBERS_KEY, members);
     },
   };
@@ -986,6 +1019,33 @@ function memberNoun(kind: ApiResourceKind): string {
   return MEMBER_NOUNS.get(kind) ?? ApiResourceKind[kind] ?? String(kind);
 }
 
+/**
+ * The overlay document that declared an adopted member, for the warning's
+ * path: only an overlay can carry the system label, so a skill (whose
+ * request carries the plugin's labels alone) never reaches this.
+ */
+function declaringDocumentOf(
+  overlays: ParsedOverlays,
+  member: PlannedMember,
+): string {
+  switch (member.kind) {
+    case ApiResourceKind.agent:
+      return overlays.agent?.path ?? "";
+    case ApiResourceKind.mcp_server:
+      return (
+        overlays.mcpServers.find((document) => document.server === member.name)
+          ?.path ?? ""
+      );
+    case ApiResourceKind.workflow:
+      return (
+        overlays.workflows.find((document) => document.name === member.name)
+          ?.path ?? ""
+      );
+    default:
+      return "";
+  }
+}
+
 /** The holding plugin's slug for a refusal; a dangling id names itself. */
 async function pluginSlugOf(store: Store, pluginId: string): Promise<string> {
   try {