@jini-ai/agent-plugins 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.5 — 2026-10-12 — retirement waits for usable successors
+
+- `retireBundledAgentPlugins()` (and so the boot seeder) keeps a retired bundled plugin until EVERY
+  successor is installed at the digest `bundled-digests.json` records for it. Before, a successor
+  whose seed had failed still got an activation record and the predecessor was removed — a switch
+  with no code behind it. The kept plugin's outcome is `failed` with the reason; the next boot retries.
+- `retiredBundledPlugins` (and the `retired` option) may list several successors for a plugin split
+  across them; such outcomes carry `successorIds` and, when retired, per-successor `successors`.
+  Single-successor outcomes are unchanged.
+
+## 0.4.4 — 2026-10-12 — Agent Plugins 1.1.0
+
+- `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` (and so the installer and MCP
+  projection) select the grammar by `$schema` and accept Agent Plugins 1.1.0 identifiers alongside
+  1.0.0. 1.1.0 changes only the version identifiers, so both map to the same validator; 1.0.0
+  behavior is unchanged. When a `plugin.json` is supplied, `mcp.json` must target the same version
+  (§10).
+- Forward-compatible within major 1 (owner decision): an unknown 1.x (e.g. 1.2.0) is validated with
+  the newest known (1.1.0) grammar and reports one warning naming the version. A different major
+  (2.x, 0.x) is refused as an unsupported major version; a non-canonical `$schema` is refused with
+  the accepted identifiers listed.
+
 ## 0.4.2
 
 - Use shared plugin identity metadata with a required `@jini-ai/core` peer at `^0.4.2`. Repair identity-lock publication syntax and isolate unreadable or invalid installed manifests with warnings so one damaged install cannot block healthy installs or bundled seeding.

package/README.md

@@ -2,9 +2,9 @@
 
 > **Leon, this is you from the past. Do not try to merge `plugins` and `agent-plugins`.**
 
-Support for **Agent Plugins**, an open, vendor-neutral spec (v1.0.0, published 2026-08-06) for
-bundling Agent Skills and MCP servers into one portable directory. Published by a Technical
-Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel.
+Support for **Agent Plugins**, an open, vendor-neutral spec (v1.0.0, published 2026-08-06; v1.1.0 and
+later 1.x manifests are also accepted) for bundling Agent Skills and MCP servers into one portable
+directory. Published by a Technical Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel.
 Source: https://developers.googleblog.com/agent-plugins-package-your-skills-tools-and-more/
 
 If you are an agent reading this cold: this document is written so you don't need the source

package/dist/lifecycle/manifest.d.ts

@@ -2,7 +2,7 @@ export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 export type { PluginManifest, McpManifest, McpServerEntry } from '../manifest.js';
 import type { PluginManifestAuthor } from '../manifest.js';
 export type { PluginManifestAuthor } from '../manifest.js';
-/** Agent Plugins 1.0.0 parsing, with application metadata confined to an explicit namespace. */
+/** Agent Plugins 1.0.0/1.1.0 parsing, with application metadata confined to an explicit namespace. */
 export type AgentPluginServerMetadataReader = (required: {
     readonly serverId: string;
     readonly value: Readonly<Record<string, unknown>>;
@@ -29,7 +29,7 @@ export type ParseAgentPluginManifestResult = {
     readonly errors: readonly string[];
 };
 /**
- * Validates an already-`JSON.parse`d `plugin.json` value against the v1.0.0 grammar.
+ * Validates an already-`JSON.parse`d `plugin.json` value against the 1.0.0/1.1.0 grammar.
  *
  * @throws Nothing — every failure is reported via the returned `errors`, matching this codebase's
  * own convention for expected validation outcomes (`plugin-runtime/manifest.ts`,
@@ -42,7 +42,7 @@ export declare function parseAgentPluginManifest({ value }: {
     readonly identityNamespace?: string;
 }): ParseAgentPluginManifestResult;
 /**
- * The three closed transport variants `mcp.schema.json` v1.0.0 defines. See this file's header for
+ * The three closed transport variants `mcp.schema.json` 1.0.0/1.1.0 defines. See this file's header for
  * the verified field shape of each.
  */
 export declare const MCP_SERVER_TRANSPORTS: readonly ["stdio", "streamable-http", "sse"];
@@ -134,9 +134,10 @@ export type ParseAgentPluginMcpConfigResult = {
     readonly errors: readonly string[];
 };
 /**
- * Validates an already-`JSON.parse`d `mcp.json` value against the v1.0.0 top-level shape:
+ * Validates an already-`JSON.parse`d `mcp.json` value against the 1.0.0/1.1.0 top-level shape:
  * `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }`, then validates each declared
- * server's own transport shape (see this file's header for the three variants).
+ * server's own transport shape (see this file's header for the three variants). When
+ * `pluginManifest` declares a supported version, `mcp.json` must declare the same one (§10).
  *
  * @throws Nothing — see {@link parseAgentPluginManifest}.
  * @complexity O(s) in the number of declared servers.

package/dist/lifecycle/manifest.js

@@ -1,5 +1,5 @@
 /**
- * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins v1.0.0
+ * @file `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` — the Agent Plugins 1.0.0/1.1.0
  * `plugin.json` / `mcp.json` grammar (agent-plugins.org/specification), verified against the live
  * spec rather than inferred from an example manifest.
  *
@@ -10,13 +10,15 @@
  * shares none of those fields and defines no execution/trust/capability model at all — see this
  * feature's own header comment in `install.ts` for why the two formats cannot be unified.
  *
- * Pinned v1.0.0 rules from agent-plugins.org/specification:
+ * Pinned 1.0.0/1.1.0 rules from agent-plugins.org/specification:
  * - `plugin.json`'s `name`: 1-64 chars, lowercase alphanumeric/hyphen/period only, must start and
  *   end alphanumeric, no `--` or `..` consecutive delimiters (§5.5). Valid: `my-plugin`,
  *   `acme.tools`, `lint3r`, `a`. Invalid: `My-Plugin`, `-start`, `has--double`.
- * - `plugin.json`'s `$schema` MUST equal `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`
- *   for this pinned version; `mcp.json`'s MUST equal
- *   `https://agent-plugins.org/schemas/1.0.0/mcp.schema.json`.
+ * - `plugin.json`'s `$schema` MUST be a recognized canonical identifier
+ *   (`https://agent-plugins.org/schemas/<version>/plugin.schema.json`); `mcp.json`'s likewise
+ *   (`.../<version>/mcp.schema.json`), and when both are present their versions MUST match (§10).
+ *   1.0.0 and 1.1.0 are recognized; an unknown 1.x is read with the newest known grammar plus one
+ *   warning; any other major is refused — see `KNOWN_SPEC_VERSIONS`.
  * - Unknown top-level `plugin.json` fields produce warnings but do not block loading — this module
  *   returns them as `warnings`, never as a rejection reason.
  * - `mcp.json`'s top-level shape is `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }` —
@@ -55,11 +57,44 @@
 import { readPluginIdentity, validatePluginIdentity } from "@jini-ai/core/plugin-directory";
 export { validatePluginManifest, validateMcpManifest } from '../manifest.js';
 /**
- * The one plugin.json schema version this loader understands. A manifest declaring any other
- * value is rejected outright rather than guessed at: pinning the grammar must survive spec churn.
+ * The Agent Plugins versions whose schemas have been diffed against this file's grammar. 1.1.0's
+ * spec text and both schemas differ from 1.0.0 only in the version identifiers, so both map to the
+ * one grammar below — §5.1 allows mapping explicitly recognized compatible versions to one
+ * implementation. Add a version here only after diffing its schemas against this grammar.
  */
-const PLUGIN_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
-const MCP_SCHEMA_1_0_0 = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const KNOWN_SPEC_VERSIONS = ["1.0.0", "1.1.0"];
+const SUPPORTED_MAJOR = "1";
+/**
+ * Owner decision (2026-10-12): any other 1.x is accepted with the newest known grammar and one
+ * warning, so a minor spec release does not lock out packages that target it. This goes beyond
+ * §5.1, which says a client MUST reject a version it does not explicitly recognize. Unknown fields
+ * stay tolerated only where the known grammar already allows them (unknown top-level fields warn,
+ * `extensions` is opaque). A different major is refused, since majors may break the grammar.
+ */
+const SCHEMA_URL_PATTERN = /^https:\/\/agent-plugins\.org\/schemas\/((\d+)\.\d+\.\d+)\/(plugin|mcp)\.schema\.json$/;
+/** The canonical `$schema` identifier for one spec version's `plugin.json` or `mcp.json`. */
+function schemaUrl(version, file) {
+    return `https://agent-plugins.org/schemas/${version}/${file}.schema.json`;
+}
+/**
+ * Reads the spec version `value` names as `file`'s canonical schema identifier: a known version,
+ * an unknown 1.x (with its warning), or the error for a different major or a non-canonical value.
+ */
+function readSpecVersion(value, file) {
+    const match = typeof value === "string" ? SCHEMA_URL_PATTERN.exec(value) : null;
+    if (!match || match[3] !== file) {
+        const accepted = KNOWN_SPEC_VERSIONS.map((version) => `'${schemaUrl(version, file)}'`).join(" or ");
+        return { error: `${file}.json '$schema' must be ${accepted} (Agent Plugins ${KNOWN_SPEC_VERSIONS.join(", ")}, or another ${SUPPORTED_MAJOR}.x), got '${String(value)}'` };
+    }
+    const version = match[1];
+    if (match[2] !== SUPPORTED_MAJOR) {
+        return { error: `${file}.json targets Agent Plugins ${version}, an unsupported major version (supported: ${SUPPORTED_MAJOR}.x)` };
+    }
+    if (KNOWN_SPEC_VERSIONS.includes(version))
+        return { version };
+    const newest = KNOWN_SPEC_VERSIONS[KNOWN_SPEC_VERSIONS.length - 1];
+    return { version, warning: `${file}.json targets Agent Plugins ${version}, newer than this loader knows; validated with the ${newest} grammar` };
+}
 /**
  * §5.5's grammar as one regex: alnum runs separated by single `-`/`.` delimiters. This shape alone
  * guarantees start/end are alphanumeric (the regex can only start and end on `[a-z0-9]+`) AND that
@@ -114,7 +149,7 @@ function resolveManifestName(raw) {
     return { name };
 }
 /**
- * Validates an already-`JSON.parse`d `plugin.json` value against the v1.0.0 grammar.
+ * Validates an already-`JSON.parse`d `plugin.json` value against the 1.0.0/1.1.0 grammar.
  *
  * @throws Nothing — every failure is reported via the returned `errors`, matching this codebase's
  * own convention for expected validation outcomes (`plugin-runtime/manifest.ts`,
@@ -127,9 +162,11 @@ export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu"
     const raw = value;
     const errors = [];
     const warnings = [];
-    if (raw.$schema !== PLUGIN_SCHEMA_1_0_0) {
-        errors.push(`plugin.json '$schema' must be '${PLUGIN_SCHEMA_1_0_0}', got '${String(raw.$schema)}'`);
-    }
+    const specVersion = readSpecVersion(raw.$schema, "plugin");
+    if (specVersion.error)
+        errors.push(specVersion.error);
+    else if (specVersion.warning)
+        warnings.push(specVersion.warning);
     if (raw.extensions !== undefined && !isJsonObject(raw.extensions))
         errors.push("plugin.json extensions must be an object");
     const nameResult = resolveManifestName(raw);
@@ -158,7 +195,7 @@ export function parseAgentPluginManifest({ value }, { identityNamespace = "tovu"
     return { ok: true, manifest, warnings };
 }
 /**
- * The three closed transport variants `mcp.schema.json` v1.0.0 defines. See this file's header for
+ * The three closed transport variants `mcp.schema.json` 1.0.0/1.1.0 defines. See this file's header for
  * the verified field shape of each.
  */
 export const MCP_SERVER_TRANSPORTS = ["stdio", "streamable-http", "sse"];
@@ -348,9 +385,10 @@ function parseMcpServerConfig(value, extension) {
     return null;
 }
 /**
- * Validates an already-`JSON.parse`d `mcp.json` value against the v1.0.0 top-level shape:
+ * Validates an already-`JSON.parse`d `mcp.json` value against the 1.0.0/1.1.0 top-level shape:
  * `{ "$schema": ..., "mcpServers": { "<server-id>": {...} } }`, then validates each declared
- * server's own transport shape (see this file's header for the three variants).
+ * server's own transport shape (see this file's header for the three variants). When
+ * `pluginManifest` declares a supported version, `mcp.json` must declare the same one (§10).
  *
  * @throws Nothing — see {@link parseAgentPluginManifest}.
  * @complexity O(s) in the number of declared servers.
@@ -362,8 +400,14 @@ export function parseAgentPluginMcpConfig({ value, extensionNamespace }, optiona
         return { ok: false, errors: ["mcp.json must be a JSON object"] };
     const raw = value;
     const errors = [];
-    if (raw.$schema !== MCP_SCHEMA_1_0_0) {
-        errors.push(`mcp.json '$schema' must be '${MCP_SCHEMA_1_0_0}', got '${String(raw.$schema)}'`);
+    // plugin.json already reports an unknown-1.x warning; mcp.json adds none of its own.
+    const mcpSpec = readSpecVersion(raw.$schema, "mcp");
+    const mcpVersion = mcpSpec.version;
+    const pluginVersion = isJsonObject(optional.pluginManifest) ? readSpecVersion(optional.pluginManifest.$schema, "plugin").version : undefined;
+    if (mcpSpec.error)
+        errors.push(mcpSpec.error);
+    else if (pluginVersion !== undefined && pluginVersion !== mcpVersion) {
+        errors.push(`mcp.json targets Agent Plugins ${mcpVersion} but plugin.json targets ${pluginVersion}; the versions must match`);
     }
     const mcpServers = raw.mcpServers;
     if (typeof mcpServers !== "object" || mcpServers === null || Array.isArray(mcpServers)) {

package/dist/lifecycle/ports.d.ts

@@ -66,7 +66,8 @@ export interface AgentPluginLifecyclePorts {
         readonly pluginId: string;
     }) => string;
     readonly seededEnabledPluginIds: ReadonlySet<string>;
-    readonly retiredBundledPlugins: ReadonlyMap<string, string>;
+    /** Retired bundled plugin id -> the bundled plugin(s) that absorbed it (`retire-bundled.ts`). */
+    readonly retiredBundledPlugins: ReadonlyMap<string, string | readonly string[]>;
     readonly bundledArchiveMagic: string;
     readonly filesystem: FilesystemPort;
     readonly clock: AgentPluginClockPort;

package/dist/lifecycle/retire-bundled.d.ts

@@ -19,6 +19,14 @@
  * ---------------------------------------------------------------------------
  * 1. Nothing installed and no activation record: nothing to do (the second boot after a migration).
  *    A leftover ledger entry is still dropped.
+ * 1a. Otherwise EVERY successor must be usable first: installed at the digest `bundled-digests.json`
+ *    records for it (the build's own seed — the same trust `trusted-plugin-files.ts` demands before
+ *    core takes a contribution from it), whether it seeded this boot or on an earlier one. If any
+ *    is not, the retired plugin is KEPT and the outcome is `failed` with the reason; the next boot
+ *    retries. Without this a successor whose seed failed (a broken `plugin.json`, a full disk) left
+ *    the retired plugin removed and only an activation record for the successor — a switch with no
+ *    code behind it (R6, 2026-10-12). A plugin split into several (`deploy` -> `fly`, `render`, ...)
+ *    is kept until all of them are usable: one working successor must not cost the others' capability.
  * 2. The retired plugin was ENABLED (explicitly, or by the "absent means active" default while its
  *    package is installed): the successor is switched on — unless an operator explicitly turned the
  *    successor off, which is left exactly as it is and reported in the outcome. No silent override.
@@ -47,13 +55,17 @@ import type { AgentPluginLifecyclePorts } from "./ports.js";
 /** What happened to the successor. `not-needed`: the retired plugin was off, so the successor was
  *  left as it was. The other three are {@link BundledAgentPluginEnableOutcome}. */
 export type RetiredAgentPluginSuccessorOutcome = BundledAgentPluginEnableOutcome | "not-needed";
-export type RetiredAgentPluginOutcome = {
-    readonly pluginId: string;
+/** `successorId` is the (first) successor; `successorIds` is present only when the map entry lists
+ *  several, and then names every one in map order. */
+interface RetiredAgentPluginSuccessors {
     readonly successorId: string;
+    readonly successorIds?: readonly string[] | undefined;
+}
+export type RetiredAgentPluginOutcome = (RetiredAgentPluginSuccessors & {
+    readonly pluginId: string;
     readonly status: "absent";
-} | {
+}) | (RetiredAgentPluginSuccessors & {
     readonly pluginId: string;
-    readonly successorId: string;
     readonly status: "retired";
     /** Every installed archive digest removed; empty when only a record or ledger entry was left. */
     readonly removedDigests: readonly string[];
@@ -62,24 +74,27 @@ export type RetiredAgentPluginOutcome = {
     /** `left-disabled-by-operator` is the one case a caller should surface: the retired plugin was
      *  on, its successor was explicitly turned off, and this step did not override that. */
     readonly successor: RetiredAgentPluginSuccessorOutcome;
-} | {
+    /** Present only with `successorIds`: each successor's own outcome. `successor` is the first's. */
+    readonly successors?: Readonly<Record<string, RetiredAgentPluginSuccessorOutcome>> | undefined;
+}) | (RetiredAgentPluginSuccessors & {
     readonly pluginId: string;
-    readonly successorId: string;
     readonly status: "failed";
     readonly reason: string;
-};
+});
 export interface RetireBundledAgentPluginsRequired {
     /** The INSTANCE-level layout, for the same reason `seed-bundled.ts` takes one. */
     readonly layout: AgentPluginLayout;
     readonly workspaceId: string;
 }
 export interface RetireBundledAgentPluginsOptional {
-    /** Defaults to {@link RETIRED_BUNDLED_AGENT_PLUGINS}; tests pass their own. */
-    readonly retired?: (ReadonlyMap<string, string>) | undefined;
+    /** Defaults to the host's `retiredBundledPlugins` port; tests pass their own. A value lists
+     *  several successors when the retired plugin was split across them. */
+    readonly retired?: (ReadonlyMap<string, string | readonly string[]>) | undefined;
     readonly now?: ((required: Record<string, never>) => Date) | undefined;
 }
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createRetireBundledModule(ports: AgentPluginLifecyclePorts): {
     retireBundledAgentPlugins: (required: RetireBundledAgentPluginsRequired, optional?: RetireBundledAgentPluginsOptional) => Promise<readonly RetiredAgentPluginOutcome[]>;
 };
+export {};
 //# sourceMappingURL=retire-bundled.d.ts.map

package/dist/lifecycle/retire-bundled.js

@@ -4,7 +4,7 @@ import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.
 import { createUninstallModule } from "./uninstall.js";
 function buildModule(ports) {
     const { deleteAgentPluginActivation, enableBundledAgentPluginUnlessOperatorDisabled, readAgentPluginActivations, resolveAgentPluginActivation } = createActivationModule(ports);
-    const { removeBundledAgentPluginDigest } = createBundledDigestsModule(ports);
+    const { readBundledAgentPluginDigests, removeBundledAgentPluginDigest } = createBundledDigestsModule(ports);
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
     const { uninstallAgentPlugin } = createUninstallModule(ports);
     /**
@@ -16,41 +16,54 @@ function buildModule(ports) {
    */
     async function retireBundledAgentPlugins(required, optional = {}) {
         const outcomes = [];
-        for (const [pluginId, successorId] of optional.retired ?? ports.retiredBundledPlugins) {
+        for (const [pluginId, successor] of optional.retired ?? ports.retiredBundledPlugins) {
+            const successorIds = typeof successor === "string" ? [successor] : successor;
+            const ids = { successorId: successorIds[0] ?? "", ...(typeof successor === "string" ? {} : { successorIds }) };
             try {
-                outcomes.push(await retireOne(required, optional, pluginId, successorId));
+                outcomes.push(await retireOne(required, optional, pluginId, ids));
             }
             catch (error) {
-                outcomes.push({ pluginId, successorId, status: "failed", reason: error instanceof Error ? error.message : String(error) });
+                outcomes.push({ pluginId, ...ids, status: "failed", reason: error instanceof Error ? error.message : String(error) });
             }
         }
         return outcomes;
     }
     // The successor first: if a later step fails, the operator keeps the capability, and the next boot
     // (which finds this step already done) retries only what is left.
-    async function retireOne(required, optional, pluginId, successorId) {
+    async function retireOne(required, optional, pluginId, ids) {
         const workspaceLayout = required.layout.forWorkspace({ workspaceId: required.workspaceId });
         const workspaceRoot = workspaceLayout.root;
+        const successorIds = ids.successorIds ?? [ids.successorId];
         const verdict = await resolveAgentPluginActivation(workspaceRoot, pluginId);
         if (verdict.verdict === "undetermined") {
-            return { pluginId, successorId, status: "failed", reason: `cannot tell whether '${pluginId}' was enabled: ${verdict.reason}` };
+            return { pluginId, ...ids, status: "failed", reason: `cannot tell whether '${pluginId}' was enabled: ${verdict.reason}` };
         }
-        const installed = (await listInstalledPlugins(workspaceLayout.root)).filter((plugin) => plugin.pluginId === pluginId);
+        const allInstalled = await listInstalledPlugins(workspaceLayout.root);
+        const installed = allInstalled.filter((plugin) => plugin.pluginId === pluginId);
         const hasRecord = Object.hasOwn((await readAgentPluginActivations(workspaceRoot)).plugins, pluginId);
         if (installed.length === 0 && !hasRecord) {
             const ledgerEntryRemoved = await removeBundledAgentPluginDigest({ workspaceRoot, pluginId });
             if (!ledgerEntryRemoved)
-                return { pluginId, successorId, status: "absent" };
-            return { pluginId, successorId, status: "retired", removedDigests: [], activationRemoved: false, ledgerEntryRemoved, successor: "not-needed" };
+                return { pluginId, ...ids, status: "absent" };
+            return { pluginId, ...ids, status: "retired", removedDigests: [], activationRemoved: false, ledgerEntryRemoved, successor: "not-needed", ...(ids.successorIds ? { successors: {} } : {}) };
         }
-        const successor = verdict.verdict === "active"
-            ? await enableBundledAgentPluginUnlessOperatorDisabled({
-                workspaceRoot,
-                pluginId: successorId,
-                actor: `system:retire-${pluginId}`,
-                ...(optional.now !== undefined ? { now: optional.now } : {}),
-            })
-            : "not-needed";
+        const unusable = await unusableSuccessor(workspaceRoot, allInstalled, successorIds);
+        if (unusable !== undefined) {
+            return { pluginId, ...ids, status: "failed", reason: `'${pluginId}' is kept until every successor is usable: ${unusable}` };
+        }
+        const successors = {};
+        for (const successorId of successorIds) {
+            successors[successorId] =
+                verdict.verdict === "active"
+                    ? await enableBundledAgentPluginUnlessOperatorDisabled({
+                        workspaceRoot,
+                        pluginId: successorId,
+                        actor: `system:retire-${pluginId}`,
+                        ...(optional.now !== undefined ? { now: optional.now } : {}),
+                    })
+                    : "not-needed";
+        }
+        const successor = successors[ids.successorId] ?? "not-needed";
         let removedDigests = [];
         if (installed.length > 0) {
             removedDigests = (await uninstallAgentPlugin({ layout: required.layout, workspaceId: required.workspaceId, pluginId }, { retiredBundled: true })).removedDigests;
@@ -59,7 +72,22 @@ function buildModule(ports) {
             await deleteAgentPluginActivation({ workspaceRoot, pluginId });
         }
         const ledgerEntryRemoved = await removeBundledAgentPluginDigest({ workspaceRoot, pluginId });
-        return { pluginId, successorId, status: "retired", removedDigests, activationRemoved: hasRecord, ledgerEntryRemoved, successor };
+        return { pluginId, ...ids, status: "retired", removedDigests, activationRemoved: hasRecord, ledgerEntryRemoved, successor, ...(ids.successorIds ? { successors } : {}) };
+    }
+    /** Why one of `successorIds` cannot take over yet, or `undefined` when every one is installed at the
+   *  digest the ledger records for it (this file's header, step 1a).
+   *  @complexity O(s * n) for s successors over n installed packages; both are small bundled counts. */
+    async function unusableSuccessor(workspaceRoot, allInstalled, successorIds) {
+        const ledger = await readBundledAgentPluginDigests(workspaceRoot);
+        for (const successorId of successorIds) {
+            const digest = ledger.get(successorId);
+            if (digest === undefined)
+                return `successor '${successorId}' has never been seeded into this workspace`;
+            if (!allInstalled.some((plugin) => plugin.pluginId === successorId && plugin.archiveDigest === digest)) {
+                return `successor '${successorId}' is not installed at its seeded digest`;
+            }
+        }
+        return undefined;
     }
     return { retireBundledAgentPlugins };
 }

package/dist/lifecycle/seed-bundled.js

@@ -115,6 +115,8 @@ function buildModule(ports) {
     // once its bytes are actually on disk for this workspace.
     // AFTER seeding and the ledger: a retired plugin's successor is itself bundled, so its record and
     // its ledger entry exist by now, and the retirement only has to decide whether to switch it on.
+    // A successor whose seed FAILED has neither; `retire-bundled.ts` then keeps the retired plugin
+    // rather than remove it in favour of a switch with no code behind it (its header, step 1a).
     async function seedBundledAgentPlugins(required) {
         const { layout, workspaceId, sourceRoot } = required;
         const pluginDirNames = await listBundledPluginDirs(sourceRoot);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jini-ai/agent-plugins",
-  "version": "0.4.3",
-  "description": "Support for Agent Plugins, the open, vendor-neutral spec (v1.0.0, published 2026-08-06, Technical Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel) for bundling Agent Skills and MCP servers into one portable directory: PluginManifest/McpManifest types + structural validators on the package root, plus the bundled plugins themselves, each on a subpath named for itself (./ui-ux-design). Extracted 2026-08-18 from @jini-ai/plugins, which now only reserves the unrelated, unimplemented ./host format.",
+  "version": "0.4.5",
+  "description": "Support for Agent Plugins, the open, vendor-neutral spec (v1.0.0, published 2026-08-06; v1.1.0 and later 1.x manifests are also accepted; Technical Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel) for bundling Agent Skills and MCP servers into one portable directory: PluginManifest/McpManifest types + structural validators on the package root, plus the bundled plugins themselves, each on a subpath named for itself (./ui-ux-design). Extracted 2026-08-18 from @jini-ai/plugins, which now only reserves the unrelated, unimplemented ./host format.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",